# V2 Adaptive Music State Machine

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](../../ue/Content/V2/Audio/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](../../ue/Content/V2/Audio/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
```