7. Tools

7.1 Event Reference Updater

This tool will scan all the scenes, prefabs and ScriptableObjects in your project for issues with event references and guide you through the process of resolving them. It is useful for:

• Fixing EventReference fields that have mismatches between path and GUID (e.g. after renaming events in FMOD Studio)
• Migrating your project from version 2.01 or earlier (which uses the [FMODUnity.EventRef] attribute) to version 2.02 or later (which uses the FMODUnity.EventReference type)

7.1.1 Usage

To access the tool, select the FMOD/Update Event References menu item. Click Scan to scan your project for issues. For each issue that is found, a task will be added to the table. You can then:

• Select individual tasks to view their details and execute them one by one
• Use the checkboxes to select or deselect tasks for bulk execution
• Click the "Execute N Selected Tasks" button to bulk execute all selected tasks

7.1.2 Manual Tasks

Some tasks require script editing, and cannot be executed automatically. These tasks are indicated with a "Manual task:" prefix in the description, and have no checkbox. To complete these tasks, select them and follow the instructions that are shown.

Add an EventReference field to hold 'X' from Y

This task is generated when the updater finds a component with an [FMODUnity.EventRef] field named Y that has a value, but no corresponding EventReference field. The recommended action is to add an EventReference field to hold the value from the [FMODUnity.EventRef] field.

For example, this code:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef]
    public string EventPath;

    // (remainder of class removed for brevity)
}

Could generate an Add an EventReference field to hold 'event:/Ambience/Country' from EventPath task with these instructions:

The EventPath field on component EventTrigger has an [FMODUnity.EventRef] attribute with no migration target specified.
* Edit Assets/EventTrigger.cs and add an EventReference field:
    public FMODUnity.EventReference yourNewFieldName; // Pick a new field name
* Change the [FMODUnity.EventRef] attribute on EventPath to:
    [FMODUnity.EventRef(MigrateTo="yourNewFieldName")]
* Re-scan your project.

To resolve this, edit the code to add an EventReference field, and add a matching MigrateTo property to the [FMODUnity.EventRef] attribute:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef(MigrateTo="EventToTrigger")]
    public string EventPath;

    public FMODUnity.EventReference EventToTrigger;

    // (remainder of class removed for brevity)
}

Then click Scan in the updater to re-scan your project; it should now generate an automatic task to migrate the value from EventPath to EventToTrigger.

Add an EventReference field named X to hold 'Y' from Z

This task is generated when the updater finds a component that has an [FMODUnity.EventRef] field with a MigrateTo property, but there is no matching EventReference field. The recommended action is to add an EventReference field that matches the MigrateTo property.

For example, this code:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef(MigrateTo="EventToTrigger")]
    public string EventPath;

    // (remainder of class removed for brevity)
}

Could generate an Add an EventReference field named EventToTrigger to hold 'event:/Ambience/Country' from EventPath task with these instructions:

The EventPath field on component EventTrigger has an [FMODUnity.EventRef(MigrateTo="EventToTrigger")] attribute, but the EventToTrigger field doesn't exist.
* Edit Assets/EventTrigger.cs and add an EventReference field named EventToTrigger:
    public FMODUnity.EventReference EventToTrigger;
* Re-scan your project

To resolve this, edit the code to add an EventReference field named EventToTrigger:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef(MigrateTo="EventToTrigger")]
    public string EventPath;

    public FMODUnity.EventReference EventToTrigger;

    // (remainder of class removed for brevity)
}

Then click Scan in the updater to re-scan your project; it should now generate an automatic task to migrate the value from EventPath to EventToTrigger.

Fix conflicting migration targets on fields X and Y

This task is generated when the updater finds a component with multiple [FMODUnity.EventRef] fields that all have the same MigrateTo property. The recommended action is to modify the MigrateTo properties so they all have different values.

For example, this code:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef(MigrateTo="EventToTrigger")]
    public string EventPath1;
    [FMODUnity.EventRef(MigrateTo="EventToTrigger")]
    public string EventPath2;

    public FMODUnity.EventReference EventToTrigger;

    // (remainder of class removed for brevity)
}

Could generate a Fix conflicting migration targets on fields EventPath1 and EventPath2 task with these instructions:

Fields EventPath1 and EventPath2 on component EventTrigger have [FMODUnity.EventRef] attributes with the same MigrateTo value.
* Edit Assets/EventTrigger.cs and make sure all [FMODUnity.EventRef] attributes have different MigrateTo values
* Re-scan your project

To resolve this, edit the code so that all MigrateTo properties have different values, and they all have matching EventReference fields:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef(MigrateTo="EventToTrigger1")]
    public string EventPath1;
    [FMODUnity.EventRef(MigrateTo="EventToTrigger2")]
    public string EventPath2;

    public FMODUnity.EventReference EventToTrigger1;
    public FMODUnity.EventReference EventToTrigger2;

    // (remainder of class removed for brevity)
}

Then click Scan in the updater to re-scan your project; it should now generate automatic tasks to migrate the value from EventPath1 to EventToTrigger1, and from EventPath2 to EventToTrigger2.

Remove empty field X

This task is generated when the updater finds a component with an empty [FMODUnity.EventRef] field named X. In this case, the recommended action is to ensure that the field is unused, and then remove the field.
For example, this code:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef]
    public string EventPath;

    public FMODUnity.EventReference EventReference;

    // (remainder of class removed for brevity)
}

Could generate a Remove empty field EventPath task with these instructions:

The EventPath field on component EventTrigger is empty.
* Ensure no other instances of EventTrigger are using the EventPath field
* Edit Assets/EventTrigger.cs and remove the EventPath field

To resolve this, edit the code to remove the declaration of EventPath:

public class EventTrigger : MonoBehaviour
{
    public FMODUnity.EventReference EventReference;

    // (remainder of class removed for brevity)
}

Remove field X

This task is generated when the updater finds a component with an [FMODUnity.EventRef] field named X and a corresponding EventReference field, and both fields have values. In this case, the recommended action is to ensure that the field is unused, and then remove the field.

For example, this code:

public class EventTrigger : MonoBehaviour
{
    [FMODUnity.EventRef]
    public string EventPath;

    public FMODUnity.EventReference EventReference;

    // (remainder of class removed for brevity)
}

Could generate a Remove field EventPath task with these instructions:

The EventPath field on component EventTrigger has value 'event:/Ambience/Country', but the corresponding EventReference field already has a value.
* Ensure no other instances of EventTrigger are using the EventPath field
* Edit Assets/EventTrigger.cs and remove the EventPath field

To resolve this, edit the code to remove the declaration of EventPath:

public class EventTrigger : MonoBehaviour
{
    public FMODUnity.EventReference EventReference;

    // (remainder of class removed for brevity)
}

Ensuring that a Field is Unused

Before removing a field from a component, it is a good idea to ensure that it is not used anywhere in your project. To do this, scan your project and check the results for any tasks (other than Remove field X or Remove empty field X) that reference it. Resolve these tasks before removing the field.

7.1.3 GUID/Path Mismatches

If you rename or move events in FMOD Studio, this can cause GUID/path mismatches on references to those events in your game. FMOD for Unity will detect these changes when it refreshes your banks and prompt you to run this tool:

When a mismatch is detected, this tool can either update the GUID to match the path, or update the path to match the GUID:

• If the path is empty, it is updated to match the GUID
• If the GUID is empty, it is updated to match the path
• If neither path nor GUID are empty, the Event Linkage setting controls which one is updated