Fighting Game · Guides & deep dives

V2 Adaptive Music State Machine

AdaptiveMusicStateMachine_V2_Contract.json

5sections2 minread1table
Markdown source
On this page

Phase 72.22.1.1 adds the high-level Maya adaptive music state machine that drives the existing V2 dynamic music resolver. It models the gameplay-facing states composers and gameplay engineers need before later horizontal re-sequencing, vertical layering, beat-sync, intensity-curve, stinger, and ducking tasks add more playback detail.

Source Of Truth#

  • Contract: AdaptiveMusicStateMachine_V2_Contract.json
  • Runtime module: V2Audio
  • Core types: EV2AdaptiveMusicState, FV2AdaptiveMusicSubstate, FV2AdaptiveMusicStateDefinition, FV2AdaptiveMusicTransitionRule, FV2AdaptiveMusicStateRequest, FV2ResolvedAdaptiveMusicState, and FV2AdaptiveMusicStateMachine
  • Builder: UV2AudioBlueprintLibrary::BuildDefaultAdaptiveMusicStateMachine
  • Validator: UV2AudioBlueprintLibrary::ValidateAdaptiveMusicStateMachine
  • Resolver: UV2AudioBlueprintLibrary::ResolveAdaptiveMusicState
  • Registrar: UV2AudioSubsystem::RegisterAdaptiveMusicStateMachine
  • Subsystem route: UV2AudioSubsystem::EvaluateAdaptiveMusicState
  • Existing music layer resolver: DynamicMusic_V2_Contract.json

State Graph#

The default graph includes the six required top-level states:

State Default substate Alternate substate Target intensity
Menu Music.State.Menu.Main Music.State.Menu.Pause Ambient
Exploration Music.State.Exploration.FreeRoam Music.State.Exploration.Discovery Ambient
Tension Music.State.Tension.Suspense Music.State.Tension.Alert Tension
Combat Music.State.Combat.Neutral Music.State.Combat.HighPressure Climax
Victory Music.State.Victory.RoundWin Music.State.Victory.MatchWin KOSting
Defeat Music.State.Defeat.RoundLoss Music.State.Defeat.MatchLoss KOSting

Every substate has a Music.Cue.* tag and a priority so designers can add specific authored cues without changing the top-level gameplay state contract.

Transition Graph#

Required transitions are explicit and validated:

  • MenuToExploration
  • ExplorationToTension
  • TensionToCombat
  • CombatToVictory
  • CombatToDefeat
  • VictoryToMenu
  • DefeatToMenu
  • CombatToTension
  • TensionToExploration

The implementation also supports ExplorationToCombat, ExplorationToMenu, TensionToMenu, and CombatToMenu so pause/menu interrupts and ambushes have deterministic routes. Each transition carries a target substate, target EV2MusicIntensity, minimum state age guard, crossfade duration, and Audio.AdaptiveMusic.* reason tag.

Dynamic Music Integration#

FV2ResolvedAdaptiveMusicState includes a FV2DynamicMusicResolveRequest. Accepted transitions set the request stage/music profile, current intensity, and conductor state so the existing dynamic music catalog can resolve the correct stage layer. Exploration and menu feed ambient music, tension maps to the tension layer, combat maps to climax, and victory/defeat map to KO sting.

The state machine is registered on UV2AudioConfigAsset and UV2AudioSubsystem. Runtime snapshots expose state count, transition count, required-state coverage, transition-graph coverage, current state, and current substate.

Validation Commands#

bash
python3 V2/ue/Tools/check-v2-adaptive-music-state-machine.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 V2/ue/Tools/check-v2-dynamic-music.py
python3 -m json.tool V2/ue/Content/V2/Audio/AdaptiveMusicStateMachine_V2_Contract.json
python3 V2/tools/validate-v2-docs.py