SoundComponent(system, entity) 

Create a new Sound Component.

Parameters

system	SoundComponentSystem	The ComponentSystem that created this component.
entity	Entity	The entity that the Component is attached to.

stringdistanceModel 

Determines 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.

numbermaxDistance 

The maximum distance from the listener at which audio falloff stops. Note the volume of the audio is not 0 after this distance, but just doesn't fall off anymore. Defaults to 10000.

numberpitch 

The pitch modifier to play the audio with. Must be larger than 0.01. Defaults to 1.

booleanpositional 

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.

numberrefDistance 

The reference distance for reducing volume as the sound source moves further from the listener. Defaults to 1.

numberrollOffFactor 

The factor used in the falloff equation. Defaults to 1.

{ [string]: SoundSlot }slots 

A dictionary that contains the SoundSlots managed by this SoundComponent.

numbervolume 

The volume modifier to play the audio with. In range 0-1. Defaults to 1.

addSlot(name, [options]) 

Creates a new SoundSlot with the specified name.

// 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');

Parameters

name	string	The name of the slot.
options	object	Settings for the slot.
options.volume	number	The playback volume, between 0 and 1. Defaults to 1.
options.pitch	number	The relative pitch. Defaults to 1 (plays at normal pitch).
options.loop	boolean	If true the sound will restart when it reaches the end. Defaults to false.
options.startTime	number	The start time from which the sound will start playing. Defaults to 0 to start at the beginning.
options.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.
options.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.
options.autoPlay	boolean	If true the slot will start playing as soon as its audio asset is loaded. Defaults to false.
options.asset	number	The asset id of the audio asset that is going to be played by this slot.

Returns

SoundSlot, null

The new slot or null if the slot already exists.

isLoaded(name) 

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(name) 

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(name) 

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(name) 

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.

pause([name]) 

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.

// pause all sounds
this.entity.sound.pause();
// pause a specific sound
this.entity.sound.pause('beep');

Parameters

name

string

The name of the slot to pause. Leave undefined to pause everything.

play(name) 

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.

// 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');

Parameters

name

string

The name of the SoundSlot to play.

Returns

SoundInstance, null

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.

removeSlot(name) 

Removes the SoundSlot with the specified name.

// remove a slot called 'beep'
this.entity.sound.removeSlot('beep');

Parameters

name

string

The name of the slot.

resume([name]) 

Resumes playback of the sound slot with the specified name if it's paused. If no name is specified all slots will be resumed.

// resume all sounds
this.entity.sound.resume();
// resume a specific sound
this.entity.sound.resume('beep');

Parameters

name

string

The name of the slot to resume. Leave undefined to resume everything.

slot(name) 

Returns the slot with the specified name.

// get a slot and set its volume
this.entity.sound.slot('beep').volume = 0.5;

Parameters

name

string

The name of the slot.

Returns

SoundSlot, undefined

The slot.

stop([name]) 

Stops playback of the sound slot with the specified name if it's paused. If no name is specified all slots will be stopped.

// stop all sounds
this.entity.sound.stop();
// stop a specific sound
this.entity.sound.stop('beep');

Parameters

name

string

The name of the slot to stop. Leave undefined to stop everything.

end 

Fired when a sound instance stops playing because it reached its ending.

Parameters

slot	SoundSlot	The slot whose instance ended.
instance	SoundInstance	The instance that ended.

pause 

Fired when a sound instance is paused.

Parameters

slot	SoundSlot	The slot whose instance was paused.
instance	SoundInstance	The instance that was paused created to play the sound.

play 

Fired when a sound instance starts playing.

Parameters

slot	SoundSlot	The slot whose instance started playing.
instance	SoundInstance	The instance that started playing.

resume 

Fired when a sound instance is resumed.

Parameters

slot	SoundSlot	The slot whose instance was resumed.
instance	SoundInstance	The instance that was resumed.

stop 

Fired when a sound instance is stopped.

Parameters

slot	SoundSlot	The slot whose instance was stopped.
instance	SoundInstance	The instance that was stopped.

booleanenabled 

Enables or disables the component.

Entityentity 

The Entity that this Component is attached to.

ComponentSystemsystem 

The ComponentSystem used to create this Component.

fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8]) 

Fire an event, all additional arguments are passed on to the event listener.

obj.fire('test', 'This is the message');

Parameters

name	string	Name of event to fire.
arg1	*	First argument that is passed to the event handler.
arg2	*	Second argument that is passed to the event handler.
arg3	*	Third argument that is passed to the event handler.
arg4	*	Fourth argument that is passed to the event handler.
arg5	*	Fifth argument that is passed to the event handler.
arg6	*	Sixth argument that is passed to the event handler.
arg7	*	Seventh argument that is passed to the event handler.
arg8	*	Eighth argument that is passed to the event handler.

Returns

EventHandler

Self for chaining.

hasEvent(name) 

Test if there are any handlers bound to an event name.

obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false

Parameters

name

string

The name of the event to test.

Returns

boolean

True if the object has handlers bound to the specified event name.

off([name], [callback], [scope]) 

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.

const handler = function () {
};
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

Parameters

name	string	Name of the event to unbind.
callback	HandleEventCallback	Function to be unbound.
scope	object	Scope that was used as the this when the event is fired.

Returns

EventHandler

Self for chaining.

on(name, callback, [scope]) 

Attach an event handler to an event.

obj.on('test', function (a, b) {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console

const evt = obj.on('test', function (a, b) {
    console.log(a + b);
});
// some time later
evt.off();

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	object	Object to use as 'this' when the event is fired, defaults to current this.

Returns

EventHandle

Can be used for removing event in the future.

once(name, callback, [scope]) 

Attach an event handler to an event. This handler will be removed after being fired once.

obj.once('test', function (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

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	object	Object to use as 'this' when the event is fired, defaults to current this.

Returns

EventHandle

• can be used for removing event in the future.