API Reference

Class List

pc.SoundComponent

Extends: pc.Component

The Sound Component controls playback of pc.Sounds.

Summary

Properties

distanceModel

Determines which algorithm to use to reduce the volume of the sound as it moves away from the listener.

maxDistance

The maximum distance from the listener at which audio falloff stops.

pitch

The pitch modifier to play the audio with.

positional

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 pc.AudioListenerComponent.

refDistance

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

rollOffFactor

The factor used in the falloff equation.

slots

A dictionary that contains the pc.SoundSlots managed by this SoundComponent.

volume

The volume modifier to play the audio with.

Methods

addSlot

Creates a new pc.SoundSlot with the specified name.

pause

Pauses playback of the slot with the specified name.

play

Begins playing the sound slot with the specified name.

removeSlot

Removes the pc.SoundSlot with the specified name.

resume

Resumes playback of the sound slot with the specified name if it's paused.

slot

Returns the slot with the specified name.

stop

Stops playback of the sound slot with the specified name if it's paused.

Events

end

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

pause

Fired when a sound instance is paused.

play

Fired when a sound instance starts playing.

resume

Fired when a sound instance is resumed.

stop

Fired when a sound instance is stopped.

Inherited

Properties

enabled

Enables or disables the component.

entity

The Entity that this Component is attached to.

system

The ComponentSystem used to create this Component.

Methods

fire

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

hasEvent

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

off

Detach an event handler from an event.

on

Attach an event handler to an event.

once

Attach an event handler to an event.

Details

Constructor

SoundComponent(system, entity)

Create a new Sound Component.

Parameters

systempc.SoundComponentSystem

The ComponentSystem that created this component.

entitypc.Entity

The entity that the Component is attached to.

Properties

stringdistanceModel

Determines which algorithm to use to reduce the volume of the sound as it moves away from the listener. Can be:

Defaults to pc.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 pc.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.

objectslots

A dictionary that contains the pc.SoundSlots managed by this SoundComponent.

numbervolume

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

Methods

addSlot(name, [options])

Creates a new pc.SoundSlot with the specified name.

// get an asset by id
var asset = app.assets.get(10);
// add a slot
this.entity.sound.addSlot('beep', {
    asset: asset
});
// play
this.entity.sound.play('beep');

Parameters

namestring

The name of the slot.

optionsobject

Settings for the slot.

options.volumenumber

The playback volume, between 0 and 1.

options.pitchnumber

The relative pitch, default of 1, plays at normal pitch.

options.loopboolean

If true the sound will restart when it reaches the end.

options.startTimenumber

The start time from which the sound will start playing.

options.durationnumber

The duration of the sound that the slot will play starting from startTime.

options.overlapboolean

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.

options.autoPlayboolean

If true the slot will start playing as soon as its audio asset is loaded.

options.assetnumber

The asset id of the audio asset that is going to be played by this slot.

Returns

pc.SoundSlot

The new slot.

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 pc.SoundComponent#resume.

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

Parameters

namestring

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
var asset = app.assets.get(10);
// create a slot and play it
this.entity.sound.addSlot('beep', {
    asset: asset
});
this.entity.sound.play('beep');

Parameters

namestring

The name of the pc.SoundSlot to play.

Returns

pc.SoundInstance

The sound instance that will be played.

removeSlot(name)

Removes the pc.SoundSlot with the specified name.

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

Parameters

namestring

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

namestring

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

namestring

The name of the slot.

Returns

pc.SoundSlot

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

namestring

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

Events

end

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

Parameters

slotpc.SoundSlot

The slot whose instance ended.

instancepc.SoundInstance

The instance that ended.

pause

Fired when a sound instance is paused.

Parameters

slotpc.SoundSlot

The slot whose instance was paused.

instancepc.SoundInstance

The instance that was paused created to play the sound.

play

Fired when a sound instance starts playing.

Parameters

slotpc.SoundSlot

The slot whose instance started playing.

instancepc.SoundInstance

The instance that started playing.

resume

Fired when a sound instance is resumed..

Parameters

slotpc.SoundSlot

The slot whose instance was resumed.

instancepc.SoundInstance

The instance that was resumed.

stop

Fired when a sound instance is stopped.

Parameters

slotpc.SoundSlot

The slot whose instance was stopped.

instancepc.SoundInstance

The instance that was stopped.

Inherited

Properties

booleanenabled

Enables or disables the component.

pc.Entityentity

The Entity that this Component is attached to.

pc.ComponentSystemsystem

The ComponentSystem used to create this Component.

Methods

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

nameobject

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

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

namestring

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.

var 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 hander functions, called 'test' with scope this

Parameters

namestring

Name of the event to unbind.

callbackpc.callbacks.HandleEvent

Function to be unbound.

scopeobject

Scope that was used as the this when the event is fired.

Returns

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

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scopeobject

Object to use as 'this' when the event is fired, defaults to current this.

Returns

pc.EventHandler

Self for chaining.

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

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

Function that is called when event is fired. Note the callback is limited to 8 arguments.

scopeobject

Object to use as 'this' when the event is fired, defaults to current this.

Returns

pc.EventHandler

Self for chaining.