43 lines
2.2 KiB
Markdown
43 lines
2.2 KiB
Markdown
# 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.
|