{{tag>dragonscript appbehavior}}
<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]] >> **GABehaviorTimers**
</WRAP>

====== GABehaviorTimers ======

Behavior adds actions, conditions and events allowing behavior trees and state machines to start, stop and wait for multiple independent timers.

To access this behavior from other application behaviors use ''GABehaviorTimers.getBehaviorInApp()''.

====== State Machine Actions ======

This behavior adds these state machine actions.

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

====== State Machine Conditions ======

This behavior adds these state machine conditions.

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

  * [[gabehavior_statemachine|GABehaviorStateMachine]]: Add actions and conditions for state machine to use.

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1GABehaviorTimers.html,GABehaviorTimers~@#.

Since DragonScript Module Version ''1.35''

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

  * Fade over black from one scene to another.
  * Create effects like flash-bang temporarily whiteout the screen.

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

  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]: Element class changing color using a state machine receiving trigger events.