User Tools

Site Tools


dragengine:modules:dragonscript:behavior_statemachine

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 an SMContext. Other behaviors can add actions and 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:

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

Action and Condition Factory

You can assign actions and conditions without using other behaviors by using one or more Action/Condition Factories. The factories are added to the behavior. Upon creating the behavior instances the factories are asked to create and assign SMAction and SMCondition.

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

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

Instance Counts

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.

This is an example code for such a setup:

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

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)
    <string name='stateMachine.path'>/content/stateMachines/puzzleBox.desm</string>

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 (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

Element class using a state machine loaded from “myBehavior.desm”.

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

Live Examples

You could leave a comment if you were logged in.
dragengine/modules/dragonscript/behavior_statemachine.txt · Last modified: 2024/03/14 16:43 by dragonlord