StateTree Quick Start Guide (2024)

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.

You can learn more about State Trees by reading the State Tree Overview documentation.

Goals

In this guide you will use a State Tree to create a moving target the player can shoot and destroy.

Objectives

• Create a Blueprint for a target Actor the player can shoot and destroy.

• Create the State Tree that contains the logic to move and destroy the target actor.

• Create State Tree Tasks and use them in the State Tree.

• Create a State Tree Evaluator and use it in the State Tree.

1 - Required Setup

1. Create a new project then select the Games category and the First Person template. Enter your project's location and name. Click Create.

   Click image for full size.

2. Click Settings > Plugins to open the Plugins window.

   

3. Search for and enable the GameplayStateTree and StateTree plugins. Restart the Unreal Engine editor.

   

Section Results

In this section, you created a new project and enabled the State Tree plugins. You are now ready to create the State Tree you will use in the target Actor.

2 - Create the State Tree

In this section, you will create a State Tree that will be used by the target Actor. This State Tree is intended to be used as a component of the target Actor, so you will use the State Tree Component Schema for this example.

1. In the Content Browser, right click and select Artificial Intelligence > StateTree.

   

2. Select the StateTreeComponentSchema class and click Select.

   

3. Name the State Tree ST_ShootingTarget.
   

   

Section Results

In this section, you created a State Tree with the Component Schema that will be used by a target Actor.

3 - Create the Shooting Target Blueprint

In this section, you will create the Blueprint for the target Actor that will move and receive damage from the player.

1. In the Content Browser, right click and select Blueprint Class from the Create Basic Asset section.

   1. In the Pick Parent Class window, click the Actor button to create a new Actor Blueprint.

   2. Name the Blueprint BP_ShootingTarget.

   

   
   

   

2. Open BP_ShootingTarget and go to the Components window. Click +Add and select Static Mesh.

   1. Go to the Details panel and scroll down to the Static Mesh section.

   2. Click the Static Mesh dropdown and select 1M_Cube.

   
   

   

3. Set the Scale of the Static Mesh to X = 0.2, Y = 2.0, Z = 2.0.

   

4. In the Components window, click +Add and select StateTree.

   See Also

   State Machines vs Behavior Trees: designing a decision-making architecture for roboticsBehavior Tree OverviewBehavior Tree Quick Start Guide

   1. Go to the Details panel and scroll down to the AI section.

   2. Click the State Tree dropdown and select ST_ShootingTarget.

   

   

   If the State Tree does not appear in the dropdown, it means that the incorrect schema was selected. Make sure to select the StateTreeComponentSchema to use in the State Tree component.

5. Right-click the Static Mesh component and select Add Event > Add OnComponentHit.

   

6. Create a new variable and name it HitCount.

   1. Go to the Details panel and set the Variable Type to Integer.

   
   

   

7. Drag the HitCount variable to the Event Graph and select Get HitCount.

   1. Drag from the HitCount node and search for and select Increment Int.

   2. Connect the On Component Hit node to the Increment Int node.

   

Section Results

In this section, you created the Shooting Actor Blueprint the player will shoot during gameplay. You are now ready to create the Idle and Dead States of the State Tree.

4 - Create the Idle and Dead States

1. Go back to ST_ShootingTarget and under the Schema section, click the Context Actor Class dropdown. Select BP_ShootingTarget.

   

2. Click + Add State to create a new State and name it Idle.

   

3. Go to the Details panel and scroll down to the Transitions section.

   1. Expand the Go to State section and click the Transition To dropdown. Select Root. This will set the State Tree to transition back to the Root State once this State is completed.

   

   

4. Create another State and name it Dead.

   

5. Select the Idle State and add another Transition.

   1. Click the Trigger dropdown and select On Tick.

   2. Click the Transition To dropdown and select Dead.

   

6. Add a new Condition by clicking on the plus sign. Click the dropdown and select Integer Compare.

   1. Expand the structure and click on the Left Bind dropdown and select Actor > Hit Count. This binds the value of Hit Count inside BP_ShootingTarget to the StateTree Condition.

   2. Enter 5 as the value of the Right integer.

   

   

   

Section Results

In this section, you added the Idle and Dead States to the State Tree. You are now ready to create a State Tree Task that will handle the Dead State.

5 - Create a New State Tree Task

In this section, you will create a new State Tree Task that will destroy the Actor when the Dead State is executed.

1. In the Content Browser, right click and select Blueprint Class.

   1. In the Pick Parent Class window, expand the All Classes dropdown and search for and select StateTreeTaskBlueprintBase.

   2. Click Select to create the asset.

   3. Name the Blueprint class STT_Destroy.

   

   
   

   

2. Open STT_Destroy by double-clicking it in the Content Browser. Go to the Functions section and click the Override dropdown. Select ExitState.

   

3. Create a new variable and name it Actor. Set its type to Actor Object Reference.

   1. Go to the Details panel, and set its Category to Context.

   2. Drag the Actor variable to the Event Graph and select Get Actor.

   3. Drag from the Actor node and search for and select Destroy Actor.

   4. Connect the Event ExitState node to the Destroy Actor node.

   

   

   

Section Results

In this section, you create a new State Tree Task that runs once the Dead State is executed. This Task destroys the Actor.

6 - Finish the Dead State

1. Go back to ST_ShootingTarget and select the Dead State. Add a new Task and select Debug Text Task from the dropdown.

   1. Enter ‘Actor Destroyed' in the Text field.

   2. Enter a Text Color and a Font Scale.

   

2. Add another Task and select Delay Task from the dropdown.

   1. Enter 2.0 for the Duration.

   

3. Add a third Task and select STT_Destroy from the dropdown. This will destroy the Actor.

   

4. Create a new Transition and set the Trigger to On State Completed.

   1. Set the Transition To dropdown to Tree Succeeded.

   

5. Drag BP_ShootingTarget to your Level and press Play. Shoot the Blueprint and confirm the State Tree is working.

   

   

Section Results

In this section, you completed the Dead State and tested that the Shooting Actor Blueprint can receive damage and be destroyed.

7 - Add a Spline Path

In this section, you will create an Actor with a Spline component. This spline will be used by the Shooting Target Blueprint to move in the Level.

1. In the Content Browser, right click and select Blueprint Class from the Create Basic Asset section.

   1. In the Pick Parent Class window, click the Actor button to create a new Actor Blueprint.

   2. Name the Blueprint BP_SplineActor.

   

   

   

2. Open BP_SplineActor and go to the Components window. Click +Add and select Spline.

   1. Compile and Save the Blueprint.

   

Section Results

In this section, you created a generic Blueprint Actor that has a Spline component. This Spline will be used to create a moving path for the Shooting Actor in the Level.

8 - Add a State Tree Evaluator

Now you will create a State Tree Evaluator that will search for all Spline Actors in the Level and return the closest one to the State Tree.

1. In the Content Browser, right click and select Blueprint Class from the Create Basic Asset section.

   1. In the Pick Parent Class window, expand the All Classes dropdown and search for and select StateTreeEvaluatorBlueprintBase.

   2. Click Select to create the asset.

   3. Name the Blueprint class STE_GetSpline.

   

   

   

2. Open STE_GetSpline and go to the Functions section of the My Blueprint panel.

   1. Click the Override dropdown and select TreeStart.

   

3. Drag from the Event TreeStart node and search for and select Get All Actors of Class.

   1. Click the Actor Class dropdown and select BP_SplineActor.

   

4. Create a new variable and name it Actor.

   1. Go to the Details panel and set the Variable Type to Actor Object Reference.

   2. Click the Category dropdown and enter ‘Context'.

   

   

5. Drag from the Out Actors pin of the Get All Actors from Class node and search for and select Find Nearest Actor.

   1. Drag the Actor variable to the Event Graph and select Get Actor.

   2. Drag from the Actor node and search for and select Get Actor Location.

   3. Connect the Return Value of the Get Actor Location node to the Origin pin of the Find Nearest Actor node.

   

6. Drag from the Return Value pin of the Find Nearest Actor node and search for and select Cast to BP_SplineActor.

   1. Right click on the As BP Spline Actor pin of the Cast to BP_SplineActor node and select Promote to Variable.

   2. Name this variable to SplineActor and enter ‘Output' for its Category.

   3. Compile and Save the Blueprint.

   

   

7. Go back to ST_ShootingTarget and under the StateTree window, click the plus sign next to Evaluators.

   1. Click the dropdown and select STE_GetSpline.

   

Section Results

In this section, you created a State Tree Evaluator that will execute when the State Tree begins execution. This Evaluator checks for all Spline Actors in the Level and returns the closest one to the Shooting Actor.

9 - Add a State Tree Task to Move Along Spline

In this section, you will create a new State Tree Task that will move the Actor along the BP_SplineActor's spline.

1. In the Content Browser, right click and select Blueprint Class.

   1. In the Pick Parent Class window, expand the All Classes dropdown and search for and select StateTreeTaskBlueprintBase.

   2. Click Select to create the asset.

   3. Name the Blueprint class STT_MoveAlongSpline.

   

   
   

   

2. Open STT_MoveAlongSpline and go to the Functions section of the My Blueprint panel. Click the Override dropdown and select Tick.

   

3. Create a new variable and name it Actor.

   1. Go to the Details panel and set the Variable Type to Actor Object Reference.

   2. Click the Category dropdown and enter ‘Context'.

   

   

4. Create a new variable and name it SplineActor.

   1. Go to the Details panel and set the Variable Type to BP_SplineActor.

   2. Enter ‘Input' as the Category.

   
   

   

5. Drag the Actor variable to the Event Graph and select Get Actor.

   1. Drag from the Actor node and search for and select Set Actor Location.

   2. Connect the Tick node to the Set Actor Location node.

   

6. Drag the SplineActor to the Event Graph and select Get Spline Actor.

   1. Drag from the SplineActor node and search for and select Spline.

   2. Drag from the Spline node and search for and select Get Location at Distance Along Spline.

   3. Connect the Return Value of the Get Location at Distance Along Spline node and connect it to the New Location pin of the Set Actor Location node.

   4. Right click the Distance pin of the Get Location at Distance Along Spline node and select Promote to Variable.

   

7. Drag from the Set Actor Location node and search for and select Branch.

   1. Drag the Distance variable to the Event Graph and select Get Distance.

   2. Drag from the Distance node and search for and select Less.

   3. Connect the Less node to the Condition pin of the Branch node.

   

8. Drag the SplineActor to the Event Graph and select Get Spline Actor.

   1. Drag from the SplineActor node and search for and select Spline.

   2. Drag from the Spline node and search for and select Get Spline Length.

   3. Connect the Return Value from the Get Spline Length node and connect it to the lower pin of the Less node.

   

9. Drag the Distance variable to the Event Graph and select Get Distance.

   1. Drag from the Distance node and search for and select Add.

   2. Create a new variable of type Float and name it MovementSpeed.

   3. Connect MovementSpeed to the lower pin of the Add node.

   4. Drag the Distance variable to the Event Graph and select Set Distance.

   5. Connect the Add node to the Set Distance node.

   6. Connect the True pin of the Branch node to the Set Distance node, as seen below.

   

10. Select the MovementSpeed variable and set its Default value to 5.0.

    

11. Drag the Distance variable to the Event Graph and select Set Distance.

    1. Connect the False pin of the Branch node to the Set Distance node.

    2. Connect both Set Distance nodes to the Return Node with a Return Value of Running.

    

    

Section Results

In this section, you create a State Tree Task that moves the Shooting Actor Blueprint along the spline path created with the Spline Actor Blueprint.

10 - Finalize the State Tree

1. Go back to ST_ShootingTarget and click +Add State. Name the new State MoveAlongSpline.

   1. Click and drag the MoveAlongSpline State into the Idle State to parent it.

   
   

   

2. Go to the Details panel and add a new Task by clicking the + button.

   1. Click the dropdown and select STT_MoveAlongSpline.

   2. Click the Bind dropdown next to Spline Actor and select STE Get Spline > Spline Actor.

   

   

   

3. Drag BP_SplineActor to the Level.

   

4. Select the Spline component of BP_SplineActor. Alt-drag to create new spline points and create a closed shape.

   1. Select the Spline component of the Spline Actor Blueprint and scroll down to the Spline section. Enable the Closed Loop checkbox to make the spline a closed shape.

   
   

   

5. Press Play and shoot at the target.