Drag[en]gine Wiki

User Tools

Site Tools

Trace:
dragengine:modules:dragonscript:statemachines

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:statemachines [2026/10/09 19:54] – [action] dragonlorddragengine:modules:dragonscript:statemachines [2026/10/13 16:25] (current) – dragonlord
Line 10: Line 10:
 __States__ and __transitions__ can contain __actions__ which modify game state. Actions are typically provided by [[behavior_elements|behaviors]] to control the behavior or behaviors linked to them. Actions are supposed to not fail and throw exceptions only if something is really wrong. Instead they should provide conditions to check if actions could be properly applied or not. If the state machine can not find an action it is treated as if it matches an empty action. It is thus allowed to define actions that do not exist. This can be used to run actions on behaviors which might not be present in an element class. To find problems with missing actions use the debug feature in [[behavior_statemachine|ECBehaviorStateMachine]]. __States__ and __transitions__ can contain __actions__ which modify game state. Actions are typically provided by [[behavior_elements|behaviors]] to control the behavior or behaviors linked to them. Actions are supposed to not fail and throw exceptions only if something is really wrong. Instead they should provide conditions to check if actions could be properly applied or not. If the state machine can not find an action it is treated as if it matches an empty action. It is thus allowed to define actions that do not exist. This can be used to run actions on behaviors which might not be present in an element class. To find problems with missing actions use the debug feature in [[behavior_statemachine|ECBehaviorStateMachine]].
  
-__Conditions__ can be paramtrized by adding one or more parameters to the rule. The conditions define themselves which parameters they understand and how they react to them. The name of parameters is free but it is recommended to use a naming scheme like this: ''<source>.<parameter>''. This groups parameters and reduces the chance of name conflicts. This is especially important since parameters are also reused for action rules. And while actions already define the ''source'' part rather well for conditions this is unknown.+__Conditions__ can be parametrized by adding one or more parameters to the rule. The conditions define themselves which parameters they understand and how they react to them. The name of parameters is free but it is recommended to use a naming scheme like this: ''<source>.<parameter>''. This groups parameters and reduces the chance of name conflicts. This is especially important since parameters are also reused for action rules. And while actions already define the ''source'' part rather well for conditions this is unknown. 
 + 
 +__Condition Groups__ allow to create complex, nested conditions. This can be used to represent mixed ''and''/''or'' condition trees as well as checking the same condition more than once but using conflicting parameters.
  
 States can have __enter actions__ and __exit actions__. __Enter actions__ run after activating the state. Exit actions run before switching to another state. Enter and exit actions both can have conditions which determine if the action is run or not. Enter actions can have a __state change__ assigned. If an enter action with a state change is run the state changes immediately to the specified state and all enter actions afterwards are ignored. This can be used to automatically transition into another state for example if a pre-condition is not fulfilled or an earlier action failed to run properly. In particular no action can be assigned in which case the enter action only serves the purpose to transition into another state if its conditions fail. In addition states can be assigned an __auto-transition state__. If all enter actions are processed and the state has an auto-transition state assigned the auto-transition state is immediately activated. This allows to create pass-through states which only run a couple of enter actions then transition into the final state. States can have __enter actions__ and __exit actions__. __Enter actions__ run after activating the state. Exit actions run before switching to another state. Enter and exit actions both can have conditions which determine if the action is run or not. Enter actions can have a __state change__ assigned. If an enter action with a state change is run the state changes immediately to the specified state and all enter actions afterwards are ignored. This can be used to automatically transition into another state for example if a pre-condition is not fulfilled or an earlier action failed to run properly. In particular no action can be assigned in which case the enter action only serves the purpose to transition into another state if its conditions fail. In addition states can be assigned an __auto-transition state__. If all enter actions are processed and the state has an auto-transition state assigned the auto-transition state is immediately activated. This allows to create pass-through states which only run a couple of enter actions then transition into the final state.
  
-Upon receiving an __event__ the state machine checks transitions defined in the current state from the first defined to the last defined. The first transition matching the event with all of its conditions evaluating to true is used. All matching transitions afterwards are ignored.If no transition matches the event is discarded. It is thus fully legit to send an event to a state machine for states not supporting this particular event. Transitions can have __actions__ assigned. They behave similar to enter actions of states. In particular they can also contain a state change which is useful for situations where actions are unable to properly to transition into an error type state. Transitions typically have a __next state__ assigned but this is optional. If no next state is set the transition only runs actions and stays in the current state. If all actions finished running and a next state is set then the state changes to the next state. If a next state is set the transition first switches the state machine to the null state to run exit actions. Then the transition actions are run. Afterward the state is changed.+Upon receiving an __event__ the state machine checks transitions defined in the current state from the first defined to the last defined. If no transition is found the global transitions in the state machine itself are check. The first transition matching the event with all of its conditions evaluating to true is used. All matching transitions afterwards are ignored.If no transition matches the event is discarded. It is thus fully legit to send an event to a state machine for states not supporting this particular event. Transitions can have __actions__ assigned. They behave similar to enter actions of states. In particular they can also contain a state change which is useful for situations where actions are unable to properly to transition into an error type state. Transitions typically have a __next state__ assigned but this is optional. If no next state is set the transition only runs actions and stays in the current state. If all actions finished running and a next state is set then the state changes to the next state. If a next state is set the transition first switches the state machine to the null state to run exit actions. Then the transition actions are run. Afterward the state is changed.
  
 Transitions can also define a __delegate event__ instead of a next state. If delegate event is set the transition runs all actions then runs the delegate event on the state machine. This does not count as transition in transition situation since the delegate event replaces the current event. Delegate events are useful to run shared transition logic without importing the logic into each transition. Instead a unique event is used which can be easily reused and overwritten to make state machines cleaner and more stable. Transitions can also define a __delegate event__ instead of a next state. If delegate event is set the transition runs all actions then runs the delegate event on the state machine. This does not count as transition in transition situation since the delegate event replaces the current event. Delegate events are useful to run shared transition logic without importing the logic into each transition. Instead a unique event is used which can be easily reused and overwritten to make state machines cleaner and more stable.
Line 62: Line 64:
 } }
 state --> transition state --> transition
 +stateMachine --> transition
 transition --> action transition --> action
  
Line 143: Line 146:
   * ''allFalse'': All conditions have to evaluate to false.   * ''allFalse'': All conditions have to evaluate to false.
 </WRAP>|0..1|''allTrue''| </WRAP>|0..1|''allTrue''|
 +|conditionGroup|Add condition group. Allows to create complex, nested conditions.|0..N|-|
 |import|Import enter actions from existing state with identifier|0..N|-| |import|Import enter actions from existing state with identifier|0..N|-|
 +
 +===== conditionGroup =====
 +
 +Defines a condition group. Condition groups allow to create complex, nested conditions.
 +
 +^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''|
 +|conditionGroup|Add condition group. Allows to create complex, nested conditions.|0..N|-|
  
 ====== Examples ====== ====== Examples ======
Line 281: Line 302:
  <transition event='interact.primary.stop' delegate='endScreen.exit'/>  <transition event='interact.primary.stop' delegate='endScreen.exit'/>
  <transition event='interact.secondary.stop' delegate='endScreen.exit'/>  <transition event='interact.secondary.stop' delegate='endScreen.exit'/>
 + </state>
 +</stateMachine>
 +</code>
 +
 +This example shows the use of condition groups to create complex, nested conditions. The checked condition represents this expression: ''isSitOn or (not inConversation and not inTransition)''.
 +
 +<code xml><?xml version='1.0' encoding='ISO-8859-1'?>
 +<stateMachine>
 + <state id='complexCondition'>
 + <transition event='touchTrigger' state='doSomething'>
 + <conditionMode>any</conditionMode>
 +
 + <conditionGroup>
 + <condition>sitOn.check</condition>
 + <parameter name='isSitOn'>true</parameter>
 + </conditionGroup>
 +
 + <conditionGroup>
 + <condition>conversation.check</condition>
 + <parameter name='inConversation'>false</parameter>
 +
 + <condition>action.check</condition>
 + <parameter name='inTransition'>false</parameter>
 + </conditionGroup>
 + </transition>
  </state>  </state>
 </stateMachine> </stateMachine>
dragengine/modules/dragonscript/statemachines.1791575686.txt.gz · Last modified: 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