Spatial audio
Place sounds in the world with spatial PlaybackSettings and hear them from a SpatialListener, with the scale to use for 2D and 3D games.
A spatial sound comes from where its entity is. The engine compares the emitter's position with two "ears" on a listener entity and sets each ear's volume, so sounds get quieter with distance and move from left to right as they pass.
Set it up#
- Give the sound a
Transformand turn onspatialin itsPlaybackSettings. - Put a
SpatialListeneron the entity that hears: usually the camera or the player.
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.run();
}
fn setup(mut commands: Commands, assets: Res<AssetServer>) {
// the emitter: a looping sound two metres to the right
commands.spawn((
Transform::from_xyz(2.0, 0.0, 0.0),
AudioPlayer::new(assets.load("sounds/engine.ogg")),
PlaybackSettings::LOOP.with_spatial(true),
));
// the listener, on the camera, with its ears 0.2 m apart
commands.spawn((
Camera3d::default(),
Transform::from_xyz(0.0, 1.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
SpatialListener::new(0.2),
));
}Moving either entity moves the sound: the engine updates positions from their GlobalTransform every frame.
The listener#
SpatialListener | What it is |
|---|---|
SpatialListener::new(gap) | Ears gap apart along the listener's local X axis, half to each side. |
left_ear_offset, right_ear_offset | The ears' positions relative to the listener, if you want to set them yourself. |
Use one listener. The ears turn with the listener's rotation, so a listener on the camera hears the world the way the player sees it.
Scale#
Distances are in your world's units. A 3D game in metres works as is. A 2D game in pixels needs scaling down, or every sound is far away. Set the scale for every sound with the audio plugin:
use neo::audio::{AudioPlugin, SpatialScale};
App::new().add_plugins(DefaultPlugins.set(AudioPlugin {
default_spatial_scale: SpatialScale::new_2d(1.0 / 100.0), // 100 pixels sound like 1 unit
..default()
}));One sound can override it with PlaybackSettings::with_spatial_scale(SpatialScale::new(..)).
Controlling a spatial sound#
A spatial sound gets a SpatialAudioSink instead of an AudioSink. It has the same controls (pause, volume, speed, seek; see Playing sounds).
What it doesn't do#
Spatial sound here is distance and stereo balance between two ears. There's no Doppler effect, occlusion, reverb or HRTF. Games built on NEO's gameplay kit get their footsteps and impacts placed by the audio kit's foley player instead, which does its own distance attenuation, panning and a reverb send; see Gameplay kit.
Examples: cargo run --example spatial_audio_3d and spatial_audio_2d.