# V2 Music Stingers

Phase 72.22.1.7 adds short one-shot music stingers for adaptive music events.
The system maps gameplay event tags to musical phrases that can overlay the
current adaptive music bed without affecting gameplay simulation.

## Source Of Truth

- Contract:
  [MusicStingers_V2_Contract.json](../../ue/Content/V2/Audio/MusicStingers_V2_Contract.json)
- Runtime module: `V2Audio`
- Core types: `EV2MusicStingerTriggerKind`, `FV2MusicStingerBinding`,
  `FV2MusicStingerRequest`, `FV2ResolvedMusicStinger`, and
  `FV2MusicStingerCatalog`
- Builder: `UV2AudioBlueprintLibrary::BuildDefaultMusicStingerCatalog`
- Validator: `UV2AudioBlueprintLibrary::ValidateMusicStingerCatalog`
- Resolver: `UV2AudioBlueprintLibrary::ResolveMusicStinger`
- Registrar: `UV2AudioSubsystem::RegisterMusicStingerCatalog`
- Subsystem route: `UV2AudioSubsystem::TriggerMusicStinger`

## Trigger Coverage

The default `MusicStingerSystem.V2` catalog authors three launch stingers.

| Trigger               | Gameplay event                       | Stinger id                          |
| --------------------- | ------------------------------------ | ----------------------------------- |
| `ItemPickup`          | `Gameplay.Event.ItemPickup`          | `Music.Stinger.ItemPickup.Spark`    |
| `AchievementUnlocked` | `Gameplay.Event.AchievementUnlocked` | `Music.Stinger.Achievement.Fanfare` |
| `DangerSpotted`       | `Gameplay.Event.DangerSpotted`       | `Music.Stinger.Danger.Riser`        |

Each binding targets a `Music.Cue.Stinger.*` cue and a `/Stingers/` audio asset.
Durations are capped as short musical phrases and cooldowns prevent rapid repeat
spam.

## Runtime Behavior

`FV2MusicStingerCatalog::ResolveStinger` validates the event binding, enforces
cooldown from the request's `LastTriggeredSeconds`, and returns a queued
one-shot result with an accepted reason tag such as
`Audio.MusicStinger.Accepted.DangerSpotted`.

`UV2AudioSubsystem` registers the catalog, triggers stingers, stores the last
accepted stinger, and exposes binding count, trigger coverage, last stinger id,
last event tag, and one-shot evidence through `FV2AudioRuntimeSnapshot`.

The stinger system is rollback-cosmetic: it overlays adaptive music only and
does not change gameplay state.

## Validation Commands

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