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.
Load, then play
Section titled “Load, then play”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);loadrejects when the file is missing or is not audio. A load that failed can be tried again.playandplayMusicnever throw. For a URL that is not loaded they do nothing and returnundefined, so a missing sound does not break a game.
Effects
Section titled “Effects”audio.play(COIN, { volume: 0.5, rate: 1.1 });
const hum = audio.play('/assets/sounds/hum.wav', { loop: true });hum?.stop();| Option | Default | What it sets |
|---|---|---|
volume | 1 | Loudness of this one sound, 0 to 1 |
rate | 1 | Playback speed, which also shifts the pitch |
loop | false, and true for music | Starts 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:
playMusicstops 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.musicis the URL of the music that is on, andundefinedwhen there is none.
Volume
Section titled “Volume”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.
When sound is silent
Section titled “When sound is silent”- Before the first press. A browser keeps a page silent until its user clicks or presses a
key. Until then
playstarts nothing and returnsundefined: 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
loadfetches nothing, andplayandplayMusicstart nothing.
Each world with AudioPlugin has its own sound, with its own volumes and mute.
In the editor
Section titled “In the editor”- 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,.oggor.mp3file, and the panel plays the one that is selected. Its address is whatloadtakes:/assets/sounds/coin.wavforsounds/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.
What a game asked for
Section titled “What a game asked for”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.
Exports
Section titled “Exports”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.