# V2 Cross-Fade Transition Effects

## Source Of Truth

- Task: `TODOS.phase-72.72.22.1.8`
- Contract:
  [CrossFadeTransitionEffects_V2_Contract.json](../../ue/Content/V2/Audio/CrossFadeTransitionEffects_V2_Contract.json)
- Core types: `EV2CrossFadeCurve`, `FV2CrossFadeTransitionEffectRule`,
  `FV2CrossFadeTransitionEffectRequest`, `FV2ResolvedCrossFadeTransitionEffect`,
  and `FV2CrossFadeTransitionEffectCatalog`
- Builder:
  `UV2AudioBlueprintLibrary::BuildDefaultCrossFadeTransitionEffectCatalog`
- Validator:
  `UV2AudioBlueprintLibrary::ValidateCrossFadeTransitionEffectCatalog`
- Resolver: `UV2AudioBlueprintLibrary::ResolveCrossFadeTransitionEffect`
- Registrar: `UV2AudioSubsystem::RegisterCrossFadeTransitionEffectCatalog`
- Scheduler: `UV2AudioSubsystem::ScheduleCrossFadeTransitionEffect`

## Curve And Duration Coverage

The default `CrossFadeTransitionEffects.V2` catalog is authored with all launch
fade curve classes and transition ids:

- `Linear`
- `EqualPower`
- `EaseInOut`
- `Music.TransitionEffect.ExplorationVerseToChorus`
- `Music.TransitionEffect.TensionVerseToChorus`
- `Music.TransitionEffect.CombatMainToDefeatKO`
- `Music.Section.Exploration.Verse->Music.Section.Exploration.Chorus`
- `Music.Section.Tension.Verse->Music.Section.Tension.Chorus`
- `Music.State.Combat.Main->Music.State.Defeat.KO`

Each `FV2CrossFadeTransitionEffectRule` carries configurable `FadeOutSeconds`,
`FadeInSeconds`, `OverlapSeconds`, `EV2CrossFadeCurve`, and an
`AudioMod.CrossFadeTransition.*` modulation control. Rules must expose
configurable fade durations and curves, use positive overlap inside both fade
windows, and remain rollback-cosmetic.

## Runtime Behavior

`FV2CrossFadeTransitionEffectCatalog::ResolveTransitionEffect` looks up the
authored source and target segment pair, applies optional request-level fade and
overlap overrides, clamps overlap to the active fade windows, and returns the
incoming start and outgoing end times. Accepted results set
`bUsesSmoothOverlap`, carry the selected curve, and report a stable
`Audio.CrossFadeTransition.Accepted.*` reason tag.

`UV2AudioConfigAsset` owns the default transition-effect catalog.
`UV2AudioSubsystem::RegisterAudioConfig` registers it before beat-synchronized
transition rules so a higher-level music conductor can pair beat timing with
smooth fade envelopes. Runtime snapshots expose the rule count, configurable
duration and curve flags, smooth-overlap coverage, and the last scheduled
transition effect id, target segment, and overlap duration.

## Validation Commands

```bash
python3 V2/ue/Tools/check-v2-cross-fade-transition-effects.py
python3 V2/ue/Tools/check-v2-beat-synchronized-transitions.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/CrossFadeTransitionEffects_V2_Contract.json
```