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 requires no other behaviors.

• ECBehaviorCollider: Attach to collider.

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>
 
    <!-- 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