63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# Audio Authoring
|
|
|
|
Blacksite provides a complete scene-to-runtime audio loop for Bevy-supported Ogg/Vorbis and Speex,
|
|
WAV, MP3, and FLAC clips. Audio assets live under `assets/audio/`; the Asset Browser assigns a
|
|
stable registry ID plus the runtime project path used by standalone games and packages.
|
|
|
|
## Authoring Workflow
|
|
|
|
- Drag an audio clip into empty viewport space to create an `AudioSource` actor at the snapped drop
|
|
position. With an audio source selected, dropping another clip assigns it through one undoable
|
|
command.
|
|
- The Audio Source Inspector controls clip, gain, pitch, loop, autoplay, 2D/spatial blend,
|
|
attenuation distances/curve, and stable bus routing. **Audition** uses the editor camera as the
|
|
spatial listener; **Stop** ends it immediately.
|
|
- Add an Audio Listener component from the Audio category when a scene needs an explicit listener.
|
|
The highest-priority enabled listener wins; stable actor ID order is the deterministic fallback.
|
|
- Source/listener root icons and selected-only attenuation/listener gizmos can be hidden with the
|
|
Audio option in Viewport options.
|
|
|
|
Audition entities are `EditorOnly`. They are stopped on PIE entry, scene replacement, source
|
|
deletion, natural clip completion, or explicit Stop. Audition does not mutate the source descriptor,
|
|
push history, or mark the active scene dirty. The preview owns a transient listener that follows the
|
|
editor camera without replacing camera components, and a failed clip load stops with an editor
|
|
status message instead of leaving a silent preview active.
|
|
|
|
## Buses
|
|
|
|
**Edit -> Project Settings -> Audio Buses** edits the project bus graph. `master`, `music`, and `sfx`
|
|
are required stable IDs; labels, gain, and mute state are editable. Custom buses receive stable IDs,
|
|
route through a parent, and may be removed while unused. Apply/Save is disabled while the graph has
|
|
duplicate IDs, missing parents, cycles, invalid gain, or missing required buses.
|
|
|
|
Runtime code can change user/session mixer state through `game::audio::AudioBusRuntime` without
|
|
rewriting project settings. Effective gain includes the complete parent route. A muted parent mutes
|
|
all descendants.
|
|
|
|
## Runtime And PIE
|
|
|
|
`game::audio::GameAudioPlugin` derives Bevy `AudioPlayer`, sink, and `SpatialListener` state from the
|
|
authored descriptors. A continuous spatial blend uses equal-power 2D and spatial voices between the
|
|
endpoints; selected attenuation is applied from the effective listener position. Spatial backend
|
|
coordinates are normalized inside the authored audible radius, so left/right panning does not add a
|
|
second distance falloff on top of the Inspector curve. F6 pauses/resumes existing PIE voices, while
|
|
stopping PIE clears derived voices so the next session starts from the authored autoplay state.
|
|
|
|
The runtime exposes `play_authored_audio_source`, `stop_authored_audio_source`, and
|
|
`reset_authored_audio_runtime` for gameplay/session control. `AudioRuntimeDiagnostics` reports the
|
|
active CPAL backend, default output device, and compiled codec set without making headless content
|
|
validation depend on an audio device.
|
|
|
|
## Validation And Sample
|
|
|
|
Interactive validation, `cargo validate-levels`, and packaging share checks for:
|
|
|
|
- missing, unsafe, excluded, unreadable, or Git LFS pointer clips;
|
|
- unresolved clip identities and unsupported codec extensions;
|
|
- invalid gain, pitch, spatial blend, attenuation, listener ear gap, or bus references;
|
|
- invalid project bus graphs and tied highest-priority enabled listeners.
|
|
|
|
`assets/levels/audio_authoring_showcase.scn.ron` and
|
|
`assets/audio/editor_audition_tone.ogg` provide a small deterministic source/listener fixture for
|
|
save/load, audition, PIE, headless validation, and package smoke tests.
|