Master Audio

Export

Use the Master Audio integration when character abilities, damage, items, footsteps, and impacts should play through Master Audio Sound Groups. Ultimate Character Controller components keep their normal Audio Config fields, while Master Audio owns Variations, pooled voices, buses, spatial settings, and most playback behavior.

The Audio Manager has one active module. Replacing it routes every Opsive Shared audio request in the scene through Master Audio, including sounds from another installed Opsive product.

Supported package boundary

The current local integration project was verified with Ultimate Character Controller 3.3.3, Opsive Shared 2.1.0, Unity 2022.3.62f3, and Master Audio 2024 v1.0.3. The bridge does not declare a minimum or maximum Master Audio version, so this is a source-verified combination rather than a general compatibility range. Import the package offered for the released Ultimate Character Controller Version 3 product, then compile and test the workflow on this page before migrating all project audio.

Master Audio includes a small MA_Opsive.unitypackage in its third-party integrations folder. That older bridge routes by Audio Clip name and does not include the current Master Audio Config, Variation, or Require Group Name workflow. Use the current Opsive MasterAudio.unitypackage from the Opsive Downloads page and do not import both bridges.

Before you begin

Back up or commit the project before replacing the scene’s global audio module.
Install Master Audio and allow Unity to finish compiling.
Add and configure the Master Audio GameObject by following the Master Audio documentation.
In Master Audio’s Group Mixer, create at least one Sound Group with a playable Variation. Confirm that this group plays before connecting Ultimate Character Controller.
Open Tools > Opsive > Ultimate Character Controller > Integrations Manager, find Master Audio, and follow its download route. If downloading separately, use the package offered for Ultimate Character Controller Version 3 on Opsive Downloads.
Import MasterAudio.unitypackage with Assets > Import Package > Custom Package. Master Audio must already compile because the bridge directly references its runtime types.

After import, Master Audio Manager Module and Master Audio Config should appear under Assets > Create > Opsive > Audio.

Route Ultimate Character Controller audio through Master Audio

Open Tools > Opsive > Ultimate Character Controller > Setup Manager.
Under Manager Setup, select Add Managers if the scene does not already contain the normal Ultimate Character Controller managers.
In the Hierarchy, select the Game GameObject and locate its Audio Manager component.
Use the included MasterAudioManagerModule asset, or create one with Assets > Create > Opsive > Audio > Master Audio Manager Module.
Assign that asset to Audio Manager Module on the Audio Manager.
Keep Require Group Name enabled for an explicit setup. Every migrated Ultimate Character Controller audio hook must then use a Master Audio Config with Audio Group Name assigned.

Disable Require Group Name only for a clip-name fallback workflow. In that mode the bridge resolves the Ultimate Character Controller Audio Clip and asks Master Audio for a Sound Group whose name exactly matches the clip. It still does not play that Audio Clip directly, so the matching Sound Group and Variation must exist.

Connect a character damage sound

This example routes the Health component’s damage response through a Sound Group named Character Hurt.

In Master Audio, create the Character Hurt Sound Group and add one or more Variations. Configure the group’s spatial, distance, bus, and voice settings for a world-space character sound.
In the Project window, select Assets > Create > Opsive > Audio > Master Audio Config and name the asset CharacterHurtMasterAudio.
Set Audio Group Name to Character Hurt.
Leave Variation set to (Random Variation) to let Master Audio choose according to the Sound Group, or select one Variation for a fixed result. Select [Type In] only when the intended Variation Name cannot be listed.
Use the inherited Audio Modifier only for Volume Override, Pitch Override, or Delay Override when this Ultimate Character Controller use should differ from the Sound Group defaults.
Select the character and open Health > Audio > Take Damage.
Assign CharacterHurtMasterAudio to Audio Config.

With Require Group Name enabled, the inline Audio Clips list is not needed for this route because the Master Audio Sound Group supplies the Variations. Keeping source clips elsewhere can still make it easier to return to the default Opsive module later.

Connect abilities, items, and surfaces

Use the same Master Audio Config pattern anywhere Ultimate Character Controller exposes Audio Config or an Audio Clip Set:

Assign configs to an ability’s Start and Stop Audio Clip Sets for short activation feedback or a long-running ability sound.
Use Health > Audio > Heal and Death for separate character groups, and the Respawner’s Respawn Audio Clip Set for return feedback.
Assign configs to item actions and effects for firing, reloading, melee, magic, pickup, and other item sounds.
On a Surface Effect, assign a Master Audio Config to Audio > Audio Config for footsteps, impacts, or collisions. Master Audio receives the originating transform when available, otherwise the world hit position.

Changing Audio Manager Module is global rather than per sound. Audit each Opsive Audio Config and Audio Clip Set after the switch. With Require Group Name enabled, a remaining standard Audio Config or inline clip cannot identify a Master Audio Sound Group and will be silent.

Choose pooling, loops, fades, and movement behavior

Master Audio owns the Variation Audio Sources, pooling, Sound Group voice limits, buses, 2D or 3D spatial behavior, reverb, and loop rules. Configure those choices on the Master Audio Sound Group and its Variations, not on the inherited Ultimate Character Controller Audio Source fields.

Configure loops on the Master Audio Variation. The bridge does not use the Ultimate Character Controller Loop Override.
Configure Variation fade-in and natural fade-out behavior in Master Audio. An Ultimate Character Controller stop request is abrupt: the supplied bridge does not call Master Audio’s fade methods.
The bridge starts transform-based audio at the transform’s current location but does not use Master Audio’s follow-transform API. Short actions such as footsteps and weapon impacts are a natural fit. A long or looping 3D sound on a moving character needs a project-specific module or a separate Master Audio setup that follows the transform.
Stopping an Ultimate Character Controller sound calls Master Audio’s stop-all operation for the source transform. Other Master Audio sounds triggered by that same transform stop too. Use separate playback transforms or a custom module when independent long-running sounds must stop separately.

Editor checkpoint

Before entering Play Mode, confirm that:

Master Audio and the Opsive bridge compile without errors;
the scene has one active Master Audio GameObject and one Opsive Audio Manager;
Audio Manager Module references MasterAudioManagerModule;
Require Group Name matches the explicit-config or clip-name fallback workflow;
each explicit Master Audio Config has a valid Audio Group Name;
a selected Variation belongs to that Sound Group, or random Variation selection is intentional;
every referenced Sound Group has at least one playable Variation; and
Master Audio owns the intended bus, voice, pooling, spatial, loop, and fade settings.

Verify in Play Mode

Damage the character without killing it. Confirm that Character Hurt plays once and Master Audio shows the active voice in the expected Sound Group.
Repeat the damage several times. A random config should follow the Sound Group’s Variation rules; a fixed Variation should remain consistent.
Trigger one ability or item sound and confirm that it also routes through Master Audio. This verifies that the Audio Manager module is global rather than Health-specific.
Walk across a configured surface or trigger a configured impact. Confirm that the sound uses the intended world position and 3D distance behavior.
Test one loop or delayed sound. Confirm that Master Audio, plus any supported volume, pitch, or delay override, produces the intended result.
Stop a long-running ability sound while another sound is active on the same character transform. Confirm whether the bridge’s stop-all behavior is acceptable for that design.
Reload the gameplay scene and repeat one character and one surface or item sound to verify initialization order in the real scene.

Saving and multiplayer

The integration redirects runtime playback; it does not add save data. Keep Sound Groups and Master Audio Config assets in source control. Save user volume, bus, or audio-option choices through the project’s normal settings system or the corresponding Master Audio workflow.

The bridge calls the local Master Audio API and does not use MasterAudioMultiplayerAdapter or replicate sounds. An Ultimate Character Controller networking add-on can replicate the gameplay event, but the project must decide which client plays the resulting audio. Trigger it on the appropriate authority or receiving clients to avoid silence or duplicate playback. Master Audio’s optional multiplayer packages are separate and must match the installed Master Audio release.

Troubleshooting

Symptom	Check	Fix
Importing the bridge creates `DarkTonic.MasterAudio` errors	Master Audio may not be installed or compiling before the Opsive scripts.	Install and compile Master Audio first, then reimport the current Opsive bridge.
Master Audio Config, Variation, or Require Group Name is missing	The project may contain Master Audio’s bundled `MA_Opsive.unitypackage` instead of the current Opsive package.	Remove the older bridge files and import the Ultimate Character Controller Version 3 `MasterAudio.unitypackage` from Opsive Downloads. Do not keep both.
No Ultimate Character Controller sound plays after assigning the module	Check the Master Audio GameObject, Audio Manager Module, Console, and requested Sound Group.	Keep both managers active, assign `MasterAudioManagerModule`, and fix the first runtime or missing-group error.
A direct Audio Clip worked before the module change but is now silent	Require Group Name is enabled and the Ultimate Character Controller hook has no Master Audio Config.	Assign a config with Audio Group Name, or use the fallback only after creating a same-named Sound Group for the clip.
Audio Group Name or Variation has no useful choices	The Master Audio GameObject, Sound Group, or Variations may not exist in the current scene.	Create or import them, then reselect the config so its Inspector can refresh the list.
The selected Variation does not play	Compare Variation or Variation Name with the direct children of the selected Sound Group.	Select an existing Variation or return to (Random Variation).
A character sound is 2D, too quiet, or routed to the wrong bus	The inherited Ultimate Character Controller spatial and output fields do not drive this module.	Correct the Master Audio Sound Group and Variation Audio Source settings.
A looping sound stays behind when the character moves	The bridge uses position-at-start playback rather than Master Audio’s follow-transform call.	Use a project-specific Audio Manager module or a direct Master Audio follow setup for that long-running sound.
Stopping one ability sound also stops another sound	Both sounds were triggered by the same character transform.	Use separate playback transforms or customize the module for group- or Variation-specific stopping.
A fade-out configured in Ultimate Character Controller is ignored	The bridge stops all sounds for the transform abruptly and does not use Ultimate Character Controller’s loop or fade-style source overrides.	Configure natural fades in the Master Audio Variation, or customize the stop path when an interrupted sound must fade.
Audio plays twice in a networked game	More than one authority or client is responding to the replicated gameplay event.	Choose one replication/playback policy; the bridge itself does not suppress duplicate network calls.

Developer and runtime reference

The bridge supplies Opsive.Shared.Integrations.MasterAudio.MasterAudioManagerModule, derived from AudioManagerModule, and MasterAudioConfig, derived from AudioConfig. Ultimate Character Controller continues to call Opsive.Shared.Audio.AudioManager; changing the manager module redirects existing Health, ability, item, respawn, and Surface Effect calls without replacing those components.

For transform playback the module calls MasterAudio.PlaySound3DAtTransform. For positioned playback it calls MasterAudio.PlaySound3DAtVector3. Audio Group Name supplies the Sound Group, and Variation optionally supplies one exact Variation. If the call neither plays nor schedules a voice, the bridge returns PlayResult.None.

The module applies volume, pitch, and delay overrides from the individual request first, then from the Master Audio Config. Master Audio owns looping, output routing, stereo pan, spatial blend, reverb, pooling, voice limits, and Variation Audio Sources. The inherited Opsive fields for Audio Source prefabs, sharing or replacing Audio Sources, copying source properties, output, loop, stereo pan, spatial blend, and reverb are not consumed by this module.

Both Stop overloads call MasterAudio.StopAllSoundsOfTransform and return no Audio Source, so a stop by config or PlayResult is not isolated to one Sound Group or Variation. The integration routes Opsive sound-effect playback; it does not turn Ultimate Character Controller audio fields into Master Audio playlists.

The current bridge package has no formal third-party version constraint. Its source and compile boundary were checked with Ultimate Character Controller 3.3.3, Opsive Shared 2.1.0, and Master Audio 2024 v1.0.3. Recheck this minimal workflow whenever upgrading any of those packages.