Fighting Game · Guides & deep dives

V2 Music Ducking

MusicDucking_V2_Contract.json

4sections1 minread
Markdown source
On this page

Source Of Truth#

  • Task: TODOS.phase-72.72.22.1.10
  • Contract: MusicDucking_V2_Contract.json
  • Core types: EV2MusicDuckingTriggerKind, FV2MusicDuckingRule, FV2MusicDuckingRequest, FV2ResolvedMusicDucking, and FV2MusicDuckingCatalog
  • Builder: UV2AudioBlueprintLibrary::BuildDefaultMusicDuckingCatalog
  • Validator: UV2AudioBlueprintLibrary::ValidateMusicDuckingCatalog
  • Resolver: UV2AudioBlueprintLibrary::ResolveMusicDucking
  • Registrar: UV2AudioSubsystem::RegisterMusicDuckingCatalog
  • Runtime controls: UV2AudioSubsystem::ApplyMusicDucking and UV2AudioSubsystem::ClearMusicDucking

Trigger Coverage#

The default MusicDuckingSystem.V2 catalog reduces the dynamic music bus when priority audio events need foreground space:

  • Dialogue through Audio.Event.Dialogue and Music.Ducking.Dialogue.Sidechain
  • Explosion through Audio.Event.Explosion and Music.Ducking.Explosion.Sidechain
  • ImportantSFX through Audio.Event.ImportantSFX and Music.Ducking.ImportantSFX.Sidechain

Every rule must target V2.DynamicMusic, bind a V2.* sidechain bus, provide attack/hold/release envelope timing, attenuate music below unity, and enable sidechain compression with a threshold and compressor ratio.

Runtime Behavior#

FV2MusicDuckingCatalog::ResolveDucking validates the catalog, matches the incoming FV2MusicDuckingRequest by EV2MusicDuckingTriggerKind and event tag, and returns an accepted FV2ResolvedMusicDucking only when sidechain compression is active. Accepted results publish trigger-specific reason tags for dialogue, explosions, and important SFX.

UV2AudioConfigAsset owns the default catalog. UV2AudioSubsystem registers it, applies accepted ducking results to the active mix by multiplying music volume by the selected target gain, prioritizes voice during dialogue ducking, and exposes runtime snapshot evidence for rule coverage, active sidechain compression, last rule id, and last gain. ClearMusicDucking removes the active ducking multiplier and refreshes the mix.

Validation Commands#

bash
python3 V2/ue/Tools/check-v2-music-ducking.py
python3 V2/ue/Tools/check-v2-music-memory-management.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 V2/tools/validate-v2-docs.py
python3 -m json.tool V2/ue/Content/V2/Audio/MusicDucking_V2_Contract.json