{{tag>dragonscript behavior}}
<WRAP youarehere>
[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[abstractions#behavior_elementsquick_and_easy_development|Behavior Elements: Quick and Easy Development]] >> **ECBehaviorBehaviorTree**
</WRAP>

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

====== ECBehaviorBehaviorTree ======

Behavior element behavior adding BehaviorTree support.

Loads a single behavior tree from file and creates a BTContext. Other behaviors can add actions and conditions to this behavior tree allowing to compose behavior tree actions and conditions easily.

This behavior can be used in different ways depending on the needs.

//Single Behavior Tree Usage//

This is the most simple solution where only one behavior tree is used. For many AI situations this is enough and is the most simple solution to use. Add one ECBehaviorBehaviorTree with no ID to the element and as many other behaviors adding actions and conditions as required. Set the ''behaviorTree.path'' property to define the behavior tree to load. If you want to use this behavior for simple elements you can set the ''behaviorTree.run'' to ''true''. In this case the behavior will run the behavior tree on ''think()'' calls. For BaseActor use it is better to keep this feature disabled and using a BaseActorAI supporting this behavior.
See [[#element_class_example|Element Class Example]] for example code.

//Multiple Behavior Tree Usage//

You can add multiple instances of ECBehaviorBehaviorTree to the element to load and use multiple behavior trees. This can be either because you want to switch between behavior trees or using multiple trees together to model complex AI logic. In this situation behaviors adding actions and conditions do add them to all instances of ECBehaviorBehaviorTree. This is usually not a problem since the behavior trees are written to use only the actions and conditions making sense to be used. You can set any ECBehaviorBehaviorTree to run during ''think()''. If enabling more than one behavior like this make sure the individual behavior trees properly work together.
See [[#element_class_example|Element Class Example]] for example code.

//BaseActor Usage//

This use case allows to use this behavior for BaseActor usage. BaseActor supports using BaseActorAI which can be exchanged to allow multiple different AI routines to be used without needing one large behavior tree. In this situation the behavior tree is not run by this behavior but by a BaseActorAI subclass. Both of the above scenarios are possible either using one behavior tree or multiple. Typically BaseActorAI does not use the BTContext from this behavior directly but instead create a copy. This has the advantage that each time a BaseActorAI is switched on it starts with a fresh context initialized with all actions and conditions added by other behaviors. Furthermore you can change the BehaviorTree to use during copy time opening up all kinds of possibilities to create actor AI easily.
See [[#element_class_example|Element Class Example]] for example code.

//Action and Condition Factory//

You can assign actions and conditions without using other behaviors by using one or more factories. The factories are added to the behavior. Upon creating the behavior instances the factories are asked to create and assign BTAction and BTCondition.
See [[#element_class_example|Element Class Example]] for example code.

====== Instance Counts ======
This behavior can be used multiple times on an element to add multiple behavior trees to mainpulate. Use the behavior identifier to tell them apart.

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

===== path =====
Set value.
  * Full name: ''behaviorTree.path'' or ''behaviorTree({id}).path''
  * Type: string
  * Default Value: empty string
  * Expected File Type: ''*.debt''
  * Example (*.deeclass) <code xml><string name='behaviorTree.path'>actor.debt</string></code>

===== run =====
Set run behavior tree during element thinking.
  * Full name: ''behaviorTree.run'' or ''behaviorTree({id}).run''
  * Type: boolean
  * Default Value: false
  * Example (*.deeclass) <code xml><boolean name='behaviorTree.run'>true</boolean></code>

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

This behavior has these events:

===== behaviorTreeUpdate =====
Send before stepping behavior tree.

===== behaviorTreeFailed =====
Stepping behavior tree Failed.

===== behaviorTreeRestarted =====
Behavior tree has been restarted.

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

This behavior requires no other behaviors.

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

This behavior does not support optional behaviors.

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

This behavior does require the element class to be persistable (setPersistable) only if the context is run by the behavior itself.

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

#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorBehaviorTree.html,ECBehaviorBehaviorTree~@#.

Since DragonScript Module Version ''1.0''

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

  * Use behavior tree to provide actor logic.

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

//Single Behavior Tree Usage//

This is an example code for such a setup:

<code>
class MyElementClass extends BehaviorElementClass
  func new()
    var ECBehaviorBehaviorTree btbehavior = ECBehaviorBehaviorTree.new(this)
    btbehavior.getPath().setValue("/content/myBehavior.debtree")
    btbehavior.getRun().setValue(true)
    
    // here you can add now behaviors adding actions and conditions for
    // the behavior tree to use
    ...
  end
end
</code>

//Multiple Behavior Tree Usage//

This is an example code for such a setup:
 
<code>
class MyElementClass extends BehaviorElementClass
  func new()
    var ECBehaviorBehaviorTree btSpecific = ECBehaviorBehaviorTree.new(this, "specific")
    btSpecific.getPath().setValue("/content/mySpecificBehavior.debtree")
    btSpecific.getRun().setValue(true)
    
    var ECBehaviorBehaviorTree btIdle = ECBehaviorBehaviorTree.new(this, "idle")
    btIdle.getPath().setValue("/content/myIdleBehavior.debtree")
    btIdle.getRun().setValue(true)
    
    // here you can add now behaviors adding actions and conditions for both
    // behavior trees to use
    ...
  end
end
</code>

//BaseActor Usage//

<code>
class MyElementClass extends BehaviorElementClass
  func new()
    var ECBehaviorBehaviorTree btree = ECBehaviorBehaviorTree.new(this)
    btSpecific.getPath().setValue("/content/basic.debtree")
    //btSpecific.getRun().setValue(false) // the default is false
    
    // here you can add now behaviors adding actions and conditions for both
    // behavior trees to use
    ...
  end
end

class MyActorAI extends BAAIBehaviorTree
  func new()
    // load behavior tree to use. this is not required but allows to use different
    // behavior trees for different AI routines. if not used the "/content/basic.debtree"
    // would be used as defined in MyElementClass.
    var BehaviorTree btree = BaseGameApp.getApp().getLoaders() \
      .getBehaviorTree().loadFromFile("/content/aiRoutine1.debtree")
    
    // create context. BAAIBehaviorTree requires a BTContextAI subclass hence we can
    // use the ECBehaviorBehaviorTree context directly. if you write your own BaseActorAI
    // subclasses this can be tough a viable option to use less script code. this copy
    // here will ensure all actions and conditions are present so this is easy and quick
    setContext(BTContextAI.new(this, ECBehaviorBehaviorTree.getInstanceIn(getActor()).getContext(), btree)
    
    // run behavior tree during think()
    setRunning(true)
  end
end
</code>

//Action and Condition Factory//

The example below shows how to use a factory to add a condition checking for a trigger and an action manipulating a trigger.

<code>
class MyElementClass extends BehaviorElementClass
  func new()
    var ECBehaviorBehaviorTree btbehavior = ECBehaviorBehaviorTree.new(this)
    btbehavior.getPath().setValue("/content/mySpecificBehavior.desm")
    
    // add factory to create actions and conditions later on. this example uses
    // a code block for simplicity. using classes implementing ActionConditionFactory
    // is preferred since it allows to reuse factories across element classes.
    btbehavior.setActionConditionFactory(block ECBehaviorBehaviorTree.Instance instance
      // add condition evaluating to true if "player.insideZone" trigger is in fired state.
      // the condition can be used in the behavior tree using the name "player is inside zone".
      instance.setCondition("player is inside zone", BTConditionTrigger.new(\
        "player.insideZone", BTConditionTrigger.TestMode.fired))
      
      // add action pulsing (fire and immediately reset) "player.damage" trigger.
      // the action can be run in the behavior tree using the name "hurt playe".
      instance.setAction("hurt player", BTActionTrigger.new("player.damage", BTActionTrigger.Action.pulse))
    end)
  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='ECBehaviorBehaviorTree'>
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.path'>actor.debp</string>
  </behavior>
  
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorBehaviorTree' id='second'/>
</elementClass>
</code>

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

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