Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
codex/terrain-sculpt-strokes
Blacksite/docs/adr/0030-audio-authoring-and-bus-schema.md
Rbanh 0553a85220
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Build production-ready editor authoring workflows
2026-07-11 12:41:04 -04:00

2.2 KiB
Raw Permalink Blame History

ADR 0030: Audio Authoring And Bus Schema

Status

Accepted

Context

Audio sources and listeners must round-trip through authored scenes without serializing Bevy's runtime playback handles or sink state. Source routing must also survive bus display-name changes, project reloads, PIE, and packaging. Bevy provides playback and spatial-listener primitives, but it does not define Blacksite's persistent authoring schema or project bus graph.

Decision

shared owns reflected, serializable AudioSourceDesc, AudioListenerDesc, AudioAttenuationDesc, and AudioRolloff types. Dedicated authored audio actors use the AudioSource and AudioListener actor kinds. Runtime playback, sink, and listener components are derived state and are never scene source of truth.

An authored clip uses EditorAssetRef. Its registry identity remains authoritative, its imported sub-asset ID is audio:source, and its cached source path supports runtime hydration and package validation. Source bus references store stable bus IDs rather than display labels.

settings owns AudioSettings and its bus graph. Every project contains stable master, music, and sfx IDs; Music and SFX route to Master by default. Additional buses are allowed when their lowercase stable IDs are unique and their parent chain terminates at Master. Validation rejects missing required buses, invalid gain values, missing parents, unknown references, and cycles.

The ProjectSettings.audio field uses a serde default so older manifests load with the standard bus graph. New project and sandbox manifests include the audio capability and assets/audio root.

Consequences

  • Renaming a bus label is safe; changing a bus ID is a routing migration.
  • Editor audition and game playback share one authored contract while retaining independent transient runtime state.
  • Continuous spatial blend and attenuation behavior belong to the runtime adapter; the schema does not claim those controls map one-to-one to native Bevy components.
  • DSP graphs, sends, reverb zones, streaming banks, and middleware integration remain future work.
  • Gitea issue #47 passed automated, headless, live editor/PIE, and packaged-runtime acceptance; this contract is the M7 audio baseline.