Skip to content

Class AudioSystem

Namespace: Apogee.Audio
Assembly: Apogee.Audio.dll

The game's audio, on OpenAL Soft: sounds (WAV, FLAC, MP3, Ogg Vorbis) played in 3D around the entity that has an , 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 is false, every call does nothing and returns something inert, and the game runs in silence.

public sealed class AudioSystem : EngineObject, IDisposable

Inheritance

object ← EngineObject ← AudioSystem

Implements

IDisposable

Inherited Members

EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Remarks

Call once a frame, after the world has progressed (it reads the entities' world transforms). Files are read through , so sounds live in res://, mods and packs. One audio system per process: OpenAL's current context is process-wide. The OpenAL listener stays at the origin; every voice is placed relative to the nearest , in double precision, so sound stays exact far from the world's origin. To use another audio middleware, replace this library (the engine has no backend layer).

Constructors

AudioSystem(World, AudioOptions?, VirtualFileSystem?)

Makes the audio of an ECS world. If OpenAL Soft is not installed (or will not start) the system is inactive and says so once in the log.

public AudioSystem(World ecs, AudioOptions? options = null, VirtualFileSystem? files = null)

Parameters

ecs World

options AudioOptions?

files VirtualFileSystem?

Properties

Class

What the registry knows about this object's class.

public override ClassInfo Class { get; }

Property Value

ClassInfo

CurrentReverb

The reverb the listener hears now: the preset of the zone it is in, or .

public ReverbPreset CurrentReverb { get; }

Property Value

ReverbPreset

Files

The file system the sounds are read from (res://…).

public VirtualFileSystem? Files { get; set; }

Property Value

VirtualFileSystem?

IsActive

True when OpenAL started: sounds will play. False means every call is a no-op.

public bool IsActive { get; }

Property Value

bool

Physics

The physics world that casts the rays for .

public PhysicsWorld? Physics { get; set; }

Property Value

PhysicsWorld?

Volume

The master volume, 0 to 1 and above.

public float Volume { get; set; }

Property Value

float

Methods

Create(World)

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.

public static AudioSystem Create(World ecs)

Parameters

ecs World

Returns

AudioSystem

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetBus(string)

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 ). Buses are cached: asking twice gives the same object.

public AudioBus GetBus(string name)

Parameters

name string

Returns

AudioBus

IsInstalled()

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

public static bool IsInstalled()

Returns

bool

LoadSound(string, bool, bool, bool)

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.

public AudioSound LoadSound(string path, bool stream = false, bool is3D = true, bool loop = false)

Parameters

path string

stream bool

is3D bool

loop bool

Returns

AudioSound

OnDestroyed()

protected override void OnDestroyed()

Update(float)

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.

public void Update(float deltaSeconds)

Parameters

deltaSeconds float