13. Troubleshooting

13.1 Logging

Logging can be useful to help track down system errors.

13.1.1 Unity Console

Always check the Unity Console for important messages from the FMOD Studio Integration.

The FMOD logs are in the Unity console logs. You can set the logging level in the FMOD Integration Settings.

13.1.2 Development Builds

The FMOD logs can be found in the Unity log files, these can be found here: https://docs.unity3d.com/Manual/LogFiles.html

13.1.3 Logging Level

You can set the logging level with the logging level setting, the default value of which is warning.

13.2 Live Update

Make sure Live Update is enabled in the FMOD Unity Settings, Port 9264 is the default, and that your application has networking permissions.

13.3 Assembly Reference Error

Unity 2018.4.12 and below do not include some assemblies referenced by FMODUnity.asmdef and FMODUnityEditor.asmdef. In these versions of Unity you will see these messages:

To fix these errors:

1. Select Assets/Plugins/FMOD/FMODUnity.asmdef.
2. In the Inspector, select each (Missing reference) item in the References area and click on the minus button to remove it.
   
3. Click the Apply button to apply your changes.
4. Select Assets/Plugins/FMOD/src/Editor/FMODUnityEditor.asmdef.
5. In the Inspector, select each (Missing reference) item in the References area and click on the minus button to remove it.
   
6. Click the Apply button to apply your changes.

13.4 Compile Errors When Upgrading from 1.10

Due to changes in the plugin file layout, upgrading to FMOD for Unity 2.02 from version 1.10 will produce compile errors similar to the following:

Assets\Plugins\FMOD\src\Editor\StudioGlobalParameterTriggerEditor.cs(21,9): error CS0246: The type or namespace name 'EditorParamRef' could not be found (are you missing a using directive or an assembly reference?)
Assets\Plugins\FMOD\src\Editor\SetupWizard.cs(146,16): error CS0246: The type or namespace name 'StagingSystem' could not be found (are you missing a using directive or an assembly reference?)

To resolve this issue, complete the manual upgrade steps.

13.5 EventNotFoundException

• Check that you've placed the Event into a Bank in the FMOD Studio Tool
• Check that the Bank is being loaded by a FMOD Studio Bank Loader component or your own script
• Check the Script Execution Order to make sure the code that loads the Bank runs before code that looks up the event

13.6 BankLoadException

• Check that any DSP plugins you've referenced in the tool are added in the FMOD Unity Integration Settings.
• Check that the file has been copied into the Streaming Assets folder correctly.

13.7 NullPointerException

• Most FMOD API functions return an FMOD.RESULT to indicate an error instead of throwing an exception. If you ignore the return code then objects such as ParameterInstance, EventInstance, EventDescription may be null and any function you attempt to call on it will result in NullPointerException.

13.8 DllNotFoundException

• This can occur in players built without the Development Build option set, but with the DEVELOPMENT_BUILD symbol defined. Logging binaries are required if the DEVELOPMENT_BUILD symbol is defined. To force use of logging binaries enable the Settings.EditorSettings.Instance.ForceLoggingBinaries.

Example:

BuildPlayerOptions options = BuildPlayerWindow.DefaultBuildMethods.GetBuildPlayerOptions(new BuildPlayerOptions());
options.extraScriptingDefines = new string[] { "DEVELOPMENT_BUILD" };

FMODUnity.Settings.EditorSettings.Instance.ForceLoggingBinaries = true;

BuildPipeline.BuildPlayer(options);

• Building for macOS from Windows while using Git can cause this, see Source Control Git for more information.

13.9 Disabling Unity Audio

We recommend that you disable the built-in Unity audio for all platforms, to prevent it from consuming system audio resources that the FMOD Engine needs. However, both systems will work side-by-side on:

• Windows
• Universal Windows Platform
• Linux
• macOS
• iOS
• Android
• PS4 / PS5
• Switch

They will not work together on:

• Xbox One / Xbox Series X|S

The Disable Unity Audio option can be found in: 'Edit > Project Settings > Audio':

13.10 Checking the Plugin Version

To check the plugin version, select FMOD > About Integration from the Unity menu bar:

13.11 Copying File Failed

If you attempt to update without first deleting the platform libs you may encounter an error:

This is because the file is a DLL and is currently in use by the Editor. The only course of action is to start the update steps again. If you ignore these errors it can lead to ERR_HEADER_MISMATCH when running or ERR_FORMAT when loading Banks.

13.12 Output Forced to NO SOUND Mode

You may see this message in the log when your game starts:

[FMOD] Initialization failed : Output forced to NO SOUND mode

This can be caused by the built-in Unity audio system conflicting with FMOD. To resolve it, try disabling the built-in Unity audio.

13.13 Cannot FMOD_OPENMEMORY_POINT Encrypted Data

FMOD.Studio.System.loadBankMemory is not compatible with FMOD.Studio.ADVANCEDSETTINGS::encryptionkey, using them together will cause an error to be returned.

The integration will use loadBankMemory on Android when using TextAssets or APK expansion files (OBB).

13.14 Built-in Speed Parameters and Doppler don't work

In order calculate the value of built-in Speed (Relative) and Speed (Absolute) parameters, as well as the behavior of dependent functionality such as Doppler, FMOD must be provided with accurate velocity values for events and/or listeners.

By default, the Studio Event Emitter component will grab velocity from a Rigidbody or Rigidbody2D component attached to the same object. If there is no Rigidbody present, the velocity of the event will not be passed to FMOD unless you enable StudioEventEmitter::NonRigidbodyVelocity.

When using a Rigidbody, methods that involve taking control of a Rigidbody's physics, such as Rigidbody.MovePosition(), will cause changes in velocity to not be calculated by Unity. In turn, when the resulting velocity value is passed to FMOD via FMOD.Studio.System.setListenerAttributes and FMOD.Studio.EventInstance.set3DAttributes, built-in Speed parameters and Doppler will also be unaffected.

This can be fixed by setting a Rigidbody's isKinematic property to true, a Rigidbody2D's bodyType property to an option other than RigidbodyType2D.Kinematic. or using Rigidbody methods that allow Unity's physics system to handle movement, such as Rigidbody.AddForce() or Rigidbody2D.AddForce().

13.15 Accessing RuntimeManager Outside of Runtime

Attempting to call into RuntimeManager from outside of runtime will cause the following error to be logged:

[FMOD] RuntimeManager accessed outside of runtime. Do not use RuntimeManager for Editor-only functionality, create your own System objects instead.

This is because RuntimeManager releases its FMOD.Studio.System object in the Unity function MonoBehaviour.OnDestroy(), which is only called when a Scene or game ends. If RuntimeManager was to create a system after being called into from Editor-only code, MonoBehaviour.OnDestroy() would never be called, thus leaking the created FMOD.Studio.System object.

As a result, if you need to access the FMOD Engine outside of runtime, you should create and initialize your own FMOD.Studio.System object to act on, and then release it once you are finished with it. For more information on doing so, see the Creating the Studio System section of the FMOD Engine User Manual.

13.16 Cannot Find Events or Buses with Strings

This usually happens because the strings bank file has not been loaded. The strings bank is denoted with the file type .strings.bank, and includes all the metadata required to look up events, buses, snapshots, and VCAs by their paths during runtime. In the event that a path lookup is performed while the strings bank isn't loaded, the error FMOD.Result.ERR_EVENT_NOTFOUND will occur, which will either be logged to the Unity Console, or directly returned from the Studio API function being called.