Skip to content

Sound

@shell/audio plays sound files through Web Audio. A game has effects and one piece of music, each with a volume of its own, and a master volume and a mute over both.

BrowserPlugin, and so Engine2D and Engine3D, already installs AudioPlugin. BrowserHostPlugin does not. A world without it adds the plugin itself:

import { AudioPlugin } from '@shell/engine-2d';
world.addPlugin(AudioPlugin);

The resource is audio: world.get('audio'), or resources.get('audio') in a system.

A sound is named by its URL. load fetches and decodes it once. play and playMusic start only sounds that are loaded.

import { AudioPlugin, Define, type World } from '@shell/engine-2d';
const COIN = '/assets/sounds/coin.wav';
const THEME = '/assets/sounds/theme.ogg';
export const SoundGame = Define.plugin('sound-game').build((world: World) => {
world.addPlugin(AudioPlugin);
const audio = world.get('audio');
world.get('lifecycle').register({
load: async () => {
await Promise.all([audio.load(COIN), audio.load(THEME)]);
audio.playMusic(THEME);
},
});
});

Then, where a coin is taken:

audio.play(COIN);
  • load rejects when the file is missing or is not audio. A load that failed can be tried again.
  • play and playMusic never throw. For a URL that is not loaded they do nothing and return undefined, so a missing sound does not break a game.
audio.play(COIN, { volume: 0.5, rate: 1.1 });
const hum = audio.play('/assets/sounds/hum.wav', { loop: true });
hum?.stop();
OptionDefaultWhat it sets
volume1Loudness of this one sound, 0 to 1
rate1Playback speed, which also shifts the pitch
loopfalse, and true for musicStarts again from the beginning until it is stopped

play gives a handle with stop(), or undefined when it started nothing. Change rate by a few percent each time a repeated effect plays, so that it does not sound mechanical.

const music = audio.playMusic(THEME);
audio.playMusic('/assets/sounds/boss.ogg'); // The theme stops.
music?.stop();
  • Music loops.
  • There is one music at a time: playMusic stops the music that was started before it. Asking for the music that already plays starts it over and leaves one copy, not two.
  • A game can ask for its music at startup, before the player has pressed anything. It starts with the first press (see below).
  • A second loop beside the music is an effect: play(url, { loop: true }).
  • audio.music is the URL of the music that is on, and undefined when there is none.
audio.musicVolume = 0.4; // The music only.
audio.effectsVolume = 0.8; // Everything `play` starts.
audio.volume = 0.5; // Over both.
audio.muted = true; // Silences both.

Each volume goes from 0 to 1, and a value outside is brought to the nearest of the two. Keeping the player’s choice from one visit to the next is the game’s job.

  • Before the first press. A browser keeps a page silent until its user clicks or presses a key. Until then play starts nothing and returns undefined: an effect that was held back would sound late, all at once with the others. Music asked for before the first press starts with it.
  • While the game does not run. Sound stops while the world is paused (world.pause(), or a hidden tab) and while its ticker is stopped, which is what the editor’s Pause and Step do. It goes on from where it was when the game goes on. An effect asked for in between is dropped, and music asked for in between starts when the game goes on.
  • After the world is gone. Unmounting or disposing a world closes its sound.
  • In a world that is only edited. A world in edit mode, as the editor’s own, makes no sound at all: there load fetches nothing, and play and playMusic start nothing.

Each world with AudioPlugin has its own sound, with its own volumes and mute.

  • Play is the press. A game’s sound is heard from Play on, its music too: the press on Play is the one a browser waits for.
  • Pause and Step are silent. On Play again the sound goes on from where it was. Stop ends it.
  • Editing is silent. A game that asks for its music as it loads is not heard while its scene is only edited.
  • A sound file is an asset. ”+ New ▸ Import files…” in the Assets panel brings in a .wav, .ogg or .mp3 file, and the panel plays the one that is selected. Its address is what load takes: /assets/sounds/coin.wav for sounds/coin.wav.
  • A sound can be picked in the inspector. Keep its address in a component field with meta: { widget: 'asset', assetKind: 'audio' }, and the inspector lists the Project’s sound files for it.
  • The Agent makes a sound from notes. Asked for a sound when no file was brought, it writes one with its tool write_sound: a list of notes that the editor mixes into a WAV file in the asset folder. The notes are not kept, so to change a sound the Agent gives all its notes again.

onPlay is a set of callbacks. Each is called when the game asks for a sound, also for one that does not start: before the first press, while the game is paused, or with a URL that is not loaded. loaded says whether the file is there, and loading whether its load is still under way.

audio.onPlay.add(({ url, music, loaded }) => {
console.log(music ? 'music' : 'effect', url, loaded ? '' : 'was not loaded');
});

The editor’s Agent cannot hear a game. Its tools play_step, play_keys and play_pointer use this to tell it which sounds the game asked for in the frames they advanced.

export { AudioPlugin } from './plugin';
export { AudioHandle, AudioPlayer, type AskedSound, type PlayOptions } from './audio-player';

The engine packages (@shell/engine-minimal, @shell/engine-2d, @shell/engine-3d) export the same names.