Mirror Engine API / SoundComponent
Class: SoundComponent
The SoundComponent enables an Entity to play audio. The SoundComponent can manage multiple SoundSlots, each of which can play a different audio asset with its own set of properties such as volume, pitch, and looping behavior.
The SoundComponent supports positional audio, meaning that the sound can be played relative to the Entity's position in 3D space. This is useful for creating immersive audio experiences where the sound's volume and panning are affected by the listener's position and orientation. Positional audio requires that an Entity with an AudioListenerComponent be added to the scene.
You should never need to use the SoundComponent constructor directly. To add a SoundComponent to an Entity, use Entity#addComponent:
// Add a sound component to an entity
const entity = new Entity()
entity.addComponent('sound')
Then, to add a sound slot to the component:
entity.sound.addSlot('beep', {
asset: asset,
autoPlay: true,
loop: true,
overlap: true,
pitch: 1.5
})
Once the SoundComponent is added to the entity, you can set and get any of its properties:
entity.sound.volume = 0.8 // Set the volume for all sounds
console.log(entity.sound.volume) // Get the volume and print it
Extends
Component
Properties
entity
entity: Entity
The Entity that this Component is attached to.
Inherited from
Component.entity
system
system: ComponentSystem
The ComponentSystem used to create this Component.
Inherited from
Component.system
distanceModel
Get Signature
get distanceModel(): string
Gets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
Returns
string
Set Signature
set distanceModel(value: string): void
Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener. Can be:
- DISTANCE_LINEAR
- DISTANCE_INVERSE
- DISTANCE_EXPONENTIAL
Defaults to DISTANCE_LINEAR.
Parameters
value
string
Returns
void
enabled
Get Signature
get enabled(): boolean
Gets the enabled state of the component.
Returns
boolean
Set Signature
set enabled(arg: boolean): void
Sets the enabled state of the component.
Parameters
arg
boolean
Returns
void
Inherited from
Component.enabled
maxDistance
Get Signature
get maxDistance(): number
Gets the maximum distance from the listener at which audio falloff stops.
Returns
number
Set Signature
set maxDistance(value: number): void
Sets the maximum distance from the listener at which audio falloff stops. Note that the volume of the audio is not 0 after this distance, but just doesn't fall off anymore. Defaults to 10000.
Parameters
value
number
Returns
void
pitch
Get Signature
get pitch(): number
Gets the pitch modifier to play the audio with.
Returns
number
Set Signature
set pitch(value: number): void
Sets the pitch modifier to play the audio with. Must be larger than 0.01. Defaults to 1.
Parameters
value
number
Returns
void
positional
Get Signature
get positional(): boolean
Gets whether the component plays positional sound.
Returns
boolean
Set Signature
set positional(newValue: boolean): void
Sets whether the component plays positional sound. If true, the audio will play back at the location of the Entity in space, so the audio will be affected by the position of the AudioListenerComponent. Defaults to true.
Parameters
newValue
boolean
Returns
void
refDistance
Get Signature
get refDistance(): number
Gets the reference distance for reducing volume as the sound source moves further from the listener.
Returns
number
Set Signature
set refDistance(value: number): void
Sets the reference distance for reducing volume as the sound source moves further from the listener. Defaults to 1.
Parameters
value
number
Returns
void
rollOffFactor
Get Signature
get rollOffFactor(): number
Gets the factor used in the falloff equation.
Returns
number
Set Signature
set rollOffFactor(value: number): void
Sets the factor used in the falloff equation. Defaults to 1.
Parameters
value
number
Returns
void
slots
Get Signature
get slots(): {}
Gets a dictionary that contains the SoundSlots managed by this SoundComponent.
Returns
{
}
Set Signature
set slots(newValue: {}): void
Sets a dictionary that contains the SoundSlots managed by this SoundComponent.
Parameters
newValue
Returns
void
volume
Get Signature
get volume(): number
Gets the volume modifier to play the audio with.
Returns
number
Set Signature
set volume(value: number): void
Sets the volume modifier to play the audio with. In range 0-1. Defaults to 1.
Parameters
value
number
Returns
void
Methods
addSlot()
addSlot(name: string, options?: {
asset: number;
autoPlay: boolean;
duration: number;
loop: boolean;
overlap: boolean;
pitch: number;
startTime: number;
volume: number;
}): null | SoundSlot
Creates a new SoundSlot with the specified name.
Parameters
name
string
The name of the slot.
options?
Settings for the slot.
asset?
number
The asset id of the audio asset that is going to be played by this slot.
autoPlay?
boolean
If true, the slot will start playing as soon as its audio asset is loaded. Defaults to false.
duration?
number
The duration of the sound that the slot will play
starting from startTime. Defaults to null which means play to end of the sound.
loop?
boolean
If true, the sound will restart when it reaches the end. Defaults to false.
overlap?
boolean
If true, then sounds played from slot will be played independently of each other. Otherwise the slot will first stop the current sound before starting the new one. Defaults to false.
pitch?
number
The relative pitch. Defaults to 1 (plays at normal pitch).
startTime?
number
The start time from which the sound will start playing. Defaults to 0 to start at the beginning.
volume?
number
The playback volume, between 0 and 1. Defaults to 1.
Returns
null | SoundSlot
The new slot or null if the slot already exists.
Example
// get an asset by id
const asset = app.assets.get(10)
// add a slot
this.entity.sound.addSlot('beep', {
asset: asset
})
// play
this.entity.sound.play('beep')
fire()
fire(
name: string,
arg1?: any,
arg2?: any,
arg3?: any,
arg4?: any,
arg5?: any,
arg6?: any,
arg7?: any,
arg8?: any): EventHandler
Fire an event, all additional arguments are passed on to the event listener.
Parameters
name
string
Name of event to fire.
arg1?
any
First argument that is passed to the event handler.
arg2?
any
Second argument that is passed to the event handler.
arg3?
any
Third argument that is passed to the event handler.
arg4?
any
Fourth argument that is passed to the event handler.
arg5?
any
Fifth argument that is passed to the event handler.
arg6?
any
Sixth argument that is passed to the event handler.
arg7?
any
Seventh argument that is passed to the event handler.
arg8?
any
Eighth argument that is passed to the event handler.
Returns
Self for chaining.
Example
obj.fire('test', 'This is the message')
Inherited from
Component.fire
hasEvent()
hasEvent(name: string): boolean
Test if there are any handlers bound to an event name.
Parameters
name
string
The name of the event to test.
Returns
boolean
True if the object has handlers bound to the specified event name.
Example
obj.on('test', () => {}) // bind an event to 'test'
obj.hasEvent('test') // returns true
obj.hasEvent('hello') // returns false
Inherited from
Component.hasEvent
isLoaded()
isLoaded(name: string): boolean
Returns true if the asset of the slot with the specified name is loaded..
Parameters
name
string
The name of the SoundSlot to look for.
Returns
boolean
True if the slot with the specified name exists and its asset is loaded.
isPaused()
isPaused(name: string): boolean
Returns true if the slot with the specified name is currently paused.
Parameters
name
string
The name of the SoundSlot to look for.
Returns
boolean
True if the slot with the specified name exists and is currently paused.
isPlaying()
isPlaying(name: string): boolean
Returns true if the slot with the specified name is currently playing.
Parameters
name
string
The name of the SoundSlot to look for.
Returns
boolean
True if the slot with the specified name exists and is currently playing.
isStopped()
isStopped(name: string): boolean
Returns true if the slot with the specified name is currently stopped.
Parameters
name
string
The name of the SoundSlot to look for.
Returns
boolean
True if the slot with the specified name exists and is currently stopped.
off()
off(
name?: string,
callback?: HandleEventCallback,
scope?: any): EventHandler
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Parameters
name?
string
Name of the event to unbind.
callback?
HandleEventCallback
Function to be unbound.
scope?
any
Scope that was used as the this when the event is fired.
Returns
Self for chaining.
Example
const handler = () => {}
obj.on('test', handler)
obj.off() // Removes all events
obj.off('test') // Removes all events called 'test'
obj.off('test', handler) // Removes all handler functions, called 'test'
obj.off('test', handler, this) // Removes all handler functions, called 'test' with scope this
Inherited from
Component.off
on()
on(
name: string,
callback: HandleEventCallback,
scope?: any): EventHandle
Attach an event handler to an event.
Parameters
name
string
Name of the event to bind the callback to.
callback
HandleEventCallback
Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
Can be used for removing event in the future.
Examples
obj.on('test', (a, b) => {
console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
const evt = obj.on('test', (a, b) => {
console.log(a + b)
})
// some time later
evt.off()
Inherited from
Component.on
once()
once(
name: string,
callback: HandleEventCallback,
scope?: any): EventHandle
Attach an event handler to an event. This handler will be removed after being fired once.
Parameters
name
string
Name of the event to bind the callback to.
callback
HandleEventCallback
Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
- can be used for removing event in the future.
Example
obj.once('test', (a, b) => {
console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
obj.fire('test', 1, 2) // not going to get handled
Inherited from
Component.once
pause()
pause(name?: string): void
Pauses playback of the slot with the specified name. If the name is undefined then all slots currently played will be paused. The slots can be resumed by calling SoundComponent#resume.
Parameters
name?
string
The name of the slot to pause. Leave undefined to pause everything.
Returns
void
Example
// pause all sounds
this.entity.sound.pause()
// pause a specific sound
this.entity.sound.pause('beep')
play()
play(name: string): null | SoundInstance
Begins playing the sound slot with the specified name. The slot will restart playing if it is already playing unless the overlap field is true in which case a new sound will be created and played.
Parameters
name
string
The name of the SoundSlot to play.
Returns
null | SoundInstance
The sound instance that will be played. Returns null if the component or its parent entity is disabled or if the SoundComponent has no slot with the specified name.
Example
// get asset by id
const asset = app.assets.get(10)
// create a slot and play it
this.entity.sound.addSlot('beep', {
asset: asset
})
this.entity.sound.play('beep')
removeSlot()
removeSlot(name: string): void
Removes the SoundSlot with the specified name.
Parameters
name
string
The name of the slot.
Returns
void
Example
// remove a slot called 'beep'
this.entity.sound.removeSlot('beep')
resume()
resume(name?: string): void
Resumes playback of the sound slot with the specified name if it's paused. If no name is specified all slots will be resumed.
Parameters
name?
string
The name of the slot to resume. Leave undefined to resume everything.
Returns
void
Example
// resume all sounds
this.entity.sound.resume()
// resume a specific sound
this.entity.sound.resume('beep')
slot()
slot(name: string): undefined | SoundSlot
Returns the slot with the specified name.
Parameters
name
string
The name of the slot.
Returns
undefined | SoundSlot
The slot.
Example
// get a slot and set its volume
this.entity.sound.slot('beep').volume = 0.5
stop()
stop(name?: string): void
Stops playback of the sound slot with the specified name if it's paused. If no name is specified all slots will be stopped.
Parameters
name?
string
The name of the slot to stop. Leave undefined to stop everything.
Returns
void
Example
// stop all sounds
this.entity.sound.stop()
// stop a specific sound
this.entity.sound.stop('beep')
Events
EVENT_END
static EVENT_END: string = 'end';
Fired when a sound instance stops playing because it reached its end. The handler is passed the SoundSlot and the SoundInstance that ended.
Example
entity.sound.on('end', (slot, instance) => {
console.log(`Sound ${'${slot.name}'} ended`)
})
EVENT_PAUSE
static EVENT_PAUSE: string = 'pause';
Fired when a sound instance is paused. The handler is passed the SoundSlot and the SoundInstance that was paused.
Example
entity.sound.on('pause', (slot, instance) => {
console.log(`Sound ${'${slot.name}'} paused`)
})
EVENT_PLAY
static EVENT_PLAY: string = 'play';
Fired when a sound instance starts playing. The handler is passed the SoundSlot and the SoundInstance that started playing.
Example
entity.sound.on('play', (slot, instance) => {
console.log(`Sound ${'${slot.name}'} started playing`)
})
EVENT_RESUME
static EVENT_RESUME: string = 'resume';
Fired when a sound instance is resumed. The handler is passed the SoundSlot and the SoundInstance that was resumed.
Example
entity.sound.on('resume', (slot, instance) => {
console.log(`Sound ${'${slot.name}'} resumed`)
})
EVENT_STOP
static EVENT_STOP: string = 'stop';
Fired when a sound instance is stopped. The handler is passed the SoundSlot and the SoundInstance that was stopped.
Example
entity.sound.on('stop', (slot, instance) => {
console.log(`Sound ${'${slot.name}'} stopped`)
})