Audio

vgai audio is built on the Web Audio API via Three.js’s AudioListener. Setup (packages/engine/src/setup/setup-audio.ts) creates the listener, a master gain, and three category buses.

The bus hierarchy and spatial attenuation.

The audio context

The AudioContext provides:

• listener — a THREE.AudioListener (attached to the camera, so spatial audio is heard from the camera’s position).
• masterGain — the final gain node everything routes through.
• buses — music, sfx, and voice gain nodes, each independently adjustable.
• resume() — call on the first user interaction; browsers start the audio context suspended until a gesture.

Sound sources

An entity plays sound via the audio schema (packages/engine/src/scene/schema/audio.ts):

Field	Meaning
src	path to a WAV / MP3 / OGG file
spatial	enable 3D positional audio
volume	0–1 playback volume
refDistance	distance at which attenuation begins (spatial only)
rolloffFactor	how fast volume falls with distance (spatial only)
maxDistance	distance beyond which it’s inaudible (spatial only)
loop	loop the clip
autoplay	start when the scene loads

For spatial sounds, refDistance / rolloffFactor / maxDistance shape the falloff curve; non-spatial sounds play at a constant volume (UI, music).

Procedural sound helpers

packages/engine/src/audio/ ships synthesized sound generators so you can prototype without asset files. They’re grouped by purpose and re-exported from audio/index.ts:

• ambient — wind, rain, hum, nature
• impacts — bounce, crash, explosion, hit
• movement — footstep, jump, whoosh
• musical — arpeggio, bassPulse, stinger
• ui-sounds — uiClick, uiError, uiHover, uiSuccess
• vehicle — brakeSqueal, engineDrone, tireSkid
• weapons — gunshot, laser, chargeUp

Mixing

Route a sound to a bus and adjust that bus’s gain to mix categories independently (e.g. duck music under voice). The master gain controls overall volume.

See also

• Quick start: play a spatial sound — a focused walkthrough.
• Scene Schema reference — every audio field.