StateTree is a general-purpose hierarchical state machine that combines the Selectors from behavior trees with States and Transitions from state machines. Users can create highly performant logic that stays flexible and organized.
It seems that StateTree has become a official plugin in UE5.1, but it is still in beta in UE5.0.3.
1. Basic Concepts
A StateTree in Unreal Engine is a editable asset, which contains a lot of states, each state in StateTree is called a State, and a state contains Tasks, Transitions, Evaluators and Enter conditions.
The following image is a classcial example:
As we can seen, a state can contains several child state, there is no essential difference between states and child states, child states is a state attach to a parent state.
And here are the property of a state, which contains Tasks, Enter Conditions etc that we have mentioned before.
StateTree contains states arranged in tree view, which initially run from the root node, but the state selection can be triggered at any location in the treeview. During the selection of process, each state’s Enter Condition is evaluated. Image that there is a StateIterator from the root node, the iterator will advance to the state’s child state if passed the enter conditions, if no child state avaiable, the state itself will be ignored.
Selecting a State will activate all of the States from the root to the leaf State. Each state consists of Tasks and Transitions.
When a state is selected, the selected state and all of its parent state will be executed at the same time. In programm, which is starting from the root down to the child.
Each Task provides an output to the StateTree. Common output examples include selecting a target, playing an animation, and looking at an object. Each State can have multiple Tasks, and all Tasks in a State run concurrently as long as the State remains active. The first Task that completes its execution triggers a Transition which can result in the selection of a new State.
Back to the image we seen just before:
It is an example given by Epic, the following are the concepts of it:
| Legend | StateTree Element | Description |
|---|---|---|
| 1 | Root | First State selected when the StateTree starts running. |
| 2 | State Selector | Refers to a State that has child States. This State will never be selected directly, and selection will continue to one of its child States. |
| 3 | State Enter Condition | Refers to the list of conditions that determine whether a State can be selected. |
| 4 | State Task | Refers to a set of actions that belong to a State and are executed when the State becomes active. |
| 5 | State Transition | Defines the conditions that trigger the State selection process. A Transition is triggered when a Task completes, succeeds, or fails, or when a monitored condition succeeds. |
There is no evaluator in this image, but in short, it provided the data used in the following states, we will introduce to it soon.
There is a schema in StateTree:
This is not that one we have used in GraphEditor before, instead, a schema in StateTree is used as a method to providing data to the StateTree. Acutally, providing data to StateTree is not by using blackboard, we will introduce it in the following content.
2. Selection Flow
StateTree selects active States similarly to a behavior tree. State selection starts from root on the first Tick, and it continues down the tree evaluating each State’s Enter Conditions.
- If the Enter Conditions do not pass, the selection proceeds to the next sibling State.
- If the Enter Conditions pass, and the State is a leaf State, it is selected as a new State.
- If the State has child States, the same process continues on to the first child State until a leaf State is found.
Note that If a State has child States, yet none can be selected (their Enter Conditions fail), the State will not be selected even if all its Enter Conditions passed the test.
One of the big differences between behavior trees and state machines is that state machines usually commit State selection as the execution goes down the tree, compared to behavior trees which try to find a suitable leaf node.
That is that means? Note that the behavior tree keeps executing the logic of selecting a node even a node has already been seleced, however, in the StateTree, it only happends when a state doing transition. Transition decides when to execute the logic of selecting state.
3. Flow Examples
Sequences
It seems that it is easily to do a select, but what about sequence? Here is an example
When the Reach state finished, the StateTree will advance to Use state by setting the transition of reach to use when complete. the parent state, Smart Object state, becomes a virutal sequencer now.
Failure handling
StateTree handles Task completion failure in a hierarchical way, starting with the active Task and going up the tree.
In the example above, the Reach Slot State will move execution to the next State on success (Wait), or it will move execution to its parent State on failure (Wait at Intersection). The Wait at Intersection State will trigger a Transition to the Idling State if any of its child States fail.
The Wait State will move execution to itself indefinitely on success or failure until its parent State selects a different State.
Hirarchical Data
Tasks can share data between each other. The data exposed by a Task will be available to any other Task that belongs to an active State. This makes resource handling in the StateTree more efficient.
In the example above, the Crowd Claim Wait Slot Task will try to claim a Smart Object Slot for the AI Agent, and if it is successful, it will pass execution to the Move To Wait Slot Task. This Task will use the Slot location from the parent Task. If successful, it will pass execution to the Wait At Slot Task, which will use the Slot Location from its parent Task as well.
Smart Objects will be discussed in the following posts.
4. Data Flow
The common data types available to all nodes in the State Tree are:
State Tree Parameters
I didn’t find how to this anyway, if someone knows, please tell me, thank you.
Context Data
It is by schema to be accurately. The Context Data refers to the predefined data available to the State Tree based on the selected State Tree Schema. This changes based on where the State Tree is used. For example, a State Tree used by an Actor will have that actor as its Context. However, if the same State Tree is used with a Smart Object behavior, the Context will refer to the Smart Object used and the Actor that uses it.
Evaluators
Evaluators provide a way to expose data to the State Tree that would otherwise not be possible to do with Parameters or Context Data. Evaluators are a separate class that can be executed in a State Tree during runtime. Evaluators contain variables and can execute custom code when the tree starts, stops, and on each Tick. The properties of an Evaluator can be bound to Parameters or Context Data, or other Evaluators that come before in the Evaluator list.