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

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

====== ECBehaviorBTSMFlags ======

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

Adds actions, conditions and events allowing behavior trees and state machines to set, clear and check named flags. Flags are stored per element instance. Flags that are not set are considered cleared. Flags 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.

===== flags.update =====

Update flags. Action always succeeds.

^Parameter^Value^Description^
|set|string|Set named flag.|
|clear|string|Clear named flag.|

This is an example of setting a flag:
<code xml>
<action name='flags.update'>
  <parameter name='set'>arrived at target</parameter>
</action>
</code>

This is an example of setting and clearing a flag in the same action:
<code xml>
<action name='flags.update'>
  <parameter name='set'>arrived at target</parameter>
  <parameter name='clear'>stay seated</parameter>
</action>
</code>

===== flags.check =====

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

^Parameter^Value^Description^
|flag|string|Flag to check.|
|set|''true'', ''false''|Flag is set or not.|
|wait| |If present action returns BTResult.running instead of BTResult.failed to wait until the checks are all fulfilled.|
|reset| |If present toggle the flag after the checks succeeded.|

This is an example of checking if a flag is set right now:
<code xml>
<action name='flags.check'>
  <parameter name='flag'>arrived at target</parameter>
  <parameter name='set'>true</parameter>
</action>
</code>

This is an example of waiting until a flag is set:
<code xml>
<action name='flags.check' id='waiting'>
  <parameter name='flag'>arrived at target</parameter>
  <parameter name='set'>true</parameter>
  <parameter name='wait'/>
</action>
</code>

This is an example of waiting until a flag is set and then clearing it:
<code xml>
<action name='flags.check' id='waiting'>
  <parameter name='flag'>arrived at target</parameter>
  <parameter name='set'>true</parameter>
  <parameter name='wait'/>
  <parameter name='reset'/>
</action>
</code>

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

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

===== flags.check =====

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

^Parameter^Value^Description^
|flags.flag|string|Flag to check.|
|flags.set|''true'', ''false''|Flag is set or not.|

This is an example of using this condition:
<code xml>
<action name='myAction' id='doing something'>
  <condition>flags.check</condition>
  <parameter name='flags.flag'>arrived at target</parameter>
  <parameter name='flags.set'>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.

===== flags.set:<name> =====

Flag named ''name'' changed from cleared to set. The name of the flag is appended to the event name.

This is an example of a transition that runs if the flag "arrived at target" has been set:
<code xml>
<transition event='flags.set:arrived at target' state='nextState'>
</transition>
</code>

===== flags.cleared:<name> =====

Flag named ''name'' changed from set to cleared. The name of the flag is appended to the event name.

This is an example of a transition that runs if the flag "arrived at target" has been cleared:
<code xml>
<transition event='flags.cleared:arrived at target' 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). Set flags are persisted.

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorBTSMFlags.html,ECBehaviorBTSMFlags~@#.

Since DragonScript Module Version ''1.35''

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

  * Remember that an event has happened, for example that a character arrived at a target.
  * Share a yes/no state between behavior trees and state machines of the same element.
  * Wait until another part of the element sets a flag before continuing.

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

This example defines an element which contains flags.

<code>
class MyElement extends BehaviorElementClass
  public var ECBehaviorBTSMFlags flags
  func new()
    flags = ECBehaviorBTSMFlags.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='ECBehaviorBTSMFlags'>
    <!-- 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]]