{{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]] >> **ECBehaviorAnimated**
</WRAP>

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

====== ECBehaviorAnimated ======

Behavior element behavior adding animation support.

Playing back an animation using an animator for an ECBehaviorComponent. By default the [[behavior_component|ECBehaviorComponent]] with empty identifier is animated.

To use this behavior make sure to add first the [[behavior_component|ECBehaviorComponent]] to animate.

See also:
  * [[gamedev:animators|Animator and Animations]]
  * [[gamedev:deigde:editors:animator|IGDE Animator Editor]]
  * [[tools:blenderexportscripts|Blender3D Export Scripts]]

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

Multiple ECBehaviorAnimated can be added targeting different [[behavior_component|ECBehaviorComponent]] using their identifier. It is also possible to add multiple ECBehaviorAnimated manipulating the same [[behavior_component|ECBehaviorComponent]] as long as the animators used are properly crafted. This can be used for example to add overlayed animations like gestures onto an actor.

====== Element Class Properties ======
Element class properties have the prefix ''animated.'' or ''animated({id}).'' if id is not empty.

===== path =====
Set path to animator to use.
  * Full name: ''animated.path'' or ''animated({id}).path''
  * Type: string
  * Default Value: empty string
  * Expected File Pattern: ''*.deanimator''
  * Example (*.deeclass) <code xml><string name='animated.path'>default.deanimator</string></code>

===== animation =====
Set path to animation to use. If used replaces animation defined in assigned animators.
  * Full name: ''animated.animation'' or ''animated({id}).animation''
  * Type: string
  * Default Value: empty string
  * Expected File Pattern: ''*.deanim'' (all supported animation type modules)
  * Example (*.deeclass) <code xml><string name='animated.animation'>default.deanim</string></code>

===== playSpeed =====
Set playback speed. Value of ''1'' plays back at normal speed. Values larger than 1 play back faster. Values less then 1 play back slower.
  * Full name: ''animated.playSpeed'' or ''animated({id}).playSpeed''
  * Type: float
  * Default Value: 1
  * Example (*.deeclass) <code xml><float name='animated.playSpeed'>0.5</float></code>

===== playing =====
Set if animator is playing back after creating element.
  * Full name: ''animated.playing'' or ''animated({id}).playing''
  * Type: boolean
  * Default Value: true
  * Example (*.deeclass) <code xml><boolean name='animated.playing'>false</boolean></code>

===== playbackController =====
Set name of controller used to play back the animation. Controller value is incremended by elapsed time multiplied by ''playSpeed''.
  * Full name: ''animated.playbackController'' or ''animated({id}).playbackController''
  * Type: string
  * Default Value: ''playback''
  * Example (*.deeclass) <code xml><string name='animated.playbackController'>animation</string></code>

===== move =====
Set move name. If animator is not set this creates a temporary animator with a single //animation// type rule playing back ''move''. This can be used to play animation moves without needing to create an animator.
  * Full name: ''animated.move'' or ''animated({id}).move''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='animated.move'>idle</string></code>

===== loopMove =====
Set loop animation move. Used only if animator is not set and animation and move is set.
  * Full name: ''animated.loopMove'' or ''animated({id}).loopMove''
  * Type: boolean
  * Default Value: ''true''
  * Example (*.deeclass) <code xml><boolean name='animated.loopMove'>false</boolean></code>

===== trigger =====
Set trigger playing back. If no trigger is set the state of ''playing'' property is used.
  * Full name: ''animated.trigger'' or ''animated({id}).trigger''
  * Type: string
  * Default Value: state of ''playing''
  * Example (*.deeclass) <code xml><string name='animated.trigger'>@machineOn & @powerEnabled</string></code>

===== targetPlaying =====
Set playing target. If playing starts target is fired. If playing stops target is reset.
  * Full name: ''animated.targetPlaying'' or ''animated({id}).targetPlaying''
  * Type: string
  * Default Value: empty string
  * Example (*.deeclass) <code xml><string name='animated.targetPlaying'>animationPlaying</string></code>

===== applyPostThink =====
Set apply animator during postThink() instead of think().
  * Full name: ''animated.applyPostThink'' or ''animated({id}).applyPostThink''
  * Type: boolean
  * Default Value: ''false''
  * Example (*.deeclass) <code xml><boolean name='animated.applyPostThink'>true</boolean></code>

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

Behavior elements and other behaviors can add listeners to the ECBehaviorAnimated. Listeners are notified if the animation starts playing and when it stops playing. This can be used to synchronize actions to these events. ECBehaviorAnimated can also use trigger targets so listeners are not always required.

Another use for listeners is update animator controllers not handled by ECBehaviorAnimated itself. ECBehaviorAnimated calls AnimatorInstance.apply() before it exits thinking. If other behaviors modify the animator controller later on they need to call AnimatorInstance.apply() again. If multiple behaviors affect the same animated component this can put strain on the game engine modules and reduce performance. For this reason listeners are also asked to update animator controllers. This allows multiple behaviors to update individual controllers with AnimatorInstance.apply() to be called only once.

It is important to note that using listeners behaviors are asked to update animator controllers before their think() method is called. For such behaviors it is best to do their thinking inside the listener call avoiding think() to be used at all.

A typical usage pattern for such behaviors is to locate the animator controller to update during construction time and to manipulated the controllers inside updateControllers().

See [[#element_class_example|Element Class Example]] for example code.

This behavior has these events:

===== startPlaying =====

Start playing back.

===== stopPlaying =====

Stop playing.

===== updateControllers =====

Update controllers if required.

===== animationApplied =====

Animation has been applied.

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

  * [[behavior_component|ECBehaviorComponent]]

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

This behavior does not support optional behaviors.

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

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

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorAnimated.html,ECBehaviorAnimated~@#.

Since DragonScript Module Version ''1.0''

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

  * Allow actor to style his player actor using custom colors for individual body parts.
  * Create variations of NPCs by adding color slots that can be modified in XML Element Classes or using Stub Properties.

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

This example defines an element which supports being animated.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorComponent component
  public var ECBehaviorAnimated animated
  func new()
    component = ECBehaviorComponent.new(this, null)
    animated = ECBehaviorAnimated.new(this, component)
  end
end
</code>

Example of using listeners.

<code>
class MyListener extends ECBehaviorInstance.DefaultListener
  var AnimatorController pController
  
  func new(ECBehaviorAnimated behavior)
    pController = behavior.getAnimatorInstance().getControllerNamed("special controller")
  end
  
  func void updateControllers(Instance instance, float elapsed)
    pController.increment(elapsed)
  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='ECBehaviorAnimated'>
    <!-- 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>
    
    <!-- optional: use named controller instead of first controller. default is empty string -->
    <string name='controllerName'>playback</string>
    
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.path'>default.deanimator</string>
  </behavior>
  
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorAnimated' id='second'/>
</elementClass>
</code>

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

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