FMOD

Export

Use the FMOD integration when Ultimate Character Controller should keep choosing and timing gameplay sounds while FMOD owns the event, spatialization, routing, and final playback.

Before you begin

  • Start with a working Ultimate Character Controller Version 3 scene. Confirm at least one ability, item, health, footstep, or impact sound through the normal Opsive audio workflow before changing the scene’s playback module.
  • Install and configure FMOD for Unity first. In Unity, use FMOD > Edit Settings to connect the built banks, FMOD > Refresh Banks after rebuilding them, and FMOD > Event Browser to confirm the intended events are available.
  • Keep the FMOD for Unity integration on the same major line as the FMOD Studio project. Follow the FMOD for Unity user guide for plugin, bank, platform, and licensing setup before troubleshooting the Ultimate Character Controller bridge.
  • Commit or back up the project. Assigning the FMOD module changes the playback owner for every sound routed through the scene’s Opsive Audio Manager.

The released bridge snapshot verified for this page uses Ultimate Character Controller 3.3.3, Opsive Shared 2.1.0, FMOD for Unity 2.02.33, and Unity 2022.3.62f3. The current public FMOD line is 2.03, but the Opsive package does not declare a semantic minimum or maximum. Treat the snapshot as an audited configuration, not a compatibility matrix. For FMOD 2.03, import the current bridge after FMOD and pass the isolated compilation and Play Mode checks below before changing a production scene.

Install the Ultimate Character Controller bridge

  1. Install FMOD for Unity and configure its banks. Resolve all FMOD initialization, bank-loading, and event-browser errors first.
  2. Sign in to Opsive Downloads and download the FMOD integration. It is not included in the base product’s Integrations folder before this download.
  3. Import the downloaded package after FMOD has compiled. Importing it creates Assets/Opsive/UltimateCharacterController/Integrations/FMOD in the project.
  4. Confirm that Unity imported FMODAudioManagerModule.cs and FMODAudioManagerModule.asset, then wait for compilation to finish.
  5. If the scene does not have the standard manager object, open Tools > Opsive > Ultimate Character Controller > Setup Manager, select Manager Setup, and use Add Managers.
  6. Select the scene’s Game object and find its Audio Manager component.
  7. Assign FMODAudioManagerModule.asset to Audio Manager Module.
  8. Select the module asset. Assign Default Audio Config only when an Opsive audio request without its own Audio Config should use that shared set of placeholder clips.
  9. Add at least one direct event mapping as described below, save the scene, and test that mapping before converting the rest of the project’s sounds.

The included asset is the normal starting point. To maintain a separate mapping asset for another project or test scene, use Assets > Create > Opsive > Audio > FMOD Audio Manager Module and assign the new asset to Audio Manager Module.

Map Ultimate Character Controller clips to FMOD events

The bridge preserves the Opsive Audio Clip Set and Audio Config workflow, but it uses each selected Unity AudioClip as an identifier. It does not play that clip’s waveform.

For a direct mapping:

  1. Create or reuse an Opsive Audio Config and add one placeholder AudioClip for each sound choice.
  2. Select FMODAudioManagerModule.asset and expand Audio Clip Event Mappings.
  3. Add an element, assign the placeholder to Audio Clip, and choose the FMOD event in Event Reference.
  4. Repeat for every placeholder used by the test Audio Config.
  5. Assign the Audio Config to the Ultimate Character Controller feature and trigger it in Play Mode.

Direct mappings are the safest route because the placeholder name and FMOD event hierarchy can change independently while the event reference remains explicit.

Use a naming fallback

If a placeholder has no direct mapping, the module joins Default Event Path Prefix and AudioClip.name. The included default is event:/, so an AudioClip named Footstep resolves to event:/Footstep.

For a shared folder, set the prefix to a path such as event:/Characters/Footsteps. A placeholder named Stone then resolves to event:/Characters/Footsteps/Stone; the module inserts the missing slash when needed.

Use this fallback only when names and folders follow a controlled convention. A renamed AudioClip, a moved FMOD event, or a missing bank can make the path invalid without changing the Ultimate Character Controller Audio Config. Use a direct mapping for nested event structures and sounds maintained by different teams.

Keep Opsive clip selection

Audio Config still chooses the placeholder before the bridge resolves an event:

  • Random selects a random mapped placeholder.
  • Sequence advances through the mapped placeholders in order.
  • Index selects the placeholder at the current Audio Config index.

This lets existing ability, item, health, surface, and impact data keep its selection logic. The corresponding FMOD events own the actual audio content and their internal variations.

How audio is routed

The scene Audio Manager remains the entry point used by Ultimate Character Controller. The FMOD module replaces its normal Unity AudioSource playback for every request that reaches that manager.

  • Ultimate Character Controller owns when to request or stop a sound, which Audio Config or AudioClip is selected, and the supported volume, pitch, and delay overrides.
  • The module resolves the placeholder to an FMOD event, creates an event instance, starts it immediately or after the requested delay, and tracks it against the originating GameObject.
  • Immediate 3D playback attaches to the originating GameObject. Delayed playback has an attachment limitation: FMOD removes the still-stopped instance from its attachment list before the scheduled start, and the bridge does not reattach it. A delay spanning a runtime update can therefore leave the event at its initial position. World-position playback intentionally sets an initial fixed position.
  • A 2D FMOD event ignores the supplied GameObject or world position for spatial placement.
  • FMOD owns event instruments, looping, parameters, buses, snapshots, effects, spatial behavior, and bank content.
  • When Ultimate Character Controller stops tracked audio, Allow Fadeout chooses FMOD’s fade-out stop mode; disable it only when that integration-wide stop should be immediate.
  • Cleanup Interval controls how often completed instances are released. Keep the included 0.5 second value unless profiling shows a reason to change it; the Inspector prevents values below 0.1 seconds.

Keep one intended Audio Manager in the scene. This bridge is a scene-wide module, not a per-clip switch between FMOD and Unity AudioSource playback. If a particular system must keep using Unity audio, call that system separately or implement and test a project-owned hybrid module.

Current limitations

The source-verified bridge forwards only Opsive clip selection, volume, pitch, and delay. Configure the following behavior in FMOD rather than expecting Unity AudioSource settings to transfer:

  • Audio Source Prefab, Output Override or an Audio Mixer Group, Stereo Pan, Spatial Blend, and Reverb Zone do not configure the FMOD event.
  • Loop Override does not make an event loop. Author looping in FMOD and ensure the Ultimate Character Controller feature stops the tracked event when the action ends.
  • Share Audio Source, Replace Previous Audio Source, and Copy Existing Audio Source Properties describe the Unity AudioSource pool and do not control FMOD event instances.
  • PlayResult.AudioSource is empty because FMOD playback does not return a Unity AudioSource. The module can still stop a matching tracked event through the Audio Config or returned PlayResult data.
  • FMOD parameters, buses, snapshots, programmer sounds, and custom emitter behavior are not populated automatically from an Opsive Audio Config. Use FMOD components or project code for those features.
  • Bank loading, platform binaries, listener setup, and FMOD Studio content remain FMOD responsibilities. The Ultimate Character Controller package supplies only the Audio Manager module.
  • For a moving 3D source, use an immediate bridge request. If playback must start later, schedule that request in the owning gameplay system and request playback with zero bridge delay at the due time, or use a corrected bridge that attaches on delayed start. The supplied delayed-start path does not retain its moving-object attachment.

When two identical events overlap on the same GameObject, stopping by Audio Config stops all tracked events for that config. Stopping by PlayResult stops one tracked event matching its clip and config; the PlayResult does not expose an FMOD event handle.

Verify in Play Mode

  1. Open a small scene with one Audio Manager, one Ultimate Character Controller character, one Audio Config, and one directly mapped FMOD event.
  2. Enter Play Mode and confirm the Console has no missing FMODUnity types, bank-loading errors, invalid event-reference errors, or missing-mapping warnings.
  3. Trigger the Ultimate Character Controller feature several times. Confirm the mapped event plays once per request and Random, Sequence, or Index chooses the expected placeholder.
  4. Trigger an immediate 3D event and move its source; confirm it follows. Then test a delayed event while moving during the delay: the supplied bridge can retain the initial position. Use a delayed zero-delay request or corrected start-time attachment when following is required. Test world-position playback separately as an intentionally fixed source.
  5. Test one 2D event and confirm that moving the character does not spatialize it.
  6. Apply distinct volume, pitch, and delay overrides in the Audio Config. Confirm those three values reach the FMOD event.
  7. Start an event that Ultimate Character Controller later stops. Confirm Allow Fadeout produces the intended release and that the event does not continue after its gameplay owner ends.
  8. Test an ability, item, health sound, footstep, and impact used by the project. Confirm every placeholder resolves through FMOD and that any default Unity AudioSource on the manager remains idle rather than playing the bridged requests.
  9. Build for the target platform and verify bank inclusion, native FMOD libraries, listener behavior, and spatial playback outside the Editor.

Troubleshooting

Symptom Check Fix
Unity reports missing FMODUnity types after importing the bridge. FMOD for Unity is absent, failed to compile, or was imported after the Ultimate Character Controller package. Install and configure FMOD first, then reimport the current Ultimate Character Controller Version 3 FMOD.unitypackage and resolve the first Console error.
The Console reports [FMOD] No event mapping was found for AudioClip 'SomeClip'. The placeholder has no valid direct mapping and the fallback path does not resolve to a loaded event. Add the clip under Audio Clip Event Mappings, or correct Default Event Path Prefix, the AudioClip name, and the bank content.
An Event Reference is assigned but nothing plays. The event may be absent from loaded banks, the FMOD plugin and Studio project may use different major lines, or FMOD may have failed to initialize. Use FMOD > Refresh Banks and FMOD > Event Browser, match the FMOD major line, and resolve FMOD’s first initialization or bank error.
Every request is silent after assigning the module. Audio Manager Module may reference the wrong asset, or the selected Audio Config may contain no placeholder clips. Assign the included FMODAudioManagerModule.asset, add mapped placeholders, and test one direct mapping in isolation.
A 3D sound does not follow the character. Check whether the FMOD event is 3D and whether bridge Delay is nonzero. Configure a 3D event and test with zero delay. For delayed moving sounds, schedule the zero-delay request at playback time or use a corrected bridge that reattaches on start.
Volume or pitch changes, but pan, mixer, reverb, spatial blend, or looping does not. Those Unity AudioSource settings are outside the module’s forwarded values. Author the behavior in the FMOD event, bus, or snapshot. Use Opsive overrides only for volume, pitch, and delay.
A looping event continues after its ability or item stops. Looping is FMOD-owned and the Ultimate Character Controller feature may not issue a matching stop request. Ensure the feature retains and stops the matching Audio Config or PlayResult, and configure the event’s FMOD release behavior.
The wrong event plays when using the fallback. Another event path may share the clip name, or Default Event Path Prefix points to the wrong folder. Use a direct Event Reference, or make the prefix and placeholder naming convention unambiguous.
Audio works in the Editor but not in a build. Banks or the target platform’s native FMOD libraries may be missing, or the bank source may not be included by CI. Follow the FMOD platform and build guidance, include the built banks and platform package, and test a development build before changing Ultimate Character Controller mappings.
  • Audio explains Audio Clip Sets, Audio Config selection, and the default Unity AudioSource module that this integration replaces.
  • Integrations covers the shared install, isolation, upgrade, and build workflow.
  • Character Foot Effects uses Audio Config assets for footsteps selected by the Surface System.
  • Health exposes damage, healing, and death audio that can route through this module.
  • Item Actions describes the action modules that request item audio.
  • Master Audio is the alternative scene-wide audio backend integration.

Developer and source reference

Opsive.Shared.Integrations.FMOD.FMODAudioManagerModule derives from AudioManagerModule. The included source and asset are packaged at Assets/Opsive/UltimateCharacterController/Integrations/FMOD/; the create menu is Assets > Create > Opsive > Audio > FMOD Audio Manager Module.

The module resolves direct mappings first, then the prefix-and-name fallback. It attaches 3D instances with RuntimeManager.AttachInstanceToGameObject, applies volume/pitch, and schedules delayed starts with the Opsive Scheduler. Attachment occurs before a delayed instance starts; FMOD’s Update can remove the STOPPED instance from its attachment list, and StartTrackedInstance does not reattach it. Instances remain tracked per GameObject for stop and cleanup; completed instances are released on the cleanup interval and destroyed owners’ instances are stopped and released.

The released source snapshot inspected for this page contains Ultimate Character Controller 3.3.3, Opsive Shared 2.1.0, FMOD for Unity 2.02.33, and Unity 2022.3.62f3. FMOD’s current Unity documentation covers the 2.03 line and requires the FMOD for Unity major line to match the FMOD Studio project. The Opsive bridge has no declared cross-version guarantee, so record the tested FMOD/Ultimate Character Controller pair and rerun compilation, event resolution, stop behavior, and target-platform builds after either dependency changes.