Eve library

Adaptive Music Composer Guide

Guide

Revision 1

On this page

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.