NEOLearn

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.

Updated October 20, 2026

On this page

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#

  1. Give the sound a Transform and turn on spatial in its PlaybackSettings.
  2. Put a SpatialListener on the entity that hears: usually the camera or the player.
src/main.rs
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#

SpatialListenerWhat it is
SpatialListener::new(gap)Ears gap apart along the listener's local X axis, half to each side.
left_ear_offset, right_ear_offsetThe 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:

Rust
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.

Next steps#