API Documentation for: 0.11.8
Show:

platypus.components.AudioSFX Class

Module: platypus

Available since 0.6.0

This component plays audio using the SpringRoll Sound instance. Audio is played in one of two ways, by triggering specific messages defined in the audio component definition or using an audio map which plays sounds when the entity enters specified states.

Methods

'*'

(
  • message.interrupt
  • message.delay
  • message.offset
  • message.length
  • message.loop
  • message.volume
  • message.pan
  • message.next
)

Defined in '*':199

Listens for messages specified by the audioMap and on receiving them, begins playing corresponding audio clips. Audio play message can optionally include several parameters, many of which correspond with SoundJS play parameters.

Parameters:

  • message.interrupt Object

    (string) - Optional. Can be "any", "early", "late", or "none". Determines how to handle the audio when it's already playing but a new play request is received. Default is "any".

  • message.delay Object

    (integer) - Optional. Time in milliseconds to wait before playing audio once the message is received. Default is 0.

  • message.offset Object

    (integer) - Optional. Time in milliseconds determining where in the audio clip to begin playback. Default is 0.

  • message.length Object

    (integer) - Optional. Time in milliseconds to play audio before stopping it. If 0 or not specified, play continues to the end of the audio clip.

  • message.loop Object

    (integer) - Optional. Determines how many more times to play the audio clip once it finishes. Set to -1 for an infinite loop. Default is 0.

  • message.volume Object

    (float) - Optional. Used to specify how loud to play audio on a range from 0 (mute) to 1 (full volume). Default is 1.

  • message.pan Object

    (float) - Optional. Used to specify the pan of audio on a range of -1 (left) to 1 (right). Default is 0.

  • message.next Object

    (string) - Optional. Used to specify the next audio clip to play once this one is complete.

'handle-render'

()

Defined in 'handle-render':226

On each handle-render message, this component checks its list of playing audio clips and stops any clips whose play length has been reached.

'mute-audio'

(
  • audioId
)

Defined in 'mute-audio':295

On receiving this message all audio will mute, or a particular sound instance will mute if an id is specified.

Parameters:

  • audioId String

    If an audioId is provided, that particular sound instance will mute. Otherwise all audio is muted.

'pause-audio'

(
  • audioId
)

Defined in 'pause-audio':325

On receiving this message all audio will pause, or a particular sound instance will pause if an id is specified.

Parameters:

  • audioId String

    If an audioId is provided, that particular sound instance will pause. Otherwise all audio is paused.

'set-pan'

(
  • pan
  • [soundId]
)

Defined in 'set-pan':353

Available since 0.11.3

This message sets the volume of playing audio.

Parameters:

  • pan Number

    A number from -1 to 1 that sets the pan.

  • [soundId] String optional

    If an soundId is provided, that particular sound instance's pan is set.

'set-volume'

(
  • volume
  • [soundId]
)

Defined in 'set-volume':376

This message sets the volume of playing audio.

Parameters:

  • volume Number

    A number from 0 to 1 that sets the volume.

  • [soundId] String optional

    If an soundId is provided, that particular sound instance's volume is set. Otherwise all audio volume is changed.

'state-changed'

()

Defined in 'state-changed':250

This component listens for changes to the entity state and tests the current state of the entity against the audio map. If a match is found, the matching audio clip is played.

'stop-audio'

(
  • audioId
)

Defined in 'stop-audio':279

On receiving this message, audio will stop playing.

Parameters:

  • audioId String

    If an audioId is provided, that particular sound instance is stopped. Otherwise all audio is stopped.

'toggle-mute'

(
  • audioId
)

Defined in 'toggle-mute':259

On receiving this message, the audio will mute if unmuted, and unmute if muted.

Parameters:

  • audioId String

    If an audioId is provided, that particular sound instance is toggled. Otherwise all audio is toggled from mute to unmute or vice versa.

'unmute-audio'

(
  • audioId
)

Defined in 'unmute-audio':310

On receiving this message all audio will unmute, or a particular sound instance will unmute if an id is specified.

Parameters:

  • audioId String

    If an audioId is provided, that particular sound instance will unmute. Otherwise all audio is unmuted.

'unpause-audio'

(
  • audioId
)

Defined in 'unpause-audio':339

On receiving this message all audio will unpause, or a particular sound instance will unpause if an id is specified.

Parameters:

  • audioId String

    If an audioId is provided, that particular sound instance will unpause. Otherwise all audio is unpaused.

addEventListener

(
  • event
  • callback
)
Function private
This method adds an event listener to the entity.

Parameters:

  • event String
    The event that this component should listen for.
  • callback Function
    The handler for the event.

Returns:

Function: handler A reference to the bound handler.

addMethod

(
  • name
  • func
)
private
This method adds a method to the entity.

Parameters:

  • name String
    The name of the method. For example, if name is "turnYellow", the method is accessible on the entity as entity.turnYellow().
  • func Function
    The function describing the method.

destroy

() private

Inherited from platypus.Component: destroy:54

This method cleans up listeners and methods that this component added to the entity. It should never be called by the component itself. Call this.owner.removeComponent(this) instead.

getAssetList

(
  • definition
  • properties
  • defaultProperties
)
Array
This method can be overwritten to provide the list of assets this component requires. This method is invoked when the list of game scenes is created to determine assets for each scene.

Parameters:

  • definition Object
    The definition for the component.
  • properties Object
    The properties of the Entity.
  • defaultProperties Object
    The default properties of the Entity.

Returns:

Array: A list of the necessary assets to load.

getLateAssetList

(
  • data
)
Array
This method can be overwritten to provide the list of assets this component requires. This method is invoked when the list of game scenes is created to determine assets for each scene.

Parameters:

  • data Object
    Scene data that affects the list of assets.

Returns:

Array: A list of the necessary assets to load.

removeEventListener

(
  • event
  • callback
)
private
This method removes an event listener from the entity.

Parameters:

  • event String
    The event for which to remove a listener.
  • callback Function
    The listener to remove. If not supplied, all event listeners for the provided event are removed.

removeEventListeners

(
  • [listeners]
)
private
This method removes multiple event listeners from the entity.

Parameters:

  • [listeners] Array optional
    The list of listeners to remove. If not supplied, all event listeners are removed.

removeMethod

(
  • name
)
private
This method removes a method from the entity.

Parameters:

  • name String
    The name of the method to be removed.

toJSON

() Object

Inherited from platypus.Component: toJSON:45

Available since 0.11.0

Returns a JSON object describing the component.

Returns:

Object: Returns a JSON definition that can be used to recreate the component.

toString

() String
Returns a string describing the component.

Returns:

String: Returns the component type as a string of the form "[Component ComponentType]".

Properties

audioMap

Object

Defined in audioMap:103

Use the audioMap property object to map messages triggered with audio clips to play. At least one audio mapping should be included for audio to play. Here is an example audioMap object:

  {
                                                  "message-triggered": "audio-id",
                                                  // This simple form is useful to listen for "message-triggered" and play "audio-id" using default audio properties.
                                            
                                                  "another-message": {
                                                  // To specify audio properties, instead of mapping the message to an audio id string, map it to an object with one or more of the properties shown below. Many of these properties directly correspond to SoundJS play parameters.
                                            
                                                      "sound": "another-audio-id",
                                                      // Required. This is the audio clip to play when "another-message" is triggered.
                                            
                                                      "interrupt": "none",
                                                      // Optional. Can be "any", "early", "late", or "none". Determines how to handle the audio when it's already playing but a new play request is received. Default is "any".
                                            
                                                      "delay": 500,
                                                      // Optional. Time in milliseconds to wait before playing audio once the message is received. Default is 0.
                                            
                                                      "offset": 1500,
                                                      // Optional. Time in milliseconds determining where in the audio clip to begin playback. Default is 0.
                                            
                                                      "length": 2500,
                                                      // Optional. Time in milliseconds to play audio before stopping it. If 0 or not specified, play continues to the end of the audio clip.
                                            
                                                      "loop": 4,
                                                      // Optional. Determines how many more times to play the audio clip once it finishes. Set to -1 for an infinite loop. Default is 0.
                                            
                                                      "volume": 0.75,
                                                      // Optional. Used to specify how loud to play audio on a range from 0 (mute) to 1 (full volume). Default is 1.
                                            
                                                      "pan": -0.25
                                                      // Optional. Used to specify the pan of audio on a range of -1 (left) to 1 (right). Default is 0.
                                                  }
                                              }

Default: null

eventBased

Boolean

Defined in eventBased:154

Available since 0.7.5

Optional. Specifies whether this component should listen to events matching the animationMap to animate. Set this to true if the component should animate for on events.

Default: true

forcePlayThrough

Boolean

Determines whether a sound that's started should play through completely regardless of entity state changes.

Default: true

stateBased

Boolean

Defined in stateBased:164

Available since 0.7.5 - Defaults to `true` prior to version 0.9.0

Optional. Specifies whether this component should listen to changes in the entity's state that match the animationMap to animate. Set this to true if the component should animate based on this.owner.state.

Default: false

Events

clip-complete

Defined in clip-complete:33

When a sound effect is finished playing, this event is triggered.