# V2 Music Intensity Curves

Phase 72.22.1.6 adds music intensity curves for Maya adaptive music. The curve
maps a normalized game intensity metric from 0.0 to 1.0 into music intensity,
adaptive state, horizontal section, and vertical instrument layer targets.

## Source Of Truth

- Contract:
  [MusicIntensityCurves_V2_Contract.json](../../ue/Content/V2/Audio/MusicIntensityCurves_V2_Contract.json)
- Runtime module: `V2Audio`
- Core types: `FV2MusicIntensityCurveBand`, `FV2MusicIntensityCurveRequest`,
  `FV2ResolvedMusicIntensityCurve`, and `FV2MusicIntensityCurveCatalog`
- Builder: `UV2AudioBlueprintLibrary::BuildDefaultMusicIntensityCurveCatalog`
- Validator: `UV2AudioBlueprintLibrary::ValidateMusicIntensityCurveCatalog`
- Evaluator: `UV2AudioBlueprintLibrary::EvaluateMusicIntensityCurve`
- Registrar: `UV2AudioSubsystem::RegisterMusicIntensityCurveCatalog`
- Subsystem route: `UV2AudioSubsystem::EvaluateMusicIntensityCurve`

## Curve Bands

The default `MusicIntensityCurves.V2` catalog defines low, mid, and high bands.

| Game intensity | Band                                     | Target section                    | Layer target                         |
| -------------- | ---------------------------------------- | --------------------------------- | ------------------------------------ |
| 0.00-0.33      | `Music.IntensityCurve.LowAmbient`        | `Music.Section.Exploration.Verse` | Ambient pad                          |
| 0.34-0.69      | `Music.IntensityCurve.MidTension`        | `Music.Section.Tension.Chorus`    | Ambient pad, bass, strings           |
| 0.70-1.00      | `Music.IntensityCurve.HighFullOrchestra` | `Music.Section.Combat.Bridge`     | Bass, drums, brass, melody orchestra |

## Mapping Rules

`FV2MusicIntensityCurveCatalog::EvaluateCurve` clamps the incoming
`GameIntensityAlpha` to 0.0-1.0, finds the matching curve band, and returns the
target `EV2MusicIntensity`, `EV2AdaptiveMusicState`,
`EV2HorizontalMusicSectionRole`, target section id, instrument layers, and layer
ids. Low values explicitly set `bLowAmbientMapping`; high values set
`bHighFullOrchestraMapping`.

The required visible mappings are:

- Low intensity maps to `Ambient`, `Exploration`, `Verse`, and ambient pad.
- Mid intensity maps to `Tension`, `Tension`, `Chorus`, and bass/strings.
- High intensity maps to `Climax`, `Combat`, `Bridge`, and full orchestra layers
  through bass, drums, brass, and melody.

## Runtime Evidence

`UV2AudioConfigAsset` owns the default `FV2MusicIntensityCurveCatalog`.
`UV2AudioSubsystem` registers it, evaluates curve requests, updates current
music intensity, adaptive state, horizontal section, and vertical layer ids, and
exposes band count, registration, metric mapping, low ambient mapping, high full
orchestra mapping, last alpha, last target intensity, last section, and layer
count through `FV2AudioRuntimeSnapshot`.

The curve is rollback-cosmetic: it drives adaptive music playback only and does
not change gameplay simulation state.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-music-intensity-curves.py
python3 V2/ue/Tools/check-v2-tempo-beat-tracking.py
python3 V2/ue/Tools/check-v2-audio-module.py
python3 -m json.tool V2/ue/Content/V2/Audio/MusicIntensityCurves_V2_Contract.json
python3 V2/tools/validate-v2-docs.py
```