Audio

The mixer lives in crates/audio (src/mixer.rs); its module docs are the full reference for buses, snapshots, music and the voice cap. This page covers the policy decisions a game author needs to know about without reading the code.

Several listeners (local split screen)

Local co-op has two to four views on one screen and one stereo output device. Each view has a camera, so each has a listener, and the mixer has to decide what one spatial sound is like when the listeners are in different places.

Default: the nearest listener decides. For each spatial voice the listener closest to it sets both its distance attenuation and its pan, exactly as if that player were alone. If two listeners are exactly as close, the one earlier in the list wins, so pass the views in a stable order with player 1 first. A sound next to player 2 sounds the way it would in a one-player game, and a sound far from every player stays quiet.

The alternative: Sum. ListenerPolicy::Sum adds up each listener's left and right contribution, then scales the total down so the voice is never louder than its unattenuated gain. Two players standing on the same sound hear it no louder than one would. The cost is that a sound between two players comes out of both speakers at once, so neither player can tell which side of their own screen it is on. Pick it for a shared-space game where loudness should reflect how many players are near a sound. Set it with Mixer::set_listener_policy.

Considered and rejected:

• The loudest listener decides. This is the same as the nearest one. Every rolloff curve falls as distance grows, and every listener hears a voice through that voice's own curve and range.
• Centred pan when listeners disagree. This throws away the one cue that tells a player which side of their own view a sound is on.

Guarantees.

• One listener gives bit-for-bit the same output as the single-listener mixer under either policy. crates/audio/tests/listeners.rs checks this every tick, bit for bit, against the old single-listener formula.
• Which listener is chosen never affects voice priority, voice stealing or the handle play returns, so the simulation stays deterministic.
• Listeners are held in a fixed array of MAX_LISTENERS (4). Setting them every tick allocates nothing (crates/audio/tests/alloc.rs).
• Bad input is contained (crates/audio/tests/listener_adversarial.rs). A listener whose position is not finite never wins the nearest decision, so it cannot silence a real one; a listener with a NaN or zero rotation pans to the centre. Whatever goes in, gain, pan and both ears are finite and no louder than the voice's own gain.
• Listeners are cut to the first four in the order given, so the cut is stable.
• When the nearest listener changes, gain stays continuous (it follows the nearest distance) but pan steps to the new listener's side. Smoothing that step belongs to the backend.
• The mixer has no doppler, occlusion or per-listener reverb today. If any is added, it will use the listener the policy chose.

API.

• Mixer: Mixer::set_listeners(&[Listener]) takes 1 to 4 listeners. Extra listeners are ignored, and an empty slice changes nothing. set_listener is the one-listener case.
• Mixer queries: Mixer::listeners() returns the live listeners, and VoiceGain::listener is the index of the listener that decided that voice.
• App: World::set_listener_sources(&[(Vec3, Quat)]) takes one position and rotation per view and applies them from the next tick. An empty slice goes back to the default below.
• Views listen by themselves. With a ctx.views layout of two or more views (left-right, top-bottom, three, grid) the mixer gets one listener per view, view 1 first, at each view's camera, refreshed every tick as the cameras move; a view the layout drops stops listening on that tick. View 1's listener is the camera's, exactly where a one-view game's is. With one view nothing changes: one listener on the camera, bit for bit. A scene's output: "viewport" camera (a minimap) is not a view and does not listen. Nothing is allocated per tick. crates/app/tests/split_screen_audio.rs covers this.
• Script: ctx.audio.listenFrom("views" | "camera"). "views" is the default above; "camera" keeps one listener on view 1's camera however many views there are. ctx.audio.setListenerPolicy("nearest" | "sum") is Mixer::set_listener_policy. Both apply from the next tick, may be called in init before any view exists, and throw a TypeError for any other value, changing nothing.
• Who listens, first that applies: World::set_listener_sources (non-empty); then listenFrom("camera"); then one listener per view; then the camera.