# Adaptive Music Composer Guide

The adaptive music system models Maya-style interactive scoring as data: states,
substates, sections, layers, playlists, transitions, stingers, ducking rules,
and middleware events. It is backend-agnostic, so the same authoring file can
drive the internal audio runtime, Wwise, or FMOD.

## Authoring Model

- Use `MusicState` for broad gameplay contexts: exploration, tension, combat,
  victory, defeat, and menu.
- Use `MusicSubstate` for musical detail such as calm travel, stealth danger,
  light combat, heavy combat, boss, success, failure, main menu, or pause menu.
- Define horizontal `MusicSection` entries for verse, chorus, bridge, low,
  medium, high, intro, ambient, and outro material.
- Define vertical `MusicLayerDefinition` entries for stems such as ambience,
  harmony, melody, rhythm, percussion, bass, drone, and stings.
- Attach `MusicIntensityCurve` points to map a 0.0-1.0 gameplay intensity value
  to a preferred section kind, active layer IDs, and layer volume scale.

## Synchronization

Every transition and stinger can choose a `SyncBoundary`:

- `immediate` starts as soon as the command arrives.
- `beat` waits for the next beat in the current clip analysis.
- `bar` waits for the next bar.
- `phrase` waits for the next phrase using `beatsPerBar * barsPerPhrase`.
- `section_end` waits for the current segment end.

Clips can provide their own `BeatAnalysis`, or the runtime can create one from
BPM, beats per bar, and bars per phrase. For build tools and editor workflows,
`analyzeTempoFromOnsets` derives BPM and beat positions from detected onset
times.

## Runtime Flow

1. Load a `MusicAuthoringDefinition`.
2. Call `start(state, substate)` when gameplay enters the first context.
3. Call `updateIntensity(value)` as combat pressure, stealth danger, speed, or
   narrative tension changes.
4. Call `setState(state, substate)` to schedule a transition.
5. Call `update()` each audio tick to apply pending transitions and ducking.
6. Call `triggerStinger(event)` for one-shot musical phrases such as pickups,
   discoveries, achievements, victory, defeat, or danger spotted.
7. Call `triggerDucking(trigger)` for dialogue, explosions, cinematics, and
   other priority sound events.

## Memory Planning

Each `MusicClip` and layer chooses a `MemoryStrategy`:

- `stream` keeps large loops off the heap and tracks expected stream chunks.
- `preload` loads short or likely-upcoming material.
- `pin` keeps essential menu, ambience, or transition material resident.

The engine builds a `MusicMemoryPlan` for the current or next state and evicts
large non-pinned preloads when the budget is exceeded. Use streamable combat
loops, preload likely state transitions, and pin only tiny shared stems.

## Middleware

The internal backend records the same high-level commands that native bindings
can forward to Wwise or FMOD:

- `set_state` for the current music state.
- `set_switch` for pending state changes and layer on/off switches.
- `set_parameter` for continuous intensity values.
- `post_event` for transitions and stingers.
- `load_bank` and `unload_bank` for future native bank integration.

`createWwiseMusicBackend` and `createFmodMusicBackend` provide test doubles with
the correct backend identity. Production adapters should implement
`MusicPlaybackBackend` and translate commands into the studio middleware API.

## Debug Overlay

`getDebugOverlayState()` returns the complete HUD/editor payload:

- current state and substate
- smoothed intensity
- tempo, beat, bar, and phrase counters
- current section and active layer IDs
- pending transition target and start time
- ducking volume
- memory budget, loaded clips, streaming clips, and evictions
- active backend kind

Keep the overlay compact in-game: show state/substate, section, layers, beat
counter, next transition, and memory warnings first. Put detailed clip lists and
middleware event logs in the editor inspector.
