game.audio is the AudioSystem of a Game. It opens the output device, owns the mixer, and loads Sound and Music resources. You do not create or close a device yourself. The audio system starts with the Game and shuts down with it.
The audio classes and bus constants come from @bornengine/engine. They are also available from @bornengine/engine/audio.
Supported files are WAV (8-bit or 16-bit PCM) and OGG Vorbis. MP3 also works on native targets built with the mp3 native feature, which every BornEngine CLI game profile includes. MP3 does not decode on Web/WASM.
Device lifecycle
The audio device opens when the Game is ready and closes when the Game is disposed. Every mixer method returns false when audio is not ready, so check isReady once at start-up.
import { BUS_MUSIC, Game } from '@bornengine/engine';
class AudioDemo extends Game {
protected override onStart(): void {
if (!this.audio.isReady) {
console.error('Audio is unavailable on this device.');
return;
}
this.audio.setMasterVolume(0.8);
this.audio.setBusGain(BUS_MUSIC, 0.6);
this.audio.setReverb(0.5, 0.4, 0.2);
}
onPlayerHit(): void {
this.audio.duckBus(BUS_MUSIC, 0.7, 0.05, 0.4, 0.3);
}
}
new AudioDemo().run();The mixer has three buses: BUS_SFX (0), BUS_MUSIC (1), and BUS_UI (2). A bus is a mixer channel that several sounds share, so you can change their level together. Sounds start on BUS_SFX, and music always plays on BUS_MUSIC.
setMasterVolume(volume)sets the level of everything.setBusGain(bus, gain)sets the level of one bus.duckBus(bus, amount, attack, release, hold)lowers a bus for a moment.amountis how far to pull it down, from 0 to 1. The level falls overattackseconds, stays down forholdseconds, and recovers overreleaseseconds. Call it again to restart the hold.setReverb(size, damp, wet)configures the one reverb that all sounds share. Each value runs from 0 to 1, and awetvalue of 0 turns the reverb off. A sound feeds the reverb only when itsreverbSendis above 0.setListener(position, forward)places the 3D listener.
Every one of these returns true when it was applied.
The Game calls game.audio.update(deltaTime) once per frame. That call advances cooldown timers and feeds every loaded Music stream, so you never call it yourself.
When the Game is disposed, it first disposes sound managers and then music and sounds, and last it closes the device.
Sound
loadSound(path) loads a file and returns a Sound at once. It never returns null. Check isLoaded, and read error when loading failed.
import { BUS_UI, Game } from '@bornengine/engine';
class MenuGame extends Game {
protected override onStart(): void {
const select = this.audio.loadSound('assets/audio/select.wav');
if (!select.isLoaded) {
console.error(select.error);
return;
}
select.setBus(BUS_UI);
select.play({ volume: 0.8, pitch: 1.1 });
const voice = select.play3D({ x: 2, y: 0, z: -4 }, { refDist: 2, maxDist: 40 });
if (voice !== null) voice.setLowpass(1200);
}
}
new MenuGame().run();play(options)starts a new playback and returnstruewhen it was requested.volumeandpitchapply to that playback only. Pitch is a speed multiplier from 0.25 to 4.play3D(position, options)plays the sound at a point in 3D space and returns aSoundVoice.looping,refDist,maxDist, androlloffshape the sound.refDistis the distance that plays at full volume,maxDistis the distance past which the mixer stops mixing the voice (0 means never), androlloffis how fast the level falls beyondrefDist. The method returnsnullwhen the sound is not loaded or when the platform plays it without a controllable voice.- A
SoundVoiceis one playing instance of a sound. You can move it withsetPosition, adjust it withsetVolume,setPitch, andsetLowpass, and end it withstop().isActivetells you whether it still exists. stop()stops the sound and all its voices.setVolume,setBus,setReverbSend(0 to 1), andsetLowpass(cutoffHz)set how the sound is mixed. A low-pass filter muffles the sound above the cutoff frequency, andsetLowpass(0)turns it off.dispose()stops the sound and unloads it. ASoundthat you do not dispose lives until theGameis disposed.
loadSoundAsync(path) returns a promise, and stageSounds(paths) decodes several files in parallel and returns staged objects whose commit() creates each Sound. game.audio has the matching loadMusicAsync(path) and stageMusic(paths) for music. Use the synchronous loaders on Web/WASM and watchOS, where staged loading is not available yet and produces a sound that is not loaded. Like every promise, an async load only finishes where the host runs promise continuations. On native Linux, Game.run() does not yet, so await the load before you call run().
To release sounds together with a scene, load them through scene.assets.loadSound(path) instead. Assets explains scene-scoped and Game-scoped loading.
Sound manager
A SoundManager registers sounds and music under names, so game code can say playSound('confirm') instead of holding file paths. It also adds a cooldown between plays, random volume and pitch for each play, and one place to release everything when a scene ends.
import { Game, BUS_SFX, Scene, SoundManager } from '@bornengine/engine';
class MenuScene extends Scene {
private readonly sounds: SoundManager;
constructor() {
super({ name: 'menu' });
const audio = Game.current.audio.createSoundManager();
this.sounds = audio;
this.own(audio);
audio.loadSound('confirm', 'assets/audio/confirm.wav', {
cooldownSeconds: 0.12,
volumeRange: [0.9, 1],
pitchRange: [0.95, 1.05],
});
audio.loadMusic('ambient', 'assets/audio/ambient.ogg', { volume: 0.6 });
audio.setBusGain(BUS_SFX, 0.9);
}
override onEnter(): void {
this.sounds.playMusic('ambient');
}
confirm(): void {
this.sounds.playSound('confirm');
}
dropTrack(name: string): void {
this.sounds.unloadMusic(name);
}
}Registering:
loadSound(name, path, options)returns theSound, ornullwhen an option is invalid, the file does not load, or the name already refers to a different path. Loading a name again with the same path returns the existing sound and keeps its first options.- The options are
bus(one of the three bus constants),volume,reverbSend(0 to 1),lowpassHz,cooldownSeconds,volumeRange, andpitchRange. Each play multiplies the volume by a random value involumeRangeand the pitch by a random value inpitchRange. Ranges are[min, max]pairs. Volume multipliers cannot be negative, and pitch multipliers must stay between 0.25 and 4. loadMusic(name, path, options)returns theMusic, ornull. Its only option isvolume.
Playing:
playSound(name)returnsfalsewhen the name is unknown or the sound is still cooling down.play3D(name, position, options)shares the same cooldown and returns aSoundVoiceornull.playMusic(name)stops the track the manager played before and starts the new one.stopMusic(name)stops one track, andstopMusic()stops them all.stopSound,setSoundVolume, andsetMusicVolumechange one registered item by name.unloadSound(name)andunloadMusic(name)stop it and release its resource.setMasterVolume(volume)andsetBusGain(bus, gain)act on the shared mixer, not on this manager alone. They change the level of all audio in theGame.
Ownership:
- A manager releases only the sounds and music it registered. Other audio in the
Gameis not touched. Calldispose()when its lifetime ends. It is safe to call more than once, and playback requests fail afterward. scene.own(audio)hands the manager to a scene, which disposes it when the scene unloads. A manager that no scene owns is disposed with theGame.- The
Gameadvances every manager’s cooldown timers each frame. - Known issue: a manager that a scene owns gets a second cooldown update each frame, from the scene. Its cooldowns run at double speed, so
cooldownSeconds: 0.12lasts about 0.06 seconds of frame time. Do not rely on exact cooldown timing for a scene-owned manager until the engine is fixed.
Music and spatial audio
loadMusic(path) returns a Music at once. Check isLoaded. A Music has play(), stop(), setVolume(volume), and isPlaying. It repeats until you stop it. The Game streams every loaded Music each frame, so you do not call music.update().
For positional sound in a 3D scene, call game.audio.setListener(position, forward) each frame, and play sounds with play3D. For a 2D game, use the shared game.audio.listener2D and an AudioEmitter2D component:
import { Game, AudioEmitter2D, GameObject, Scene, Vec3 } from '@bornengine/engine';
import type { Music } from '@bornengine/engine';
class Level extends Scene {
private readonly theme: Music;
private readonly emitter: AudioEmitter2D;
constructor() {
super({ name: 'level' });
this.theme = Game.current.audio.loadMusic('assets/audio/theme.ogg');
const wind = Game.current.audio.loadSound('assets/audio/wind.wav');
this.emitter = new AudioEmitter2D(wind, Game.current.audio.listener2D, {
looping: true,
refDist: 24,
maxDist: 400,
});
const source = new GameObject({ name: 'Wind', position: new Vec3(300, 200, 0) });
source.addComponent(this.emitter);
this.addNode(source);
}
override onEnter(): void {
if (this.theme.isLoaded) this.theme.play();
if (this.emitter.sound.isLoaded) this.emitter.play();
}
override onExit(): void {
this.theme.stop();
this.emitter.stop();
}
}Music and sounds that you load through game.audio belong to the Game, not to the scene. That is why onExit() stops them.
To make the listener follow a game object, such as the player, add the component to that object:
import { AudioListener2D, GameObject, Scene } from '@bornengine/engine';
export function addListener(scene: Scene, player: GameObject): AudioListener2D {
const listener = new AudioListener2D();
player.addComponent(listener);
scene.addNode(player);
return listener;
}listener2Dfollows the active scene camera by default. CallsetPosition({ x, y })to pin it to a world position, andfollowCamera()to follow the camera again.AudioListener2Dis also aGameComponent. Addnew AudioListener2D()to a game object and the scene updates the listener once per frame from that object: its world X and Y position, and its rotation about Z. Without an owner object, and without the sharedlistener2Dbinding, it does nothing.AudioEmitter2Dstarts one controllable voice at its object’s position and moves the voice as the object moves. The world’s X and Y axes map to the mixer’s X and Z axes.play()returnstruewhen the voice started,stop()ends only that voice, andisPlayingreports its state. Disabling or destroying the object stops the voice. The shared audio system still owns theSoundand the listener.
Platform notes:
- On Web/WASM, browsers block audio until the player interacts with the page. The first pointer or key press starts it.
- watchOS plays sounds and music through the system audio player. It supports loading,
play,stop, and volume. Buses, ducking, reverb, low-pass filters, voices, spatial audio, per-playvolumeandpitch, and staged loading do nothing there.play3Dplays the sound flat.
Next steps
- Audio and UI adds sound effects and a heads-up display to a game.
- Assets explains how scenes and the
Gameown loaded resources. - Scene covers the scene lifecycle that
scene.own()follows.