Skip to content

AudioSystem

Extends EngineObject.

The game's audio, on OpenAL Soft: sounds (WAV, FLAC, MP3, Ogg Vorbis) played in 3D around the entity that has an AudioListener, on buses, with reverb zones and occlusion. OpenAL Soft is a separate shared library that ships beside the program (see Legal/THIRD_PARTY_NOTICES.md): without it IsActive is false, every call does nothing and returns something inert, and the game runs in silence.

Properties

  • is_active: boolean True when OpenAL started: sounds will play. False means every call is a no-op. Read-only.
  • physics: PhysicsWorld? The physics world that casts the rays for AudioVoice.Occlusion.
  • volume: number The master volume, 0 to 1 and above.
  • current_reverb: ReverbPreset The reverb the listener hears now: the preset of the zone it is in, or ReverbPreset.Off. Read-only.

Methods

update

function update(self, deltaSeconds: number): ()

Once a frame, after the world has progressed: finds the listeners, puts the voices where their entities are (relative to the nearest listener, in double precision, with the velocities the Doppler effect needs), raycasts the occlusion, picks the reverb zone, and mixes the time that has passed when the output is not a device. deltaSeconds is the game's frame time.

get_bus

function get_bus(self, name: string): AudioBus

A bus by name, made when first asked for: the groups of sounds a game mixes (music, vehicles, ui), each with a volume, a mute and a pause of its own. The empty name and master are the whole mix (its volume is Volume). Buses are cached: asking twice gives the same object.

load_sound

function load_sound(self, path: string, stream: boolean?, is3D: boolean?, loop: boolean?): AudioSound

Loads a sound file (WAV, FLAC, MP3 or Ogg Vorbis) from the file system. stream decodes it as it plays instead of whole (music, long ambience); is3D makes it positional; loop loops it by default.

Functions

create

AudioSystem.create: (ecs: World) -> AudioSystem

Makes an audio system for an ECS world from a script, mixing into nowhere (no sound device is opened): for tests. A game's own is the global audio.

is_installed

AudioSystem.is_installed: () -> boolean

Whether OpenAL Soft and the decoders can be loaded: false on a machine without the libraries.