Drag[en]gine Wiki

User Tools

Site Tools

Trace:
dragengine:modules:dragonscript:behaviortrees

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
dragengine:modules:dragonscript:behaviortrees [2025/05/16 13:37] – dragonlorddragengine:modules:dragonscript:behaviortrees [2025/06/12 17:01] (current) – [File Format (*.debt)] dragonlord
Line 6: Line 6:
 ====== Behavior Trees ====== ====== Behavior Trees ======
  
-Behavior trees are structured graphics describing the AI logic using a tree of rules. The behavior tree is at all times located at one of the rules in the tree. During each simulation step (typically during frame update) the behavior tree moves along the tree until an rule returns either ''BTResult.running'' . The behavior tree keeps on running the active rule each simulation step until the rule either returns ''BTResult.success'' or ''BTResult.failure''. The AI logic is formed by the logic behind each rule.+Behavior trees are structured graphs describing the AI logic using a tree of rules. The behavior tree is at all times located at one of the rules in the tree. During each simulation step (typically during frame update) the behavior tree moves along the tree until an rule returns either ''BTResult.running'' . The behavior tree keeps on running the active rule each simulation step until the rule either returns ''BTResult.success'' or ''BTResult.failure''. The AI logic is formed by the logic behind each rule.
  
 Each can also have one or more conditions assigned. Before each run of the rule the conditions are evaluated. If any of the conditions evaluates to false the rule fails. Only the conditions of the active rule are evaluated. The conditions of the parent rule are only evaluated if the active node returns anything else but ''BTResult.running''. In this case the behavior tree wants to move to the next action. To do this the parent rule is run which then automatically evaluates the parent rule conditions. Each can also have one or more conditions assigned. Before each run of the rule the conditions are evaluated. If any of the conditions evaluates to false the rule fails. Only the conditions of the active rule are evaluated. The conditions of the parent rule are only evaluated if the active node returns anything else but ''BTResult.running''. In this case the behavior tree wants to move to the next action. To do this the parent rule is run which then automatically evaluates the parent rule conditions.
Line 68: Line 68:
 The main use for this rule is to force waiting until a rule conditions fails. The main use for this rule is to force waiting until a rule conditions fails.
  
 +Since this rules returns ''BTResult.running'' it must have an ''id'' to make it persistable. A typical example is this:
 +<code xml>
 +<running id='.running'/>
 +</code>
 +
 +===== Yield =====
 +
 +Returns ''BTResult.running'' the first time the rule is run and ''BTResult.success'' otherwise.
 +
 +This rule causes the behavior tree to yield processing for one frame update to continue with the next rule the next time it is run. This rule prevents endless choice loops. Choice loops happen if all rules in a looping choice are not applying. The last rule has to be a rule returning ''BTResult.running'' to stop retesting all rules endlessly. After some time though this last rule has to return ''BTResult.success'' or the behavior tree is stuck forever in this rule. A typical solution is to use a short [[behavior_behaviortreetimer|ECBehaviorBehaviorTreeTimer]] to achieve this pause. This rule allows to yield processing for one frame in a simple way without needing to deal with timers.
 +
 +This rule can also be used to add single frame delays in a behavior tree, for example to ensure actors are not running actions too fast.
 +
 +Since this rules can return ''BTResult.running'' it must have an ''id'' to make it persistable. A typical example is this:
 +<code xml>
 +<yield id='.yield'/>
 +</code>
  
-====== File Format (*.debtree) ======+====== File Format (*.debt) ======
  
-The behavior tree file format is recognized by the LoadBehaviorTree script class. The file is an XML file with a simple structure to define a behavior tree using XML.+The behavior tree file format is recognized by the LoadBehaviorTree script class. The file is an XML file with a simple structure to define a behavior tree using XML. See [[https://lordofdragons.github.io/dragengine/artifacts/xmlschema/dragengine/latest/behaviorTree.xsd|XML Schema]] for use with editors like VSCode.
  
 <uml> <uml>
Line 83: Line 100:
   |failure||   |failure||
   |running||   |running||
 +  |yield||
   |subtree|  <color:gray>string|   |subtree|  <color:gray>string|
 } }
Line 103: Line 121:
   |failure||   |failure||
   |running||   |running||
 +  |yield||
   |subtree|  <color:gray>string|   |subtree|  <color:gray>string|
 } }
Line 117: Line 136:
   |failure||   |failure||
   |running||   |running||
 +  |yield||
   |subtree|  <color:gray>string|   |subtree|  <color:gray>string|
 } }
Line 141: Line 161:
 } }
 behaviorTree --> running behaviorTree --> running
 +
 +object "yield" as yield {
 +  <#transparent,#transparent>|parameter|  <color:gray>string|
 +  |condition|  <color:gray>string|
 +  |conditionMode|  <color:gray>enum|
 +}
 +behaviorTree --> yield
 +
 +object "subtree" as subtree {
 +  <#transparent,#transparent>|parameter|  <color:gray>string|
 +  |condition|  <color:gray>string|
 +  |conditionMode|  <color:gray>enum|
 +}
 +behaviorTree --> subtree
  
 @enduml @enduml
Line 156: Line 190:
 |failure|Add failure rule|0..N|-| |failure|Add failure rule|0..N|-|
 |running|Add running rule|0..N|-| |running|Add running rule|0..N|-|
 +|yield|Add yield rule|0..N|-|
 |subtree|Load behavior tree using path from tag text content. Subtree is added to the behavior tree as a sequence rule containing the loaded behavior tree|0..N|-| |subtree|Load behavior tree using path from tag text content. Subtree is added to the behavior tree as a sequence rule containing the loaded behavior tree|0..N|-|
  
Line 164: Line 199:
 ^Attribute^Description^Occurance^Default^ ^Attribute^Description^Occurance^Default^
 |name|Name of action to run.|Required|-| |name|Name of action to run.|Required|-|
 +|id|Rule identifier. Required for actions potentially returning ''BTResult.running'' to support persistance. If identifier starts with ''.'' the parent rule identifier is prepended.|Optional|-|
 |doNotFail|If action fails return ''BTResult.success''. Useful to running optional actions without failing the parent rule.|Optional|''false''| |doNotFail|If action fails return ''BTResult.success''. Useful to running optional actions without failing the parent rule.|Optional|''false''|
  
Line 184: Line 220:
 ^Attribute^Description^Occurance^Default^ ^Attribute^Description^Occurance^Default^
 |loop|Loop sequence.|Optional|''false''| |loop|Loop sequence.|Optional|''false''|
 +|id|Rule identifier. Used to support persistance. If identifier starts with ''.'' the parent rule identifier is prepended.|Optional|-|
 |doNotFail|If sequence fails return ''BTResult.success''. Useful to optional sequences running as many rules in a sequence as possible without failing the parent rule.|Optional|''false''| |doNotFail|If sequence fails return ''BTResult.success''. Useful to optional sequences running as many rules in a sequence as possible without failing the parent rule.|Optional|''false''|
  
Line 203: Line 240:
 |failure|Add failure rule|0..N|-| |failure|Add failure rule|0..N|-|
 |running|Add running rule|0..N|-| |running|Add running rule|0..N|-|
 +|yield|Add yield rule|0..N|-|
 |subtree|Load behavior tree using path from tag text content. Subtree is added to the behavior tree as a sequence rule containing the loaded behavior tree|0..N|-| |subtree|Load behavior tree using path from tag text content. Subtree is added to the behavior tree as a sequence rule containing the loaded behavior tree|0..N|-|
  
Line 211: Line 249:
 ^Attribute^Description^Occurance^Default^ ^Attribute^Description^Occurance^Default^
 |loop|Loop choice.|Optional|''false''| |loop|Loop choice.|Optional|''false''|
 +|id|Rule identifier. Used to support persistance. If identifier starts with ''.'' the parent rule identifier is prepended.|Optional|-|
 |doNotFail|If choice fails return ''BTResult.success''. Useful for optional choices there failing the choice should not fail the parent rule.|Optional|''false''| |doNotFail|If choice fails return ''BTResult.success''. Useful for optional choices there failing the choice should not fail the parent rule.|Optional|''false''|
  
Line 230: Line 269:
 |failure|Add failure rule|0..N|-| |failure|Add failure rule|0..N|-|
 |running|Add running rule|0..N|-| |running|Add running rule|0..N|-|
 +|yield|Add yield rule|0..N|-|
 |subtree|Load behavior tree using path from tag text content. Subtree is added to the behavior tree as a sequence rule containing the loaded behavior tree|0..N|-| |subtree|Load behavior tree using path from tag text content. Subtree is added to the behavior tree as a sequence rule containing the loaded behavior tree|0..N|-|
  
Line 267: Line 307:
  
 Adds a running rule. Adds a running rule.
 +
 +^Attribute^Description^Occurance^Default^
 +|id|Rule identifier. Required to support persistance. If identifier starts with ''.'' the parent rule identifier is prepended.|Optional|-|
 +
 +^Tag^Description^Occurance^Default^
 +|parameter|<WRAP>Add parameter. Parameter value is text content of node which can be empty. Attributes:
 +  * ''name'': Name of parameter. Required.
 +</WRAP>|0..N|-|
 +|condition|Add condition. Condition name is text content of node|0..N|-|
 +|conditionMode|<WRAP>How conditions are evaluated. Valid values:
 +  * ''allTrue'': All conditions have to evaluate to true.
 +  * ''anyTrue'': At least one condition has to evaluate to true.
 +  * ''anyFalse'': At least one condition has to evaluate to false.
 +  * ''allFalse'': All conditions have to evaluate to false.
 +</WRAP>|0..1|''allTrue''|
 +
 +===== yield =====
 +
 +Adds a yield rule.
 +
 +^Attribute^Description^Occurance^Default^
 +|id|Rule identifier. Required to support persistance. If identifier starts with ''.'' the parent rule identifier is prepended.|Optional|-|
  
 ^Tag^Description^Occurance^Default^ ^Tag^Description^Occurance^Default^
dragengine/modules/dragonscript/behaviortrees.1747402638.txt.gz · Last modified: 2025/05/16 13:37 by dragonlord

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
CC Attribution-Noncommercial-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki