Audio
The Audio Manager in dill-pixel provides a robust system for handling audio playback in your game, including support for multiple channels, volume control, fading, and more.
Audio Channels
The Audio Manager comes with three default channels:
music
- For background musicsfx
- For sound effectsvoiceover
- For voice-over audio
// Access channels through the audio managerthis.app.audio.music; // music channelthis.app.audio.sfx; // sound effects channelthis.app.audio.vo; // voice-over channel (alias for voiceover)
Playing Audio
To play a sound, use the play
method:
// Basic playbackawait this.app.audio.play('click-sound', 'sfx');
// With optionsawait this.app.audio.play('background-music', 'music', { loop: true, volume: 0.5,});
// returns an AudioInstanceconst audioInstance = await this.app.audio.play('background-music', 'music', { loop: true, volume: 0.5,});
// Stop the audioaudioInstance.stop();
Loading Audio Assets
Audio assets can be loaded in several ways:
1. Through Asset Manifest
// In your scene or applicationexport const assets = { preload: { assets: { 'click-sound': '/assets/audio/click.mp3', 'background-music': '/assets/audio/music.mp3', }, // Or using bundles defined in your manifest bundles: ['game-audio'], },};
2. Manually Adding Audio
// Add individual soundthis.app.audio.add({ name: 'click-sound', src: '/assets/audio/click.mp3',});
// Add from manifestthis.app.audio.addAllFromManifest(manifest);
// Add from bundlethis.app.audio.addAllFromBundle('audio-bundle');
Volume Control
// Master volumethis.app.audio.masterVolume = 0.5;
// Channel volumethis.app.audio.setChannelVolume('music', 0.8);
// Multiple channels at oncethis.app.audio.setChannelVolume(['music', 'sfx'], 0.7);
Fading Audio
The Audio Manager provides several methods for smooth audio transitions:
// Fade to specific volumeawait this.app.audio.fade('background-music', 'music', { volume: 0.5, duration: 2,});
// Fade inawait this.app.audio.fadeIn('background-music', 'music', { duration: 1,});
// Fade outawait this.app.audio.fadeOut('background-music', 'music', { duration: 1,});
// Cross-fade between two tracksawait this.app.audio.crossFade( 'current-track', 'new-track', 'music', 2, // duration in seconds);
Global Audio Controls
// Mute/Unmute all audiothis.app.audio.mute();this.app.audio.unmute();
// Pause/Resume all audiothis.app.audio.pause();this.app.audio.resume();
// Stop all audiothis.app.audio.stopAll();
// Stop all with fadethis.app.audio.stopAll(true, 1); // fade duration in seconds
Event Handling
The Audio Manager provides several signals you can listen to:
// Sound started playingthis.app.audio.onSoundStarted.connect((detail) => { console.log(`Sound ${detail.id} started in ${detail.channelName} channel`);});
// Sound finished playingthis.app.audio.onSoundEnded.connect((detail) => { console.log(`Sound ${detail.id} ended in ${detail.channelName} channel`);});
// Volume changesthis.app.audio.onMasterVolumeChanged.connect((volume) => { console.log(`Master volume changed to ${volume}`);});
this.app.audio.onChannelVolumeChanged.connect((detail) => { console.log(`Channel ${detail.channel} volume changed to ${detail.volume}`);});
// Mute state changesthis.app.audio.onMuted.connect((muted) => { console.log(`Audio ${muted ? 'muted' : 'unmuted'}`);});
Custom Channels
You can create additional audio channels beyond the default ones:
// Create a new channelthis.app.audio.createChannel('ambient');
// Use the new channelawait this.app.audio.play('wind-sound', 'ambient');