Audio

Use the Opsive audio system to add varied, spatial sounds to character abilities, health, items, footsteps, impacts, and other gameplay without managing a separate Audio Source for every playback.

The Audio Manager finds or creates an available Audio Source on the object that plays the sound. This lets multiple clips overlap when needed and gives built-in UCC features a common way to play audio.

Add audio to a UCC feature

Most audio-enabled UCC features expose an Audio Clip Set. Examples include Start and Stop on an ability, Take Damage, Heal, and Death on the Health component, and Audio Clip Set on character or item effects.

1. Select the character, item, or scene object that owns the behavior.
2. In the relevant component, ability, effect, or action module, expand its audio field.
3. For a quick, local setup, leave Audio Config empty and add one or more clips under Audio Clips. Each playback chooses a clip at random.
4. Enter Play Mode and trigger the behavior. UCC plays the sound from the object associated with that behavior.

Use inline Audio Clips when the clips belong to one feature only. Use an Audio Config when several features should share the same clips and playback rules.

Create a reusable Audio Config

1. In the Project window, choose Assets > Create > Opsive > Audio > Audio Config.
2. Add the available sounds to Audio Clips.
3. Set Clip Selection to match the intended behavior.
4. If the default source is not suitable, assign an Audio Source Prefab that contains a configured Unity Audio Source.
5. Set only the required values in Audio Modifier. Leave a value at No Override to inherit it from the selected Audio Source.
6. Assign the asset to Audio Config in the feature’s Audio Clip Set. When a config is assigned, its clips replace the inline Audio Clips list.

You can also select AudioClip assets in the Project window and use Assets > Create > Opsive > Audio > One Audio Config From Selected Clips. Use Multi Audio Configs From Clips when each selected clip should receive its own config.

Key choices

Choose a clip

• Random chooses a random entry for each playback and is the default.
• Sequence advances from the first clip to the last, then repeats.
• Index uses AudioClipIndex, which starts at 0 and can be changed from code. Use it when gameplay chooses a specific variation.

An inline Audio Clip Set chooses randomly when a built-in feature plays it without an explicit index. Create an Audio Config when you need Sequence behavior or an Inspector-configured Index mode.

Control overlap and Audio Sources

• Share Audio Source is enabled by default. The manager reuses any available shared source on the same GameObject and creates another when all shared sources are busy.
• Replace Previous Audio Source is disabled by default. Enable it when a new clip should replace an active clip instead of overlapping it.
• Copy Existing Audio Source Properties is enabled by default. When the manager creates another source, it copies the Unity Audio Source settings already on the originating GameObject.
• Audio Source Prefab provides the source settings when no suitable source exists. The prefab must contain an Audio Source component.

For a local 3D sound, play it on the character, visible item, or impact position. For non-spatial UI or narration, use a 2D Audio Source prefab or set Spatial Blend Override to a constant value of 0.

Vary or override playback

The Audio Config’s Audio Modifier can override Output, Loop, Volume, Pitch, Stereo Pan, Spatial Blend, Reverb Zone, and Delay. Float overrides can use a constant or a random range; Loop Override can use a constant or random Boolean. Small random pitch or volume ranges can make repeated footsteps or impacts sound less repetitive.

Configure the scene Audio Manager

The normal UCC setup adds an Audio Manager to the scene’s Game object and assigns the included 3D Audio Manager Module. If no Audio Manager exists, the runtime creates one with a 3D Audio Source, so a basic Audio Clip Set still works.

To add the normal scene managers explicitly:

1. Open Tools > Opsive > Ultimate Character Controller > Setup Manager.
2. In Manager Setup, select Add Managers.
3. Select the Game object and confirm that its Audio Manager component has Audio Manager Module assigned.

For project-wide custom defaults, create an Audio Manager Module from Assets > Create > Opsive > Audio > Audio Manager Module, assign its Default Audio Config, and then assign the module to the scene’s Audio Manager. Use Output Override on an Audio Config when a sound needs a particular Audio Mixer Group.

Verify in Play Mode

Trigger each configured behavior several times and confirm that:

• the sound begins at the expected ability, health, item, surface, or impact event;
• Random or Sequence selection changes clips as configured;
• simultaneous sounds overlap unless Replace Previous Audio Source is enabled;
• 3D sounds follow or originate from the intended object or world position; and
• volume, pitch, delay, looping, and mixer routing match the Audio Source plus any Audio Modifier overrides.

During playback, expand the source GameObject in the Hierarchy. The manager names generated children SharedAudioSource or ReservedAudioSource: <config name>, which helps confirm which source is being used.

Troubleshooting

Related pages

• Quick setup adds the standard scene managers.
• Health uses Audio Clip Sets for damage, healing, and death feedback.
• Jump shows ability-specific audio alongside the common ability Start and Stop sets.
• Character Foot Effects connects footsteps to Surface Effects and Audio Config assets.
• Item actions explains the action and module system that item audio effects participate in.
• Events explains how to react to UCC gameplay events before playing custom audio.
• FMOD and Master Audio replace the default playback module while retaining the Opsive audio data workflow.

Developer reference

The released audio types are in the Opsive.Shared.Audio namespace. Built-in UCC integrations call Audio Clip Sets from their own lifecycle: abilities play their Start and Stop sets, Health plays its Take Damage, Heal, and Death sets, item effects and modules play from the item or visible object, and surface or impact effects can play at a world position. These integrations do not require a separate audio-specific event subscription. For custom behavior, respond to the relevant UCC event and call the audio API from that handler.

Keep the returned PlayResult when you need to stop the exact source started by a call:

using Opsive.Shared.Audio;
using UnityEngine;

public class AlertAudio : MonoBehaviour
{
    [SerializeField] private AudioConfig m_AlertAudioConfig;
    private PlayResult m_PlayResult;

    public void PlayAlert()
    {
        m_PlayResult = AudioManager.Play(gameObject, m_AlertAudioConfig);
    }

    public void StopAlert()
    {
        AudioManager.Stop(gameObject, m_PlayResult);
    }

    public void PlayAlertAt(Vector3 position)
    {
        AudioManager.PlayAtPosition(m_AlertAudioConfig, position);
    }
}

AudioManager also provides overloads for an AudioClip, volume, pitch, delay, looping, AudioConfig, and AudioClipInfo. AudioClipSet provides PlayAudioClip, PlayAtPosition, and Stop when a component should expose the same Inspector workflow used by UCC.