Behavior element behavior adding speaker support.

Behavior adds a Speaker resource to the the behavior element.

If the ECBehaviorCollider is present in the behavior element before this behavior is added the speaker is attached. The speaker is attached to the named bone if defined otherwise it is attached statically.

Speakers can play either a static Sound resource or use a Synthesizer. By using a synthesizer dynamic sound can be played. To use a synthesizer use the speaker{(id)}.synthesizer property instead of the speaker{(id)}.sound property. If both properties are present the synthesizer one is used if valid otherwise sound.

If synthesizer is valid a SynthesizerInstance will be created. Subclasses of ECBehaviorSpeaker or other behaviors can then obtain SynthesizerController from the SynthesizerInstance to modify the played sound. Since controllers use curves behaviors have to set the value ahead of time before playing back the speaker. It is possible to change the controller curves while sound is playing. In this case though care has to be taken to be set the curve early enough since audio modules typically render sound into buffered blocks. If the curve is changed too late the changes can be missed or result in strange sound jumping.

See also:

• Synthesizers
• IGDE Synthesizer Editor

This behavior can be added multiple times to an element. Each instance creates one speaker attached to the element collider which can be individually modified. To distinguish the speakers each instance has an identifier which can be used to retrieve a specific instance. Hence to use more than one speaker use code like this in your subclass constructor:

class MyElement extends BehaviorElementClass
  func new()
    ECBehaviorSpeaker.new(this)
    ECBehaviorSpeaker.new(this, "subSpeaker")
  end
end

You can now define the parameters to use for both speakers using for example the properties speaker.volume for the first speaker and speaker(subSpeaker).volume for the second speaker.

It is recommended to always specify an identifier even if only one speaker is used. This avoids potentially name conflicts especially if other behaviors are added attaching other resources too.

Element class properties have the prefix speaker. or speaker({id}). if id is not empty.

Speaker type.

• Full name: speaker.type or speaker({id}).type
• Type: enumeration

• Allowed Values:

  Value	Description
  point	Omnidirectional.
  directed	Directed.

• Default Value: point
• Example (*.deeclass)

  <string name='speaker.type'>directed</string>

Path of sound resource to use.

• Full name: speaker.sound or speaker({id}).sound
• Type: string
• Default Value: empty string
• Expected File Type: *.ogg (all sound modules)
• Example (*.deeclass)

  <string name='speaker.sound'>click.ogg</string>

Path of synthesizer resource to use.

• Full name: speaker.synthesizer or speaker({id}).synthesizer
• Type: string
• Default Value: empty string
• Expected File Type: *.desynth
• Example (*.deeclass)

  <string name='speaker.synthesizer'>sound.desynth</string>

Speaker volume.

• Full name: speaker.volume or speaker({id}).volume
• Type: float
• Default Value: 1
• Restriction: At least 0
• Example (*.deeclass)

  <float name='speaker.volume'>0.8</float>

Speaker range in meters. Speaker is inaudible beyond range.

• Full name: speaker.range or speaker({id}).range
• Type: float
• Default Value: 30
• Restriction: At least 0
• Example (*.deeclass)

  <float name='speaker.range'>20</float>

Roll off. Value 1 is realistic (normal) roll-off. Values larger than 1 reduce volume faster near the sound source. Values smaller than 1 reduce volume faster near the sound range.

• Full name: speaker.rollOff or speaker({id}).rollOff
• Type: float
• Default Value: 1
• Restriction: At least 0
• Example (*.deeclass)

  <float name='speaker.rollOff'>1.5</float>

Distance offset for attenuation calculation. For use by distance sounds. Offsets the true distance to the sound source for attenuation calculation to make the sound appear coming from far away. Requires increasing the volume to compensate for the distance increased attenuation.

• Full name: speaker.distanceOffset or speaker({id}).distanceOffset
• Type: float
• Default Value: 0
• Restriction: At least 0
• Example (*.deeclass)

  <float name='speaker.distanceOffset'>500</float>

Play speed. Value of 1 is normal play speed. Values larger than 1 are faster (1.5 for example 150% play speed). Values less than 1 are slower (0.75 for example 75% play speed).

• Full name: speaker.playSpeed or speaker({id}).playSpeed
• Type: float
• Default Value: 1
• Example (*.deeclass)

  <float name='speaker.playSpeed'>1.5</float>

Speaker is muted. Affects only volume not play state.

• Full name: speaker.muted or speaker({id}).muted
• Type: boolean
• Default Value: false
• Example (*.deeclass)

  <boolean name='speaker.muted'>true</boolean>

Speaker plays back looping. If fase playback stops after end of sound or synthesizer.

• Full name: speaker.looping or speaker({id}).looping
• Type: boolean
• Default Value: true
• Example (*.deeclass)

  <boolean name='speaker.looping'>false</boolean>

Speaker is playing back after being created.

• Full name: speaker.playing or speaker({id}).playing
• Type: boolean
• Default Value: true
• Example (*.deeclass)

  <boolean name='speaker.playing'>false</boolean>

Shape of speaker.

• Full name: speaker.shape or speaker({id}).shape
• Type: string (shape format). See “Shape List Encoding” in CodecPropertyString.
• Default Value: empty string
• Example (*.deeclass)

  <string name='speaker.shape'>box:position,0,0.5,0:extends,2,1,0.5</string>

Position to attach resource to collider.

• Full name: speaker.position or speaker({id}).position
• Type: 3-component float vector
• Default Value: (0,0,0)
• Example (*.deeclass)

  <vector name='speaker.position' x='0' y='0' z='0.1'/>

Orientation to attach resource to collider in degrees.

• Full name: speaker.orientation or speaker({id}).orientation
• Type: 3-component float vector
• Default Value: (0,0,0)
• Example (*.deeclass)

  <vector name='speaker.orientation' x='30' y='0' z='0'/>

Bone to attach resource to. If empty string attach to collider.

• Full name: speaker.bone or speaker({id}).bone
• Type: string
• Default Value: empty string
• Example (*.deeclass)

  <string name='speaker.bone'>attach</string>

Playback trigger. If no trigger is set the state of playing property is used.

• Full name: speaker.trigger or speaker({id}).trigger
• Type: string
• Default Value: state of playing
• Example (*.deeclass)

  <string name='speaker.trigger'>@switchOnVent & @powerEnabled</string>

Muted trigger. If no trigger is set the state of muted property is used.

• Full name: speaker.trigger(muted) or speaker({id}).trigger(muted)
• Type: string
• Default Value: state of muted
• Example (*.deeclass)

  <string name='speaker.trigger(muted)'>@switchOnVent & @powerEnabled</string>

Speaker started playing back.

Speaker stopped playing. This can be either manual or trigger based stop of speaker or a non-looping speaker finished playing back the sound/synthesizer.

Speaker has been muted.

Speaker has been unmuted.

This behavior adds these behavior tree actions if behavior tree is present. If behavior has non-empty identifier replace speaker with speaker(id).

Set one or more speaker parameters.

This is an example of using this action:

<action name='speaker.set'>
  <parameter name='playing'>true</parameter>
</action>

Check one or more speaker parameters. Action succeeds if all parameter value matches their respective speaker parameter otherwise action fails. This action is typically used as first action in a sequence to run the sequence only if a speaker parameter matches (or not).

This is an example of using this action:

<sequence>
  <action name='speaker.check'>
    <parameter name='playing'>true</parameter>
    <parameter name='muted'>false</parameter>
  </action>
  <!-- actions here run only if speaker playing and not muted -->
</sequence>

This behavior adds these behavior tree conditions if behavior tree is present. If behavior has non-empty identifier replace speaker with speaker(id).

Check one or more speaker parameters. Conditions returns true if all parameter value match their respective speaker parameter. This condition is typically used to run an action or sequence of actions as long as speaker conditions are true.

This is an example of using this condition:

<action name='myAction' id='doing something'>
  <parameter name='speaker.playing'>true</parameter>
  <parameter name='speaker.muted'>false</parameter>
  <condition>speaker.check</condition>
</action>

Same as Behavior Tree Actions.

Same as Behavior Tree Conditions.

This behavior sends these state machine events. If behavior has non-empty identifier replace speaker with speaker(id).

Speaker started playing back.

Speaker stopped playing. This can be either manual or trigger based stop of speaker or a non-looping speaker finished playing back the sound/synthesizer.

Speaker has been muted.

Speaker has been unmuted.

This behavior requires no other behaviors.

• ECBehaviorCollider: Attach to collider.
• ECBehaviorBehaviorTree: Add actions and conditions for behavior trees to use.
• ECBehaviorStateMachine: Add actions and conditions for state machine to use and events to send to the state machine.

This behavior does support element class to be persistable (setPersistable).

ECBehaviorSpeaker.

Since DragonScript Module Version 1.0

• Add speaker playing back sound.

This example defines an element which can play back sound using a speaker.

class MyElement extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorCollider collider
  public var ECBehaviorSpeaker speaker
  func new()
    component = ECBehaviorComponent.new(this, null)
    collider = ECBehaviorCollider.new(this, component)
    speaker = ECBehaviorSpeaker.new(this, component, collider)
  end
end

Using element class supporting adding behaviors the behavior can be added like this:

<?xml version='1.0' encoding='UTF-8'?>
<elementClass name='MyClass' class='GenericBehaviorElement'>
  <behavior type='ECBehaviorComponent'/>
  <behavior type='ECBehaviorCollider'/>
 
  <behavior type='ECBehaviorSpeaker'>
    <!-- optional: set layer mask (default '2' meaning BaseGameApp.WorldLayerBit.audio).
                   list of bits to set. -->
    <string name='layerMask'>0 1 4</string>
 
    <!-- optional: use BaseGameApp trigger table. game can add more supported values -->
    <string name='triggerTable'>default</string>
 
    <!-- optional: identifier of ECBehaviorTriggered to synchronize with or empty
                   string to not synchronize. default is empty string. -->
    <string name='trigger.synchronize'>other</string>
 
    <!-- optional: identifier of ECBehaviorTriggered to synchronize with or empty
                   string to not synchronize. default is empty string. -->
    <string name='triggerMuted.synchronize'>other</string>
 
    <!-- optional: use behavior tree with id instead of empty string -->
    <string name='behaviorTree'>second</string>
 
    <!-- optional: use state machine with id instead of empty string -->
    <string name='stateMachine'>second</string>
 
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.sound'>ambience.ogg</string>
  </behavior>
 
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorSpeaker' id='second'/>
</elementClass>

• DEExamples Repository