Audio
How the NEO engine plays sound - AudioPlayer entities, formats in NEO's builds, global volume, spatial sound - and NEO's audio kit for game foley.
Sound in the engine is an entity. Spawn an entity with an AudioPlayer holding a sound asset and it starts playing; despawn it and it stops. Settings for how it plays go in a PlaybackSettings component next to it, and once it's playing the engine adds an AudioSink you use to pause, change the volume or seek.
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, music)
.run();
}
fn music(mut commands: Commands, assets: Res<AssetServer>) {
commands.spawn((
AudioPlayer::new(assets.load("sounds/theme.ogg")),
PlaybackSettings::LOOP,
));
}Formats#
| Format | In NEO's builds |
|---|---|
Ogg Vorbis (.ogg) | Yes. This is the format to use for music and effects. |
| WAV, FLAC, MP3, AAC, MP4 | No. They need the wav, flac, mp3, aac or mp4 cargo features (audio-all-formats turns on all of them). |
NEO's audio kit has its own WAV decoder for its foley banks, so games built on the gameplay kit play .wav footsteps without the wav feature. See Cargo features.
Global volume#
GlobalVolume scales every sound. Set it when you add the plugins, or change the resource; a change applies to sounds that start afterwards.
use neo::audio::{AudioPlugin, GlobalVolume, Volume};
App::new().add_plugins(DefaultPlugins.set(AudioPlugin {
global_volume: GlobalVolume::new(Volume::Linear(0.5)),
..default()
}));Pages#
| Page | What it covers |
|---|---|
| Playing sounds | AudioPlayer, PlaybackSettings, controlling a sound with AudioSink, volumes and fades, one-shot effects and generated sounds. |
| Spatial audio | Sounds placed in the world, heard from a listener, in 2D and 3D. |
In NEO games#
The gameplay kit's audio, neo_audio_kit, sits on top of this. It mixes the game's sounds in one output stream with fades, loops and a reverb send, and its foley player plays the character's footsteps, landings and impacts from a bank picked by surface, with distance and panning. It plays through the engine as a custom audio source, so engine sounds and kit sounds mix together. See Gameplay kit.
On the web#
Browsers only start audio after the player interacts with the page. NEO's web builds start the game from a Play click for this reason; see Web builds. Sounds are decoded while the game starts, and the browser build runs on one thread.