{{tag>dragonscript behavior}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:abstractions|Abstraction Layers: How you want to build your Game]] >> [[dragengine:modules:dragonscript:behavior_elements|Behavior Elements]] >> **ECBehaviorPlaySoundRandom**
</WRAP>

  * [[behaviors_use_cases|Behaviors Explained: By Use-Case]]
  * [[behaviors_a_to_z|Behaviors Explained: From A to Z]]

====== ECBehaviorPlaySoundRandom ======

Extends [[behavior_playsound|ECBehaviorPlaySound]] to pick sound to play randomly from a list of sounds.

Useful for situations where random sounds from a list of sounds have to be played each time the behavior is triggered. If random sound list is empty behaves the same as [[behavior_playsound|ECBehaviorPlaySound]].

<WRAP center round important 60%>
ECBehaviorPlaySoundRandom uses the same element property prefix (''playSound'') as ECBehaviorPlaySound does. This allows using ECBehaviorPlaySoundRandom as replacement for ECBehaviorPlaySound if the need for random sounds arises. But this also means it is possible to use ECBehaviorPlaySoundRandom and ECBehaviorPlaySound with the same identifier. While technically possible this would cause property name clash and an exception is thrown due to duplicate properties added. Make sure to always use a unique identifier for both ECBehaviorPlaySoundRandom and ECBehaviorPlaySound as if they were the same class.
</WRAP>

====== Instance Counts ======

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:

<code>
class MyElementClass extends BehaviorElementClass
  func new()
    ECBehaviorPlaySoundRandom.new(this, null, null)
    ECBehaviorPlaySoundRandom.new(this, null, null, "subPlaySound")
  end
end
</code>

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

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

===== type =====

Speaker type.

  * Full name: ''playSound.type'' or ''playSound({id}).type''
  * Type: enumeration
  * <WRAP>Allowed Values:
^Value^Description^
|''point''|Omnidirectional.|
|''directed''|Directed.|
</WRAP>
  * Default Value: ''point''
  * Example (*.deeclass) <code xml><string name='playSound.type'>directed</string></code>

===== sound =====

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) <code xml><string name='playSound.sound'>click.ogg</string></code>

===== sounds =====

List of path of sound resource to randomly choose from.

  * Full name: ''playSound.sounds'' or ''playSound({id}).sounds''
  * Type: string
  * Default Value: empty string
  * Expected File Type: ''*.ogg'' (all sound modules)
  * Example (*.deeclass) <code xml><list name='playSound.sounds'>
  <string>click1.ogg</string>
  <string>click2.ogg</string>
</list></code>

===== volume =====

Speaker volume.

  * Full name: ''playSound.volume'' or ''playSound({id}).volume''
  * Type: float
  * Default Value: ''1''
  * Restriction: At least ''0''
  * Example (*.deeclass) <code xml><float name='playSound.volume'>0.8</float></code>

===== range =====

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) <code xml><float name='playSound.range'>20</float></code>

===== rollOff =====

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) <code xml><float name='playSound.rollOff'>1.5</float></code>

===== distanceOffset =====

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) <code xml><float name='playSound.distanceOffset'>500</float></code>

===== playSpeed =====

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) <code xml><float name='playSound.playSpeed'>1.5</float></code>

===== position =====

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) <code xml><vector name='playSound.position' x='0' y='0' z='0.1'/></code>

===== orientation =====

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) <code xml><vector name='playSound.orientation' x='30' y='0' z='0'/></code>

===== bone =====

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) <code xml><string name='playSound.bone'>attach</string></code>

===== trigger =====

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) <code xml><string name='playSound.trigger'>@switchOnVent & @powerEnabled</string></code>

====== Events ======

This behavior has no events.

====== Required Behaviors ======

This behavior requires no other behaviors.

====== Optional Behaviors ======

  * [[behavior_component|ECBehaviorComponent]]: Attach to component bone.
  * [[behavior_collider|ECBehaviorCollider]]: Attach to collider.

====== Persistency ======

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

====== API Documentation ======

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorPlaySoundRandom.html,ECBehaviorPlaySoundRandom~@#.

Since DragonScript Module Version ''1.0''

====== Use Cases ======

  * Play sound.

====== Element Class Example ======

This example defines an element which can play sound.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorCollider collider
  public var ECBehaviorPlaySoundRandom playSound
  func new()
    component = ECBehaviorComponent.new(this, null)
    collider = ECBehaviorCollider.new(this, component)
    playSound = ECBehaviorPlaySoundRandom.new(this, component, collider)
  end
end
</code>

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

<code>
class DoorClass extends BehaviorElementClass
  public ECBehaviorPlaySoundRandom playSoundOpen
  public ECBehaviorPlaySoundRandom playSoundClose
  
  func new()
    // create and add play sound behavior for open door sound
    playSoundOpen = ECBehaviorPlaySoundRandom.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 = ECBehaviorPlaySoundRandom.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 ECBehaviorPlaySoundRandom.Instance playSoundOpen
  public ECBehaviorPlaySoundRandom.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 = ECBehaviorPlaySoundRandom.getInstanceIn(this, null, null, "open")
    playSoundClose = ECBehaviorPlaySoundRandom.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
</code>

====== Behavior Factory ======

Using element class supporting adding behaviors the behavior can be added like this:
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<elementClass name='MyClass' class='GenericBehaviorElement'>
  <behavior type='ECBehaviorComponent'/>
  <behavior type='ECBehaviorCollider'/>
  
  <behavior type='ECBehaviorPlaySoundRandom'>
    <!-- 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 -->
    <list name='.sound'>
      <string>click1.ogg</string>
      <string>click2.ogg</string>
    </list>
  </behavior>
  
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorPlaySoundRandom' id='second'/>
</elementClass>
</code>

====== Live Examples ======

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]