Drag[en]gine Wiki

User Tools

Site Tools

Trace:
dragengine:modules:dragonscript:behavior_statemachine

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:behavior_statemachine [2025/03/11 18:52] – [Instance Counts] dragonlorddragengine:modules:dragonscript:behavior_statemachine [2025/05/09 19:04] (current) – dragonlord
Line 1: Line 1:
 {{tag>dragonscript behavior}} {{tag>dragonscript behavior}}
 <WRAP youarehere> <WRAP youarehere>
-[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[abstractions#behavior_elementsquick_and_easy_development|Behavior Elements: Quick and Easy Development]] >> **ECBehaviorStateMachine** +[[: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]] >> **ECBehaviorStateMachine**
-</WRAP> +
- +
-  * [[behaviors_use_cases|Behaviors Explained: By Use-Case]] +
-  * [[behaviors_a_to_z|Behaviors Explained: From A to Z]] +
- +
-====== ECBehaviorStateMachine ====== +
- +
-<WRAP center 100%> +
-<WRAP center box 450px> +
-{{youtube>F0xMEw-vtdw?medium}} +
-<WRAP centeralign>Example usage of State machine Behavior. See [[https://github.com/LordOfDragons/deexamples/blob/master/exampleApp/data/scripts/StateMachineExampleClass.ds|StateMachineExampleClass.ds]] and [[https://github.com/LordOfDragons/deexamples/blob/master/exampleApp/data/content/stateMachines/colorizer.desm|colorizer.desm]]</WRAP> +
-</WRAP> +
-</WRAP> +
- +
-Behavior element behavior adding #@LinkApiDocDEDS2_HTML~classDragengine_1_1StateMachineSystem_1_1StateMachine.html,StateMachine~@# support. +
- +
-Loads state machine from file (*.desm) and creates an #@LinkApiDocDEDS2_HTML~classDragengine_1_1StateMachineSystem_1_1SMContext.html,SMContext~@#. Other behaviors can add #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1StateMachineSystem_1_1SMAction.html,actions~@# and #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1StateMachineSystem_1_1SMCondition.html,conditions~@# to this state machine allowing to compose state machine actions and conditions easily. +
- +
-This behavior can be used in different ways depending on the needs. +
- +
-Single state machine is the most simple solution where only one state machine is used. For many situations this is enough and is the most simple solution to use. Add one **ECBehaviorStateMachine** with no ID to the element and as many other behaviors adding actions and conditions as required. Set the //stateMachine.path// property to define the state machine to load. Then use behavior listeners to run events on the state machine at the appropriate time. +
- +
-This is an example code for such a setup: +
-<code> +
-class MyElementClass extends BehaviorElementClass +
-   public func new() +
-      var ECBehaviorStateMachine smbehavior = ECBehaviorStateMachine.new(this) +
-      smbehavior.getPath().setValue("/content/myBehavior.desm") +
-       +
-      // here you can add now behaviors assigining actions and conditions for +
-      // the state machine to use +
-      ... +
-       +
-      // add listeners to behaviors to send events to the state machine +
-      var ECBehaviorTwoStateAnimated animated = ... +
-      animated.addActionConditionFactory(MyEventListener.Factory.new(smbehavior)) +
-   end +
-    +
-   // two state listeners used to send events +
-   class MyEventListener extends ECBehaviorTwoStateAnimated.DefaultListener +
-      class Factory implements ECBehaviorTwoStateAnimated.ActionConditionFactory +
-         public var ECBehaviorStateMachine stateMachine +
-          +
-         public func new(ECBehaviorStateMachine stateMachine) +
-            this.stateMachine = stateMachine +
-         end +
-          +
-         public func ECBehaviorTwoStateAnimated.Listener createListener(ECBehaviorTwoStateAnimated.Instance instance) +
-            return MyEventListener.new(stateMachine.instance(instance.getElement())) +
-         end +
-     end +
-      +
-     public var ECBehaviorStateMachine.Instance stateMachine +
-      +
-     public func new(ECBehaviorStateMachine.Instance stateMachine) +
-        this.stateMachine = stateMachine +
-     end +
-      +
-     public func void stopActivate(ECBehaviorTwoStateAnimated.Instance instance) +
-        stateMachine.runEvent("animated activated") +
-     end +
-      +
-     public func void stopDeactivate(ECBehaviorTwoStateAnimated.Instance instance) +
-        stateMachine.runEvent("animated deactivated") +
-     end +
-  end +
-end +
-</code> +
- +
-**Action and Condition Factory** +
- +
-You can assign #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1StateMachineSystem_1_1SMAction.html,actions~@# and #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1StateMachineSystem_1_1SMCondition.html,conditions~@# without using other behaviors by using one or more #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Scenery_1_1ECBehaviorStateMachine_1_1ActionConditionFactory.html,Action/Condition Factories~@#. The factories are added to the behavior. Upon creating the behavior instances the factories are asked to create and assign #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1StateMachineSystem_1_1SMAction.html,SMAction~@# and #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1StateMachineSystem_1_1SMCondition.html,SMCondition~@#. +
- +
-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 +
-   public func new() +
-      var ECBehaviorStateMachine smbehavior = ECBehaviorStateMachine.new(this) +
-      smbehavior.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. +
-      smbehavior.setActionConditionFactory( block ECBehaviorStateMachine.Instance instance +
-         // add condition evaluating to true if "player.insideZone" trigger is in fired state. +
-         // the condition can be used in the state machine using the name "player is inside zone". +
-         instance.setCondition("player is inside zone", SMConditionTrigger.new( \ +
-            "player.insideZone", SMConditionTrigger.TestMode.fired)) +
-          +
-         // add action pulsing (fire and immediately reset) "player.damage" trigger. +
-         // the action can be run in the state machine using the name "hurt playe". +
-         instance.setAction("hurt player", SMActionTrigger.new("player.damage", SMActionTrigger.Action.pulse)) +
-      end ) +
-   end +
-end +
-</code> +
- +
-{{tag>dragonscript behavior}} +
-<WRAP youarehere> +
-[[:start|Start Page]] >> [[main|DragonScript Scripting Language]] >> [[abstractions#behavior_elementsquick_and_easy_development|Behavior Elements: Quick and Easy Development]] >> **ECBehaviorStateMachine**+
 </WRAP> </WRAP>
  
Line 124: Line 24:
 This behavior can be used in different ways depending on the needs. This behavior can be used in different ways depending on the needs.
  
-_Single State Machine Usage_+//Single State Machine Usage//
  
 This is the most simple solution where only one state machine is used. For many situations this is enough and is the most simple solution to use. Add one ECBehaviorStateMachine with no ID to the element and as many other behaviors adding actions and conditions as required. Set the ''stateMachine.path'' property to define the state machine to load. Then use behavior listeners to run events on the state machine at the appropriate time. This is the most simple solution where only one state machine is used. For many situations this is enough and is the most simple solution to use. Add one ECBehaviorStateMachine with no ID to the element and as many other behaviors adding actions and conditions as required. Set the ''stateMachine.path'' property to define the state machine to load. Then use behavior listeners to run events on the state machine at the appropriate time.
Line 130: Line 30:
 See [[#element_class_example|Element Class Example]] for example code. See [[#element_class_example|Element Class Example]] for example code.
  
-_Multiple State Machine Usage_+//Multiple State Machine Usage//
  
 You can add multiple instances of ECBehaviorStateMachine to the element to load and use multiple state machines. This can be for using multiple state machines together to model complex logic. In this situation behaviors assigining actions and conditions do add them to all instances of ECBehaviorStateMachine. This is usually not a problem since the state machines are written to use only the actions and conditions making sense to be used. You can add multiple instances of ECBehaviorStateMachine to the element to load and use multiple state machines. This can be for using multiple state machines together to model complex logic. In this situation behaviors assigining actions and conditions do add them to all instances of ECBehaviorStateMachine. This is usually not a problem since the state machines are written to use only the actions and conditions making sense to be used.
Line 144: Line 44:
 ===== path ===== ===== path =====
 Set path to state machine file to load. Set path to state machine file to load.
-  * Full name: ''stateMachine.value'' or ''stateMachine({id}).value''+  * Full name: ''stateMachine.path'' or ''stateMachine({id}).path''
   * Type: string   * Type: string
   * Default Value: empty string   * Default Value: empty string
   * Expected File Type: ''*.desm''   * Expected File Type: ''*.desm''
-  * Example (*.deeclass) <code xml><string name='stateMachine.value'>actor.desm</string></code>+  * Example (*.deeclass) <code xml><string name='stateMachine.path'>actor.desm</string></code> 
 + 
 +===== debug ===== 
 +Debug mode prefix. If not empty string enables debug mode with prefix to locate log messages easily. 
 +  * Full name: ''stateMachine.debug'' or ''stateMachine({id}).debug'' 
 +  * Type: string 
 +  * Default Value: empty string 
 +  * Example (*.deeclass) <code xml><string name='stateMachine.debug'>Debug-Actor-SM</string></code>
  
 ===== Events ===== ===== Events =====
  
 This behavior has no events. This behavior has no events.
 +
 +====== Behavior Tree Actions ======
 +
 +This behavior adds these behavior tree actions if behavior tree is present. If behavior has non-empty identifier replace ''stateMachine'' with ''stateMachine(id)''.
 +
 +===== stateMachine.set =====
 +
 +Set one or more state machine parameters.
 +
 +^Parameter^Value^Description^
 +|reset| |Set state machine root state as current state|
 +|state|string|Set state machine state to state with identifier matching string value|
 +
 +This is an example of using this action:
 +<code xml>
 +<action name='stateMachine.set'>
 +  <parameter name='state'>open</parameter>
 +</action>
 +</code>
 +
 +===== stateMachine.event =====
 +
 +Run event on state machine.
 +
 +^Parameter^Value^Description^
 +|id|string|Identifier of event to run|
 +
 +This is an example of using this action:
 +<code xml>
 +<action name='stateMachine.event'>
 +  <parameter name='id'>open door</parameter>
 +</action>
 +</code>
 +
 +===== stateMachine.check =====
 +
 +Check one or more state machine parameters. Action succeeds if all parameter value matches their respective state machine parameter otherwise action fails. This action is typically used as first action in a sequence to run the sequence only if a state machine parameter matches (or not).
 +
 +^Parameter^Value^Description^
 +|state|string|Current state identifier matches string value|
 +|state.not|string|Current state identifier does not match string value|
 +|state.starts|string|Current state identifier starts with string value|
 +|state.starts.not|string|Current state identifier does not start with string value|
 +|state.ends|string|Current state identifier ends with string value|
 +|state.ends.not|string|Current state identifier does not end with string value|
 +|state.contains|string|Current state identifier contains string value|
 +|state.contains.not|string|Current state identifier does not contain string 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 using this action:
 +<code xml>
 +<sequence>
 +  <action name='stateMachine.check'>
 +    <parameter name='state'>open</parameter>
 +  </action>
 +  <!-- actions here run only if state machine is in the "open" state -->
 +</sequence>
 +</code>
 +
 +====== Behavior Tree Conditions ======
 +
 +This behavior adds these behavior tree conditions if behavior tree is present. If behavior has non-empty identifier replace ''stateMachine'' with ''stateMachine(id)''.
 +
 +===== stateMachine.check =====
 +
 +Check one or more state machine parameters. Conditions returns true if all parameter value match their respective state machine parameter. This condition is typically used to run an action or sequence of actions as long as state machine conditions are true.
 +
 +^Parameter^Value^Description^
 +|stateMachine.state|string|Current state identifier matches string value|
 +|stateMachine.state.not|string|Current state identifier does not match string value|
 +|stateMachine.state.starts|string|Current state identifier starts with string value|
 +|stateMachine.state.starts.not|string|Current state identifier does not start with string value|
 +|stateMachine.state.ends|string|Current state identifier ends with string value|
 +|stateMachine.state.ends.not|string|Current state identifier does not end with string value|
 +|stateMachine.state.contains|string|Current state identifier contains string value|
 +|stateMachine.state.contains.not|string|Current state identifier does not contain string value|
 +
 +This is an example of using this condition:
 +<code xml>
 +<action name='myAction' id='doing something'>
 +  <parameter name='stateMachine.state'>open</parameter>
 +  <condition>stateMachine.check</condition>
 +</action>
 +</code>
  
 ====== Required Behaviors ====== ====== Required Behaviors ======
Line 160: Line 151:
 ====== Optional Behaviors ====== ====== Optional Behaviors ======
  
-This behavior does not support optional behaviors.+  * [[behavior_behaviortree|ECBehaviorBehaviorTree]]: Add actions and conditions for behavior trees to use.
  
 ====== Persistency ====== ====== Persistency ======
Line 181: Line 172:
 ====== Element Class Example ====== ====== Element Class Example ======
  
-Example of the _Single State Machine Usage_ .+Example of the //Single State Machine Usage//.
  
 <code> <code>
Line 229: Line 220:
 </code> </code>
  
-Example of the _Multiple State Machine Usage_ .+Example of the //Multiple State Machine Usage//.
  
 <code> <code>
Line 261: Line 252:
 The above example loads and runs two state machines. The first one is running specific state machine. The second state machine provides two separate state machines able to handle multiple logic at the same time. By writing the state machines properly the two state machienes do not interfere with each other and allow to split up state machines into multiple ones which can help create complex logic more simple and stable. The above example loads and runs two state machines. The first one is running specific state machine. The second state machine provides two separate state machines able to handle multiple logic at the same time. By writing the state machines properly the two state machienes do not interfere with each other and allow to split up state machines into multiple ones which can help create complex logic more simple and stable.
  
-_Action and Condition Factory_+//Action and Condition Factory//
  
 This example shows how to use a factory to add a condition checking for a trigger and an action manipulating a trigger. This example shows how to use a factory to add a condition checking for a trigger and an action manipulating a trigger.
Line 301: Line 292:
   <behavior type='ECBehaviorStateMachine' id='second'/>   <behavior type='ECBehaviorStateMachine' id='second'/>
 </elementClass> </elementClass>
-</code> 
- 
-====== Live Examples ====== 
- 
-  * [[https://github.com/LordOfDragons/deexamples|DEExamples Repository]]: Element class changing color using a state machine receiving trigger events. 
-    * [[https://github.com/LordOfDragons/deexamples/blob/master/exampleApp/data/scripts/StateMachineExampleClass.ds|StateMachineExampleClass.ds]] 
-    * [[https://github.com/LordOfDragons/deexamples/blob/master/exampleApp/data/content/stateMachines/colorizer.desm|colorizer.desm]] 
- 
-====== Element Class Properties ====== 
- 
-Element class properties have the prefix **stateMachine.** or **stateMachine(id).** if id is not empty. 
- 
-===== path ===== 
-Path to state machine XML (*.desm) to load. 
-  * Full name: "stateMachine.path" or "stateMachine(id).path" 
-  * Type: Path (*.desm) 
-  * Default Value "" (empty string) 
-  * Example (*.deeclass) <code xml><string name='stateMachine.path'>/content/stateMachines/puzzleBox.desm</string></code> 
- 
-====== Required Behaviors ====== 
- 
-This behavior does not require other behaviors. 
- 
-====== Optional Behaviors ====== 
- 
-This behavior does not support optional behaviors. 
- 
-====== Persistency ====== 
- 
-This behavior does support element class to be persistable (setPersistable). Saves state machine content (#@LinkApiDocDEDS2_HTML~classDragengine_1_1StateMachineSystem_1_1SMContext.html,SMContext~@#). 
- 
-====== API Documentation ====== 
- 
-#@LinkApiDocDEDS2_HTML~classDragengine_1_1Scenery_1_1ECBehaviorStateMachine.html,ECBehaviorStateMachine~@#. 
- 
-Since DragonScript Module Version **1.3** 
- 
-====== Use Cases ====== 
- 
-  * Create element logic without writing state machine using scripts. 
-  * Reuse element logic across different elements. 
-  * Split element logic into smaller logic units using multiple state machines (potentially reused). 
- 
-====== Element Class Example ====== 
- 
-Element class using a state machine loaded from "myBehavior.desm". 
- 
-<code> 
-class MyElementClass extends BehaviorElementClass 
-   public func new() 
-      var ECBehaviorStateMachine smbehavior = ECBehaviorStateMachine.new(this) 
-      smbehavior.getPath().setValue("/content/myBehavior.desm") 
-       
-      // here you can add now behaviors assigining actions and conditions for 
-      // the state machine to use 
-      ... 
-       
-      // add listeners to behaviors to send events to the state machine 
-      var ECBehaviorTwoStateAnimated animated = ... 
-      animated.addActionConditionFactory(MyEventListener.Factory.new(smbehavior)) 
-   end 
-    
-   // two state listeners used to send events 
-   class MyEventListener extends ECBehaviorTwoStateAnimated.DefaultListener 
-      class Factory implements ECBehaviorTwoStateAnimated.ActionConditionFactory 
-         public var ECBehaviorStateMachine stateMachine 
-          
-         public func new(ECBehaviorStateMachine stateMachine) 
-            this.stateMachine = stateMachine 
-         end 
-          
-         public func ECBehaviorTwoStateAnimated.Listener createListener(ECBehaviorTwoStateAnimated.Instance instance) 
-            return MyEventListener.new(stateMachine.instance(instance.getElement())) 
-         end 
-     end 
-      
-     public var ECBehaviorStateMachine.Instance stateMachine 
-      
-     public func new(ECBehaviorStateMachine.Instance stateMachine) 
-        this.stateMachine = stateMachine 
-     end 
-      
-     public func void stopActivate(ECBehaviorTwoStateAnimated.Instance instance) 
-        stateMachine.runEvent("animated activated") 
-     end 
-      
-     public func void stopDeactivate(ECBehaviorTwoStateAnimated.Instance instance) 
-        stateMachine.runEvent("animated deactivated") 
-     end 
-  end 
-end 
 </code> </code>
  
dragengine/modules/dragonscript/behavior_statemachine.1741719129.txt.gz · Last modified: 2025/03/11 18:52 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