User Tools

Site Tools


dragengine:modules:dragonscript:behavior_statemachine

This is an old revision of the document!


ECBehaviorStateMachine

Example usage of State machine Behavior. See StateMachineExampleClass.ds and colorizer.desm

Behavior element behavior adding StateMachine support.

Loads state machine from file (*.desm) and creates a SMContext. Other behaviors can add actions and conditions to this state machine allowing to compose state machine actions and conditions easily.

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 SMAction and SMCondition.

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

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.

See Element Class Example for example code.

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.

See Element Class Example for example code.

Instance Counts

This behavior can be used multiple times on an element to add multiple custom colors to mainpulate. Use the behavior identifier to tell them apart.

Element Class Properties

Element class properties have the prefix stateMachine. or stateMachine({id}). if id is not empty.

path

Set path to state machine file to load.

  • Full name: stateMachine.path or stateMachine({id}).path
  • Type: string
  • Default Value: empty string
  • Expected File Type: *.desm
  • Example (*.deeclass)
    <string name='stateMachine.path'>actor.desm</string>

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)
    <string name='stateMachine.debug'>Debug-Actor-SM</string>

Events

This behavior has no events.

State Machine Actions

This behavior adds these state machine actions.

element.set

Set owner element parameters.

ParameterValueDescription
visibletrue,falseSet if element is visible.
touchabletrue,falseSet if element is touchable.

This is an example of using this action to fully hide the owner element:

<action name='element.set'>
  <parameter name='visible'>false</parameter>
  <parameter name='touchable'>false</parameter>
</action>

element.update

Update owner element.

ParameterValueDescription
dispose Dispose of owner element. Make sure this is the last action run in a transition or state. Running actions afterwards can lead to problems.
logstringPrint a log message using Element.log() function.

This is an example of using this action to dispose element:

<action name='element.set'>
  <parameter name='dispose'/>
</action>

gameWorld

Runs action from game world behavior GWBehaviorBTSM. Game world behaviors can add state machine actions to GWBehaviorBTSM similar to how element class behaviors can add state machine actions to this behavior. This allows state machines to access actions specific to a game world. The action is run as if it has been added to this behavior. All parameters defined in the action are passed to the game world action with the addition of the parameter element set to the behavior element owning the state machine. If the element owning this behavior is not in a game world or the action can not be found, nothing is done.

ParameterValueDescription
actionstringName of action to run.
receiveEventstrue,falseEnable receiving game world events

This is an example of using this action to spawn a new element:

<action name='gameWorld'>
  <parameter name='action'>spawn</parameter>
  <parameter name='class'>MyGameObjectClass</parameter>
  <parameter name='properties'>propertyName1:propertyValue1 propertyName2:propertyValue2</parameter>
  <parameter name='spawnPoint'>spawn point name</parameter>
</action>

State Machine Conditions

This behavior adds these state machine conditions.

element.check

Evaluate owner element parameters.

ParameterValueDescription
element.visibletrue,falseElement is visible or not.
element.touchabletrue,falseElement is touchable or not.
element.inGameWorldtrue,falseElement is located in game world or not.
element.hasParenttrue,falseElement is parented to another element or not.

This is an example of using this condition to check if the element is visible, touchable, in a game world and not parented to another element:

<action name='myAction'>
  <condition>element.check</condition>
  <parameter name='element.visible'>true</parameter>
  <parameter name='element.touchable'>true</parameter>
  <parameter name='element.inGameWorld'>true</parameter>
  <parameter name='element.hasParent'>false</parameter>
</action>

gameWorld

Evaluate condition from game world behavior GWBehaviorBTSM. Game world behaviors can add state machine conditions to GWBehaviorBTSM similar to how element class behaviors can add state machine conditions to this behavior. This allows state machines to access conditions specific to a game world. The condition is evaluated as if it has been added to this behavior. All parameters defined in the condition are passed to the game world condition with the addition of the parameter gameWorld.element set to the behavior element owning the state machine. If the element owning this behavior is not in a game world or the condition can not be found, false is returned.

ParameterValueDescription
gameWorld.conditionstringName of condition to evaluate.

This is an example of using this condition to evaluate a game state:

<action name='myAction'>
  <condition>gameWorld</condition>
  <parameter name='gameWorld.condition'>winningCondition.check</parameter>
  <parameter name='gameWorld.condition.foundCounts'>10</parameter>
</action>

Behavior Tree Actions

This behavior adds these behavior tree actions if behavior tree is present. If behavior has non-empty identifier replace attachSlot with attachSlot(id).

attachSlot.update

Update attach slot.

ParameterValueDescription
detachempty string, disposeDetach attachable if one is present. If value is dispose dispose of attachable after detaching it
interactElement.assignstringAssign attached element to ECBehaviorInteractElement with identifier matching value string. Action fails if no element is attached or interact element behavior is absent
interactstringInteract with attachable. If element is absent action fails. Runs interaction with name value. If interaction with name value is absent fails action. If interaction returns false fails action. Otherwise action succeeds.
interact.parametersstringOptional parameters to use with interaction.

This is an example of using this action:

<action name='attachSlot.set'>
  <parameter name='detach'>dispose</parameter>
</action>

attachSlot.check

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

ParameterValueDescription
emptytrue, falseAttach slot is empty or not
interact.namestringName of interaction
interact.hastrue, falseHas attachable and interaction with name interaction.name is present
interact.querytrue, falseInteract with attachable and test result. Condition is true if attachable is present, interaction with name interaction.name is present and interaction returns true. It is recommended to use here only interactions without side effects (hence query interactions).
interact.parametersstringOptional parameters to use with interaction.query.
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:

<sequence>
  <action name='attachSlot.check'>
    <parameter name='empty'>false</parameter>
  </action>
  <!-- actions here run only if attach slot is not empty, hence an attachable is present -->
</sequence>

Behavior Tree Conditions

This behavior adds these behavior tree conditions if behavior tree is present. If behavior has non-empty identifier replace attachSlot with attachSlot(id).

attachSlot.check

Check one or more attach slot parameters. Conditions returns true if all parameter value match their respective attach slot parameter. This condition is typically used to run an action or sequence of actions as long as attach slot conditions are true.

ParameterValueDescription
attachSlot.emptytrue, falseAttach slot is empty or not
attachSlot.interact.namestringName of interaction
attachSlot.interact.hastrue, falseHas attachable and interaction with name interaction.name is present
attachSlot.interact.querytrue, falseInteract with attachable and test result. Condition is true if attachable is present, interaction with name interaction.name is present and interaction returns true. It is recommended to use here only interactions without side effects (hence query interactions).
attachSlot.interact.parametersstringOptional parameters to use with interaction.query.

This is an example of using this condition:

<action name='myAction' id='doing something'>
  <parameter name='attachSlot.empty'>false</parameter>
  <condition>attachSlot.check</condition>
</action>

Required Behaviors

This behavior requires no other behaviors.

Optional Behaviors

Persistency

This behavior does support element class to be persistable (setPersistable). Saves state machine content (SMContext).

API Documentation

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

Example of the Single State Machine Usage.

class MyElementClass extends BehaviorElementClass
  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
      
      func new(ECBehaviorStateMachine stateMachine)
        this.stateMachine = stateMachine
      end
      
      func ECBehaviorTwoStateAnimated.Listener createListener(ECBehaviorTwoStateAnimated.Instance instance)
        return MyEventListener.new(stateMachine.instance(instance.getElement()))
      end
    end
    
    public var ECBehaviorStateMachine.Instance stateMachine
    
    func new(ECBehaviorStateMachine.Instance stateMachine)
      this.stateMachine = stateMachine
    end
    
    func void stopActivate(ECBehaviorTwoStateAnimated.Instance instance)
      stateMachine.runEvent("animated activated")
    end
    
    func void stopDeactivate(ECBehaviorTwoStateAnimated.Instance instance)
      stateMachine.runEvent("animated deactivated")
    end
  end
end

Example of the Multiple State Machine Usage.

class MyElementClass extends BehaviorElementClass
  func new()
    var ECBehaviorStateMachine smSpecific = ECBehaviorStateMachine.new(this, "specific")
    smSpecific.getPath().setValue("/content/mySpecificBehavior.desm")
    
    var ECBehaviorStateMachine smGeneric = ECBehaviorStateMachine.new(this, "idle")
    smGeneric.getPath().setValue("/content/myGenericBehavior.desm")
    
    // here you can add now behaviors assigining actions and conditions for both
    // state machines to use
    ...
    
    // add listeners to behaviors to send events to the state machine. the same
    // MyEventListener is used as in the single state machine example. the example
    // here uses two animated behaviors each sending events to one of the state
    // machines. in general using multiple state machines the events should be
    // disjoint but it is fully valid to send the same event to both if the
    // state machines are written to deal with this properly.
    var ECBehaviorTwoStateAnimated animated1 = ...
    animated1.addActionConditionFactory(MyEventListener.Factory.new(smSpecific))
    
    var ECBehaviorTwoStateAnimated animated2 = ...
    animated2.addActionConditionFactory(MyEventListener.Factory.new(smGeneric))
  end
end

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

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

class MyElementClass extends BehaviorElementClass
  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

Behavior Factory

Using element class supporting adding behaviors the behavior can be added like this:

<?xml version='1.0' encoding='UTF-8'?>
<elementClass name='MyClass' class='GenericBehaviorElement'>
  <behavior type='ECBehaviorStateMachine'>
    <!-- set element properties. omit property prefix if used inside behavior tag -->
    <string name='.path'>actor.desm</string>
  </behavior>
 
  <!-- for adding multiple behaviors use unique identifiers -->
  <behavior type='ECBehaviorStateMachine' id='second'/>
</elementClass>

Live Examples

You could leave a comment if you were logged in.
dragengine/modules/dragonscript/behavior_statemachine.1791761147.txt.gz · Last modified: by dragonlord