AudioManager plays the game's music, ambient sound, sound effects and voice lines, and controls their volumes. See Audio Overview for how audio is organised in a project.
Sounds are named by their key, the file name without its extension, so Door Creak.ogg is "door_creak". PlayMusic, PlayAmbient, PlaySFX, PlayVoice and Unload also take an audio file picked in a File variable (an AssetRef). One music track and one ambient loop play at a time. Any number of sound effects and voice lines can overlap.
Browsers block sound until the player first clicks or taps the page, so sound started before then may not be heard. While the game's tab is hidden, all sound is silenced.
| Member | Description |
|---|---|
PlayMusic() |
Plays a music track, crossfading from the current one |
StopMusic() |
Fades the music out |
PlayAmbient() |
Plays an ambient loop |
StopAmbient() |
Fades the ambient loop out |
PlaySFX() |
Plays a sound effect |
PlayVoice() |
Plays a voice line |
Get...Volume() |
Reads a volume |
Set...Volume() |
Changes a volume |
ApplySettings() |
Sets several volumes at once |
SaveSettings() |
Saves the volumes |
LoadSettings() |
Loads the saved volumes |
RegisterAudio() |
Adds a sound from a url |
Unload() |
Frees a loaded sound effect or voice line |
AttachVideo() |
Routes a video's sound through the video volume |
Register() |
Listens for audio events |
Unregister() |
Stops listening |
ctx |
The Web Audio context |
Playing sound
PlayMusic
AudioManager.PlayMusic(name: MusicName, fade = 1): void
Plays a music track on a loop, fading it in while the current track fades out.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
MusicName |
The track's key | |
fade |
number |
1 |
Seconds to crossfade over |
How it works
- Nothing happens if that track is already playing, so it's safe to call every time a scene starts.
- If there's no such track, a warning is logged and the current music carries on.
- Music set in a scene's inspector, and the
[Music(key)]chapter action, use this too.
Example
onStart() {
AudioManager.PlayMusic("boss_theme", 3); // a slow three-second crossfade
},
StopMusic
AudioManager.StopMusic(fade = 1): void
Fades the music out over fade seconds, then stops it. Does nothing if no music is playing.
Example
onBossDefeated() {
AudioManager.StopMusic(0.5);
AudioManager.PlaySFX("victory");
},
PlayAmbient
AudioManager.PlayAmbient(name: AmbientName, fade = 1): void
Plays an ambient loop, like rain or crowd noise, fading it in while the current loop fades out. It plays alongside the music.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
AmbientName |
The loop's key | |
fade |
number |
1 |
Seconds to fade over |
Nothing happens if that loop is already playing. A warning is logged if there's no such file.
Example
onEnter() {
AudioManager.PlayAmbient("forest_birds");
},
StopAmbient
AudioManager.StopAmbient(fade = 1): void
Fades the ambient loop out over fade seconds, then stops it.
PlaySFX
AudioManager.PlaySFX(name: SfxName): Promise<void>
Plays a sound effect once. Several can play at the same time.
Returns a promise that resolves when the sound starts, not when it finishes.
How it works
- The first time a sound plays, it's loaded first, so there may be a short delay. After that it plays straight away.
- If there's no such file, nothing happens.
Example
onButtonPressed() {
AudioManager.PlaySFX("click");
},
PlayVoice
AudioManager.PlayVoice(name: VoiceName): Promise<void>
Plays a voice line once, using the voice volume. Otherwise it works like PlaySFX.
Example
onStart() {
AudioManager.PlayVoice("narrator_intro"); // in a chapter, [Voice(narrator_intro)] does the same
},
Volumes
There are six volumes: master, music, sfx, ambient, voice and video. Each is a number from 0 (silent) to 1 (full). Every other volume is multiplied by the master volume.
Get...Volume
AudioManager.GetMasterVolume(): number
AudioManager.GetMusicVolume(): number
AudioManager.GetSfxVolume(): number
AudioManager.GetAmbientVolume(): number
AudioManager.GetVoiceVolume(): number
AudioManager.GetVideoVolume(): number
Returns the volume, from 0 to 1.
Example
onEnter() {
this.dom.music_slider.value = String(AudioManager.GetMusicVolume() * 100); // slider from 0 to 100
},
Set...Volume
AudioManager.SetMasterVolume(volume: number): void
AudioManager.SetMusicVolume(volume: number): void
AudioManager.SetSfxVolume(volume: number): void
AudioManager.SetAmbientVolume(volume: number): void
AudioManager.SetVoiceVolume(volume: number): void
AudioManager.SetVideoVolume(volume: number): void
Changes a volume straight away. Values below 0 or above 1 are clamped.
How it works
The change isn't saved. Call SaveSettings() to keep it for next time.
Example
onMusicSliderChanged(value: number) {
AudioManager.SetMusicVolume(value / 100);
},
onMusicSliderReleased() {
AudioManager.SaveSettings(); // save once the player lets go, not on every step
},
ApplySettings
AudioManager.ApplySettings(settings: Record<string, any>): void
Sets several volumes at once. settings can have master, music, sfx, ambient, voice and video. Any it leaves out stay as they are.
Example
onResetVolumes() {
AudioManager.ApplySettings({ master: 1, music: 0.8, sfx: 1, ambient: 1, voice: 1, video: 1 });
AudioManager.SaveSettings();
},
SaveSettings
AudioManager.SaveSettings(): void
Saves all six volumes to the player's storage, so they're used next time the game starts.
LoadSettings
AudioManager.LoadSettings(): void
Sets the volumes to the ones last saved, or to 1 if none were saved. The game does this when it starts, so you only need it to undo changes that weren't saved.
Example
onCancelSettings() {
AudioManager.LoadSettings(); // back to the volumes from before the menu was opened
SceneManager.DetachScene("settings");
},
Adding sounds
RegisterAudio
AudioManager.RegisterAudio(name: string, url: string, type = "sfx", options?: { preload?: boolean }): void
Adds a sound that isn't in the project, from a url, so it can be played by name.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string |
The name to play it by | |
url |
string |
Where to load it from | |
type |
"sfx" | "music" | "ambient" | "voice" |
"sfx" |
What kind of sound it is |
options.preload |
boolean |
false |
Load a sound effect or voice line now, so it plays without a delay the first time |
RegisterMusic(name, url), RegisterAmbient(name, url), RegisterSFX(name, url) and RegisterVoice(name, url) do the same with the type filled in.
Example
onStart() {
AudioManager.RegisterSFX("server_ping", "https://example.com/sounds/ping.mp3");
AudioManager.PlaySFX("server_ping");
},
Unload
AudioManager.Unload(name: string): void
Frees the memory used by a sound effect or voice line that has been played. It's loaded again the next time it plays.
Example
onExit() {
AudioManager.Unload("boss_roar"); // only used in this scene
},
AttachVideo
AudioManager.AttachVideo(element: HTMLMediaElement): void
Routes a video or audio element's sound through the video volume. Video nodes are attached for you, so you only need this for elements you create yourself.
Example
onStart() {
const video = document.createElement("video");
video.src = Assets.GetVideo("credits")?.url ?? "";
AudioManager.AttachVideo(video); // now follows the video volume
this.root.appendChild(video);
video.play();
},
Events
Register
AudioManager.Register(eventName: string, handler: (...args: any[]) => void, owner?: object): void
Calls handler each time an audio event happens. Pass this as the owner to remove it when the scene exits (see The owner argument).
| Event | When | The handler receives |
|---|---|---|
MusicChanged |
PlayMusic started a new track |
The track's asset entry |
MusicStopped |
StopMusic stopped the music |
An empty array |
AmbientChanged |
PlayAmbient started a new loop |
The loop's asset entry |
AmbientStopped |
StopAmbient stopped the loop |
An empty array |
SFXPlayed |
A sound effect or a voice line started | Its name |
Example
onStart() {
AudioManager.Register("MusicChanged", this.showTrackName, this);
},
showTrackName(track: AssetEntry) {
this.dom.now_playing.textContent = `Now playing: ${track.key}`;
},
Unregister
AudioManager.Unregister(eventName: string, handler: (...args: any[]) => void, owner?: object): void
Removes a handler added with Register. Pass the same function, not a bound copy. UnregisterScene(owner) removes every handler that owner registered.
ctx
AudioManager.ctx: AudioContext
The Web Audio context all the game's sound goes through, for effects the methods above don't cover.
Example
beep() {
const ctx = AudioManager.ctx;
const tone = ctx.createOscillator();
tone.connect(ctx.destination);
tone.start();
tone.stop(ctx.currentTime + 0.2); // a fifth of a second
},