StateTree Overview

Overview

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.

StateTree contains States that are arranged in a tree structure. The State selection can be triggered at any location in the tree, but it initially starts from the root. During the selection process, each State's Enter Conditions are evaluated. If they pass, the selection advances to the State's child States, if available. If no child States are available, the current State is activated.

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 its parent States become active. All Tasks are executed for all active States, starting from the root, down to the selected State.

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.

As a simple example, you could create a time of day system using StateTree. You would create a State for each time of the day, and underneath each State you would create separate Tasks. Each Task could handle different elements, such as fog density, sky sphere color, and so on.

Another example would be having an AI Agent walk around the level and constantly check for hits while looking around. You could have a State for walking and looking around, and another for reacting to a hit.

A Transition in a StateTree can point to any other State in the tree. Transitions have Trigger Conditions that need to be met before the transition triggers the State selection process.

If the State selection succeeds, a new State will be selected. Some Transitions are monitored constantly, while others only execute on State completion. Transitions are evaluated starting from the leaf State and progressing upwards toward the root. During this process, the first Transition that succeeds and leads to State selection is selected. This hierarchy allows for grouping of common Transitions.

These are the different elements of the StateTree:

Selection Flow

Selecting a new State

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.

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.

In general terms, behavior trees keep executing the State selection logic even when a State has been selected. This is the only method for transitioning between States.

StateTree runs the State selection process on-demand, based on Transitions. On the first tick, there is an implicit transition to the root State, which will select the first State to run. Once that State has been selected, the Transitions dictate when and where the selection logic will be executed.

Executing the State Tasks

Once a State is selected, all its Tasks will begin executing concurrently. The Tasks will continue executing until a Transition triggers the selection process and a State is selected. The selected State can be the current State (the State continues executing) or a new State.

The most common Transition trigger is completion, which is executed once the first Task of the active State finishes. Other Transitions can be marked as Tick and are tested on each tick. If the conditional Transition passes the test, the State selection logic is executed and the selection process starts at the target State. If the target State has child States, the selection process will consider the child States as part of the selection logic.

Data Flow

State Trees use data binding to pass data within the tree. The data binding can be used to create conditions, or to configure Tasks to run. The data binding can access data passed into the State Tree, or between the nodes in a specific manner.

The common data types available to all nodes in the State Tree are:

StateTree nodes can share data among themselves. The different elements in the StateTree can bind to data in the following manner:

Blueprint Integration

StateTree is designed to be extended via Blueprint scripting. You can create custom Tasks, Evaluators, and Conditions by extending the following Blueprint classes:

Following up with the example mentioned before, you could create a time of day system using StateTree and Blueprints. This system would change the fog density of the Level depending on the time. The system could also check for a storm spell to change the lighting conditions regardless of time.

For this example, you could create the following Blueprint classes:

Common Patterns

Grouping Similar Tasks

Tasks can be grouped under a common State. In the example above, there is a State that handles Smart Objects in the world. This State contains child States that handle Reaching the Smart Object and Using the Smart Object.

Each of these child States contains Tasks that execute when that State is selected. The Reach child State contains Tasks that find the Smart Object and move the AI Agent to the Smart Object.

When you use this grouping strategy, all Tasks share the same Transitions via the State.

Sequences

StateTree comes with the Next Transition, which simplifies creating and arranging a sequence of States.

In the example above, when the Reach State is selected, the Find SO Target, Move to SO, and Look Tasks are executed. Once the Tasks are completed, the Next Transition moves execution to the Use State below, where its Tasks can begin executing.

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.

Hierarchical 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.

Refining Behavior

StateTree provides a way to organize Tasks such that contextual behaviors can be achieved easily.

In the example above, the Wait State handles the AI Agent's standing locomotion - the AI Agent looks around and reacts when hit. By default, the Wait Look State will be executed. If the State succeeds, it will return execution to its parent. However, if it fails, it will move execution to the Wait Hit State.

The Wait Hit State will execute the Mass LookAt and Mass Contextual Anim Tasks. These Tasks will then play the appropriate animation to the hit.