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

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

====== ECBehaviorBTSMTimers ======

Behavior element behavior adding timer support to behavior trees and state machines.

Adds actions, conditions and events allowing behavior trees and state machines to start, stop and wait for multiple independent named timers. Timers count down during think updates. A timer has elapsed once its remaining time reaches 0. Timers are persisted together with the element.

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

This behavior can be added only once to an element class.

====== Element Class Properties ======

This behavior has no element class properties.

====== Behavior Tree Actions ======

This behavior adds these behavior tree actions if behavior tree is present.

===== timers.update =====

Start or stop named timers. Action always succeeds.

^Parameter^Value^Description^
|start|string|Start named timer. The timer is added if absent. If the timer is already present it is restarted with the new timeout.|
|timeout|0 or larger|Seconds until the timer elapses. Used with ''start''.|
|timeout.lower|0 or larger|Minimum seconds of random timeout. Used with ''start'' together with ''timeout.upper'' instead of ''timeout''.|
|timeout.upper|0 or larger|Maximum seconds of random timeout. Used with ''start'' together with ''timeout.lower'' instead of ''timeout''.|
|stop|string|Stop named timer.|

This is an example of starting a timer:
<code xml>
<action name='timers.update'>
  <parameter name='start'>myTimer</parameter>
  <parameter name='timeout'>1.5</parameter>
</action>
</code>

This is an example of starting a timer using random timeout:
<code xml>
<action name='timers.update'>
  <parameter name='start'>myTimer</parameter>
  <parameter name='timeout.lower'>1.5</parameter>
  <parameter name='timeout.upper'>2.5</parameter>
</action>
</code>

This is an example of stopping a timer:
<code xml>
<action name='timers.update'>
  <parameter name='stop'>myTimer</parameter>
</action>
</code>

===== timers.check =====

Check one or more timer parameters. Not existing timers are considered stopped. Action succeeds if all parameter values match their respective timer state otherwise action fails. This action is typically used as first action in a sequence to run the sequence only if a timer condition matches (or not).

^Parameter^Value^Description^
|timer|string|Name of the timer to check.|
|running|''true'', ''false''|Timer is running or not.|
|remaining.less|0 or larger|Remaining seconds is less than value.|
|remaining.greater|0 or larger|Remaining seconds is greater than value.|
|wait| |If present action returns BTResult.running instead of BTResult.failed to wait until the checks are all fulfilled.|

This is an example of checking if a timer is running:
<code xml>
<action name='timers.check' id='waiting'>
  <parameter name='timer'>myTimer</parameter>
  <parameter name='running'>true</parameter>
</action>
</code>

This is an example of waiting until a timer has elapsed:
<code xml>
<action name='timers.check' id='waiting'>
  <parameter name='timer'>myTimer</parameter>
  <parameter name='running'>false</parameter>
  <parameter name='wait'/>
</action>
</code>

====== Behavior Tree Conditions ======

This behavior adds these behavior tree conditions if behavior tree is present.

===== timers.check =====

Check one or more timer parameters. Condition returns true if all parameter values match their respective timer state. This condition is typically used to run an action or sequence of actions as long as timer conditions are true.

^Parameter^Value^Description^
|timers.timer|string|Name of the timer to check.|
|timers.running|''true'', ''false''|Timer is running or not.|
|timers.remaining.less|0 or larger|Remaining seconds is less than value.|
|timers.remaining.greater|0 or larger|Remaining seconds is greater than value.|

This is an example of using this condition:
<code xml>
<action name='myAction' id='doing something'>
  <condition>timers.check</condition>
  <parameter name='timers.timer'>myTimer</parameter>
  <parameter name='timers.running'>true</parameter>
</action>
</code>

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

===== timers.elapsed:<name> =====

Timer named ''name'' has elapsed. The event is sent once after the timer reached 0 remaining time. The name of the timer is appended to the event name.

This is an example of a transition that runs if the timer "myTimer" has elapsed:
<code xml>
<transition event='timers.elapsed:myTimer' state='nextState'>
</transition>
</code>

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

This behavior requires no other behaviors.

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

  * [[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). Running timers are persisted.

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorBTSMTimers.html,ECBehaviorBTSMTimers~@#.

Since DragonScript Module Version ''1.35''

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

  * Delay an action, for example close a door a few seconds after it has been opened.
  * Let a state machine switch state after a timeout, for example leave an idle state after some time.
  * Add random delays using ''timeout.lower'' and ''timeout.upper''.

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

This example defines an element which contains timers.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorBTSMTimers timers
  func new()
    timers = ECBehaviorBTSMTimers.new(this)
  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='ECBehaviorBTSMTimers'>
    <!-- optional: add behavior trees. default adds all behavior trees. -->
    <list name='behaviorTrees'>
      <string/> <!-- add behavior with empty identifier -->
      <string>default</string> <!-- add behavior with 'default' identifier -->
    </list>

    <!-- optional: add state machines. default adds all state machines. -->
    <list name='stateMachines'>
      <string/> <!-- add behavior with empty identifier -->
      <string>default</string> <!-- add behavior with 'default' identifier -->
    </list>
  </behavior>
</elementClass>
</code>

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

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