{{tag>dragonscript behavior}} [[: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]] >> **ECBehaviorSpeaker** * [[behaviors_use_cases|Behaviors Explained: By Use-Case]] * [[behaviors_a_to_z|Behaviors Explained: From A to Z]] ====== ECBehaviorSpeaker ====== Behavior element behavior adding speaker support. Behavior adds a Speaker resource to the the behavior element. If the [[behavior_collider|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. ===== Synthesizer Handling ===== 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: * [[[gamedev:synthesizers|Synthesizers]] * [[gamedev:deigde:editors:synthesizer|IGDE Synthesizer Editor]] ====== Instance Counts ====== 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 ====== Element class properties have the prefix ''speaker.'' or ''speaker({id}).'' if id is not empty. ===== type ===== 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) directed ===== sound ===== 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) click.ogg ===== synthesizer ===== 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) sound.desynth ===== volume ===== Speaker volume. * Full name: ''speaker.volume'' or ''speaker({id}).volume'' * Type: float * Default Value: ''1'' * Restriction: At least ''0'' * Example (*.deeclass) 0.8 ===== range ===== 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) 20 ===== 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: ''speaker.rollOff'' or ''speaker({id}).rollOff'' * Type: float * Default Value: ''1'' * Restriction: At least ''0'' * Example (*.deeclass) 1.5 ===== 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: ''speaker.distanceOffset'' or ''speaker({id}).distanceOffset'' * Type: float * Default Value: ''0'' * Restriction: At least ''0'' * Example (*.deeclass) 500 ===== 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: ''speaker.playSpeed'' or ''speaker({id}).playSpeed'' * Type: float * Default Value: ''1'' * Example (*.deeclass) 1.5 ===== muted ===== Speaker is muted. Affects only volume not play state. * Full name: ''speaker.muted'' or ''speaker({id}).muted'' * Type: boolean * Default Value: ''false'' * Example (*.deeclass) true ===== looping ===== 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) false ===== playing ===== Speaker is playing back after being created. * Full name: ''speaker.playing'' or ''speaker({id}).playing'' * Type: boolean * Default Value: ''true'' * Example (*.deeclass) false ===== shape ===== 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) box:position,0,0.5,0:extends,2,1,0.5 ===== position ===== 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) ===== orientation ===== 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) ===== bone ===== 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) attach ===== trigger ===== 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) @switchOnVent & @powerEnabled ===== trigger(muted) ===== 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) @switchOnVent & @powerEnabled ====== Events ====== ===== startPlaying ===== Speaker started playing back. ===== stopPlaying ===== 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. ===== muted ===== Speaker has been muted. ===== unmuted ===== Speaker has been unmuted. ====== Behavior Tree Actions ====== This behavior adds these behavior tree actions if behavior tree is present. If behavior has non-empty identifier replace ''speaker'' with ''speaker(id)''. ===== speaker.set ===== Set one or more speaker parameters. ^Parameter^Value^Description^ |playing|''true'', ''false''|Speaker is playing back| |muted|''true'', ''false''|Speaker is muted| This is an example of using this action: true ===== speaker.check ===== 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). ^Parameter^Value^Description^ |playing|''true'', ''false''|Speaker is playing| |muted|''true'', ''false''|Speaker is muted| |wait| |If present action returns BTResult.running instead of BTResult.failed to wait until the checks are all fulfilled| This is an example of using this action: true false ====== Behavior Tree Conditions ====== This behavior adds these behavior tree conditions if behavior tree is present. If behavior has non-empty identifier replace ''speaker'' with ''speaker(id)''. ===== speaker.check ===== 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. ^Parameter^Value^Description^ |speaker.playing|''true'', ''false''|Speaker is playing| |speaker.muted|''true'', ''false''|Speaker is muted| This is an example of using this condition: true false speaker.check ====== State Machine Actions ====== Same as [[#behavior_tree_actions|Behavior Tree Actions]]. ====== State Machine Conditions ====== Same as [[#behavior_tree_conditions|Behavior Tree Conditions]]. ====== State Machine Events ====== This behavior sends these state machine events. If behavior has non-empty identifier replace ''speaker'' with ''speaker(id)''. ===== speaker.start ===== Speaker started playing back. ===== speaker.stop ===== 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.muted ===== Speaker has been muted. ===== speaker.unmuted ===== Speaker has been unmuted. ====== Required Behaviors ====== This behavior requires no other behaviors. ====== Optional Behaviors ====== * [[behavior_collider|ECBehaviorCollider]]: Attach to collider. * [[behavior_behaviortree|ECBehaviorBehaviorTree]]: Add actions and conditions for behavior trees to use. * [[behavior_statemachine|ECBehaviorStateMachine]]: Add actions and conditions for state machine to use and events to send to the state machine. ====== Persistency ====== This behavior does support element class to be persistable (setPersistable). ====== API Documentation ====== #@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorSpeaker.html,ECBehaviorSpeaker~@#. Since DragonScript Module Version ''1.0'' ====== Use Cases ====== * Add speaker playing back sound. ====== Element Class Example ====== 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 ====== Behavior Factory ====== Using element class supporting adding behaviors the behavior can be added like this: 0 1 4 default other other second second ambience.ogg ====== Live Examples ====== * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]