Behavior element behavior play sound using one shot speaker.

Behavior is comparable to ECBehaviorSpeaker but does not add a permanent speaker to the element. Instead GWBehaviorOneShotSpeaker.addSpeaker() is used to play a short sound event. One shot speakers are constructed the same way as ECBehaviorSpeaker does. Once deployed the one shot speaker stays in place and vanishes once it finished playing. This is the preferred way to play short sound events like a door lock toggling or firing gun shots.

Typical parameters can be set quickly using ECBehaviorPlaySound.set() methods. This is an example of door element class playing a sound for opening and a sound for closing. Both sounds have a range of 30m and play at a volume of 0.8 and play at the center of the door. In XML element classes these sound parameters can be modified using playSound.open.* and laySound.close.*.

If a trigger table is set the trigger expression triggerPlay or {prefix}.triggerPlay can be used to play sound each time the trigger expression changes and evaluates to true. Using a trigger table is usually only useful if the element can be used by mappers.

This behavior can be added multiple times to an element. This allows to play different sound events. Each instance has an identifier which can be used to retrieve a specific instance to play a one shot speaker. The prefix of the speaker class properties is playSound. . If the identifier is not empty the speaker element class properties have the prefix {id}.playSound. . This can be overwritten if required.

Hence to use more than one speaker use code like this in your subclass constructor:

class MyElementClass extends BehaviorElementClass
  func new()
    ECBehaviorPlaySound.new(this, null, null)
    ECBehaviorPlaySound.new(this, null, null, "subPlaySound")
  end
end

You can now define the parameters to use for both speakers using for example the properties volume for the first speaker and subPlaySound.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 playSound. or playSound({id}). if id is not empty.

Speaker type.

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

• Allowed Values:

  Value	Description
  point	Omnidirectional.
  directed	Directed.

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

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

Path of sound resource to use.

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

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

Speaker volume.

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

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

Speaker range in meters. Speaker is inaudible beyond range.

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

  <float name='playSound.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: playSound.rollOff or playSound({id}).rollOff
• Type: float
• Default Value: 1
• Restriction: At least 0
• Example (*.deeclass)

  <float name='playSound.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: playSound.distanceOffset or playSound({id}).distanceOffset
• Type: float
• Default Value: 0
• Restriction: At least 0
• Example (*.deeclass)

  <float name='playSound.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: playSound.playSpeed or playSound({id}).playSpeed
• Type: float
• Default Value: 1
• Example (*.deeclass)

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

Position to attach resource to collider.

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

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

Orientation to attach resource to collider in degrees.

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

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

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

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

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

Play sound when trigger evaluates to true and pauses when trigger evaluates to false.

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

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

This behavior has no events.

This behavior requires no other behaviors.

• ECBehaviorComponent: Attach to component bone.
• ECBehaviorCollider: Attach to collider.

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

ECBehaviorPlaySound.

Since DragonScript Module Version 1.0

• Play sound.

This example defines an element which can play sound.

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

Example of a door element playing sounds on open/close.

class DoorClass extends BehaviorElementClass
  public ECBehaviorPlaySound playSoundOpen
  public ECBehaviorPlaySound playSoundClose
  
  func new()
    // create and add play sound behavior for open door sound
    playSoundOpen = ECBehaviorPlaySound.new(this, null, null, "open")
    playSoundOpen.set("/content/door/open.ogg", 30.0, 0.8, Vector.new(0, 1, 0))
    
    // create and add play sound behavior for close door sound
    playSoundClose = ECBehaviorPlaySound.new(this, null, null, "close")
    playSoundClose.set("/content/door/close.ogg", 30.0, 0.8, Vector.new(0, 1, 0))
  end
end

class Door extends BehaviorElement
  public ECBehaviorPlaySound.Instance playSoundOpen
  public ECBehaviorPlaySound.Instance playSoundClose
  
  func new(DoorClass eclass) super(eclass)
    // find and store the behavior instances. it is not necessary to store them away
    // but doing so is faster especially if playing sound many times and quickly
    playSoundOpen = ECBehaviorPlaySound.getInstanceIn(this, null, null, "open")
    playSoundClose = ECBehaviorPlaySound.getInstanceIn(this, null, null, "close")
  end
  
  func void openDoor()
    // do what is needed to open the door
    playSoundOpen.play()
  end
  
  func void closeDoor()
    // do what is needed to close the door
    playSoundClose.play()
  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='ECBehaviorPlaySound'>
    <!-- optional: set layer mask (default '2' meaning BaseGameApp.WorldLayerBit.audio).
                   list of bits to set. -->
    <string name='layerMask'>0 1 4</string>
 
    <!-- optional: use component with id instead of empty string -->
    <string name='component'>second</string>
 
    <!-- optional: use BaseGameApp trigger table. game can add more supported values.
                   default is 'default' -->
    <string name='triggerTable'>default</string>
 
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.sound'>click.ogg</string>
  </behavior>
 
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorPlaySound' id='second'/>
</elementClass>

• DEExamples Repository