Expand description
Voxel-aware acoustics for the roxlap engine (stage AU —
docs/porting/PORTING-AUDIO.md).
This crate computes acoustic parameters from the voxel world; it
deliberately owns no audio device and spawns no audio thread. The
host feeds the numbers into whatever playback stack it uses (the
optional kira backend lands in AU.2): per sound source an
occlusion-driven gain + lowpass cutoff + reverb send, and (AU.1) per
listener a cavity-driven reverb feedback/mix.
The occlusion model follows the convergent games recipe (Sound
Physics, Teardown, Overwatch — see the entry doc): a small fan of
rays from the source to the listener, each accumulating the solid
path length it crosses (voxel units, exact segment lengths from a
DDA march — not a boolean hit test), averaged into a 0..=1
transmission. Thickness matters: one voxel of wall muffles less
than five, and a doorway passes some rays untouched, so sound leaks
around corners instead of gating on/off.
Everything here is pure and deterministic — the jitter fan is a fixed ring, not RNG — so tests pin exact values and hosts can call it from any thread.
Re-exports§
pub use synth::SoundBuffer;
Modules§
- synth
- AU.2 — procedurally synthesized demo sounds (house pattern: no binary assets; the Doom demo synthesizes its GIFs, we synthesize our bleeps). Deterministic — the noise source is a fixed LCG — so buffers are testable byte-for-byte and identical across runs.
Structs§
- Acoustics
Config - Tuning knobs for
source_acoustics. The defaults are the cave-demo tuning; every field is plain data so hosts can persist or lerp them. - Cavity
Config - Tuning knobs for the cavity probe + the reverb mapping.
- Cavity
Estimator - Stateful cavity estimator:
probe_cavityplus the prior-art exponential smoothing, mapped to reverb parameters. One per listener; callupdateat ~2 Hz andreseton teleports. - Cavity
Probe - Raw (unsmoothed) result of one
probe_cavityfan. - Listener
Acoustics - Smoothed reverb parameters for the listener’s surroundings,
produced by
CavityEstimator::update. Feed the reverb fields to the backend with long tweens (~1 s). - Sound
Key - A registered sound asset (backend-owned decoded buffer).
- Source
Acoustics - Occlusion-driven playback parameters for one source→listener pair,
produced by
source_acoustics. Feed them to the playback layer with short tweens (~120 ms) — never as raw jumps. - Source
Id - One live spatial source (a pooled backend track). Stale after the source is stopped or stolen — backend calls on a stale id are no-ops by contract.
- Source
Pool - Backend-agnostic voice-slot policy for a fixed pool of spatial
tracks — pure and unit-tested here so every backend (the built-in
kira one, or a host’s own
AudioOut) inherits the same behaviour (hazard 2: tracks are created up front and reused; a per-shot allocation storm is the classic mistake). One-shots are stealable (oldest first) when the pool is full; loops hold their slot until explicitly stopped.
Constants§
- DEFAULT_
SPEED_ OF_ SOUND - AU2.2 — default speed of sound for
doppler_factor, world units/second. Deliberately game-tuned, not physical: at the real 343 m/s a 60 u/s bullet would bend pitch by ~1.5 semitones; at 90 the demo’s speeds read clearly. Hosts pass their own value to retune. - LISTENER_
LOWPASS_ OPEN_ HZ - WT.3 — the neutral (fully open) listener-lowpass cutoff: passing
this (or anything above) to
AudioOut::set_listener_lowpassmeans “not submerged”. Defined AScrate::OPEN_CUTOFF_HZ— “open” means the same thing on the per-source and listener paths by construction, not by a pin test. - LISTENER_
LOWPASS_ SUBMERGED_ HZ - WT.3 — the canonical SUBMERGED listener-lowpass cutoff: the value the demos (and any host without its own tuning) pass while the eye is under water. One named default so every call site muffles identically and a listening-pass retune is a one-line change. Tuned dark enough to read as “under the surface” while speech-band content stays intelligible.
- OPEN_
CUTOFF_ HZ - The ONE definition of a fully-open (no muffle) lowpass cutoff,
shared by every path that needs “not occluded / not submerged”:
AcousticsConfig::default’sopen_cutoff_hz, the listener lowpass (LISTENER_LOWPASS_OPEN_HZis this constant), and the kira backend’s per-source filter rest position. One constant so the three can’t drift apart silently.
Traits§
- Audio
Out - The playback backend the acoustics core drives. Implementations apply parameter changes with tweens (~120 ms for per-source occlusion, ~1 s for the listener’s reverb) — never as raw jumps (hazard 3: parameter zippering).
Functions§
- doppler_
factor - AU2.2 — the Doppler playback-rate factor for a moving
source/listener pair:
> 1approaching (pitch up),< 1receding, exactly1.0at rest. The classic two-sided formula(c − v_l·n̂) / (c − v_s·n̂)withn̂the source→listener direction, made monotone and finite at the edges: the denominator floors at0.05·c(a supersonic approach clamps instead of flipping sign) and the result clamps to[0.5, 2.0]— an octave down/up, past which game audio reads as a glitch. - hear_
source - FW.4 — reveal a heard sound source in the fog of war (decision 6):
hearing something behind the back or through a wall lights a temporary
“heard” pocket around it. Runs
source_acousticsto measure how much of the source reaches the listener through the geometry, scalesbase_loudnessby that transmission, and stamps a heard blob at the source’s fog cell viaFogOfWar::hear_world. - path_
thickness - Total solid path length (world/voxel units) the straight segment
a → bcrosses, summed over every grid in the scene. This is the thickness building block undersource_acoustics: exact per-cell segment lengths from a voxel DDA againstroxlap_scene::Grid::voxel_solid(a diagonal crossing of a 1-voxel wall correctly reports ~√2). - path_
thickness_ weighted - AU2.0 —
path_thicknesswith per-material weighting: each solid cell’s segment length is multiplied by its material’s absorption factor (material_mapclassifies the cell’s colour the way the renderer’s terrain map does;absorptionmaps material id → multiplier, unmapped =1.0). One voxel of0.35glass muffles like 0.35 voxels of stone. The.vxlformat stores surface colours only, so an interior cell reuses the last surface colour the ray crossed in that grid (weight1.0before the first — deep interiors read as rock, which is what they are). - probe_
cavity - Probe the space around
listener: cast the golden-spiral fan and reduce it to aCavityProbe. Pure and deterministic — the fan is a fixed direction set, so tests pin exact values and the estimator can round-robin freely. - source_
acoustics - Occlusion parameters for one source heard from
listener: a fan ofAcousticsConfig::raysthickness rays (the direct segment plus a fixed jitter ring around the source, perpendicular to the source→listener axis), each converted to transmitted energyexp(-absorption · thickness)and averaged.