1. Introduction to State Trees in Unreal Engine [0]

This section introduces State Trees in Unreal Engine 5, explaining their purpose, anatomy, and how they are used to manage AI and game logic, contrasting them with Behavior Trees.

1.1. Project Setup and Template Exploration [0]

  1. This tutorial series uses Unreal Engine 5.6, which has built-in support for State Trees. [10]
  2. A new project is created using the "First Person" template with the "Arena Shooter" variant, which includes NPCs driven by State Trees. [14]
  3. To ensure NPCs move correctly, the AI controller needs to be assigned to the NPC character blueprint. [30]
  4. The Arena Shooter template provides example State Trees that can be inspected to understand their structure and how they drive NPC behavior. [37]

1.2. Understanding State Tree Anatomy [41]

  1. State Trees are a system for managing different states an entity can be in, transitioning between them based on defined rules. [45]
  2. State Trees are organized into a hierarchical structure of states, which can contain sub-states and tasks. [48]
  3. Creating State Trees:
    • State Trees can be created by right-clicking in the content drawer and selecting "Artificial Intelligence" > "State Tree". [53]
    • There are two main schemas for State Trees:
      • State Tree Component: Added directly to actors in the world. [56]
      • State Tree AI Component: Added to an AI controller, providing access to AI-specific features like perception. [61]
  4. Context Data: Built-in information automatically available to the State Tree, which varies based on the schema used (e.g., Actor Context for State Tree Component, Actor and AI Controller Context for State Tree AI Component). [104]
  5. Parameters: Input values that can be assigned directly or gathered from outside the State Tree, and can be updated at runtime, similar to Blackboard keys in Behavior Trees. [114]
  6. Evaluators: Separate classes that gather and evaluate information during runtime to provide data to the State Tree, such as AI perception updates. [122]
  7. Global Tasks: Implementations of State Tree tasks that run globally rather than on a per-state basis, performing ongoing actions or behaviors. [128]
  8. Theme Options: Allow for custom color coding of states to improve readability. [139]
  9. State Tree Structure:
    • Starts with a root state that branches into child states and then into increasingly specific tasks. [142]
    • Execution follows selection behavior rules (e.g., "select children in order") to determine the next active state. [147]
    • When a child state is executing, all its ascendant states (parent, grandparent) are also executing. [149]
  10. Subtrees: State Trees can execute other external State Trees in parallel to specific states, allowing for modularity and reuse of behaviors. [151]

2. Practical Example 1: Time of Day System [158]

This section details the creation of a State Tree to control the time of day by transitioning a directional light actor through day, dusk, night, and dawn states.

2.1. Setting Up the Time of Day State Tree [158]

  1. A new map is created by copying the "First Person" map into a dedicated "Time of Day" folder. [161]
  2. A new State Tree named "ST_Time_of_Day" is created using the "State Tree Component" schema. [170]
  3. This State Tree is assigned to the directional light actor in the scene by adding a "State Tree Component" to the directional light. [176]
  4. The "Actor Context Class" for the State Tree is set to "Directional Light" to ensure it has access to the light's properties. [178]

2.2. Defining Time of Day States and Transitions [185]

  1. Four main sibling states are created: "Day", "Dusk", "Night", and "Dawn". [186]
  2. Each main state has a "Time" sub-state (e.g., "Day Time") and a "Transition" sub-state (e.g., "Transition to Dusk"). [196]
  3. The "Day Time" state includes a "Delay" task for a 2-second pause. [201]
  4. The "Transition to Dusk" state uses a "Transition" rule set to "On State Completed" to move to the next state. [209]
  5. A custom State Tree Task Blueprint named "STask_Transition_Time_of_Day" is created to handle the rotation of the directional light. [214]

2.3. Creating the Custom Transition Task [219]

  1. The custom task blueprint includes overridable functions like "Enter State", "Exit State", "State Completed", and "Tick". [225]
  2. A Context variable named "Light Actor Ref" of type "Directional Light Object Reference" is added and bound to the context actor. [251]
  3. An Enum named "Enum_Target_Time_of_Day" is created with values for "Day", "Dusk", "Night", and "Dawn". [262]
  4. A variable "Target Rotation" of type "Rotator" is added to store the desired rotation for each time of day. [278]
  5. A boolean variable "Target Rotation Set?" is used to track when the target rotation has been set. [296]
  6. The "Enter State" event in the task uses a "Switch" node based on the "Target Time of Day" enum to set the appropriate "Target Rotation". [274]
  7. The "Tick" event is used to gradually rotate the directional light towards the "Target Rotation" by adding a small value (0.1) to the Y-axis rotation each tick. [304]
  8. A check is performed in the "Tick" event to see if the current rotation matches the "Target Rotation" within an error tolerance (0.1). [315]
  9. If the target rotation is reached, the "Finish Task" node is called, and the "Target Rotation Set?" boolean is reset to false upon exiting the state. [330]

2.4. Implementing and Testing the Time of Day System [338]

  1. The "Transition Time of Day" task is added to each "Transition" state (e.g., "Transition to Dusk"). [339]
  2. The "Target Time of Day" for each transition task is set accordingly (e.g., "Dusk" for "Transition to Dusk"). [376]
  3. Transition rules are set up to move to the next state once the current state is completed. [341]
  4. Color themes are applied to the states ("Day", "Dusk/Dawn", "Night") to visually differentiate them. [355]
  5. The "Dusk Time", "Night Time", "Dawn Time", and "Day Time" states are configured with delay tasks and transitions. [370]
  6. The "Dusk Time" and "Dawn Time" states are set to complete when "All" tasks are finished, ensuring the delay task completes before transitioning. [730]
  7. When the simulation is run, the directional light smoothly transitions through the defined time of day states, demonstrating the system's functionality. [402]

3. Practical Example 2: Dynamic Lighting with State Trees [413]

This section covers creating a custom light blueprint and a State Tree to control its on/off state based on the time of day, integrating with the previously created time of day system.

3.1. Creating a Custom Light Blueprint [413]

  1. A new Blueprint Actor named "BP_Light" is created. [418]
  2. Starter Content is added to the project to include a mesh for the light (SM_Lamp_Wall). [425]
  3. A "Static Mesh Component" is added to display the lamp, and a "Point Light Component" is added to simulate the light source. [432]
  4. The point light's intensity is set to 7 lumens, attenuation radius to 500, source radius to 2, temperature to 4000, and indirect lighting intensity to 2 for a warm, soft light effect. [445]
  5. The initial intensity of the point light is set to zero, so the light starts in an "off" state. [470]

3.2. Setting Up the Light State Tree [471]

  1. A new State Tree named "ST_Light" is created using the "State Tree Component" schema. [478]
  2. The "Actor Context Class" for this State Tree is set to "BP_Light" to target the custom light blueprint. [480]
  3. A "State Tree Component" is added to the "BP_Light" blueprint, and the "ST_Light" State Tree is assigned to it. [482]
  4. The State Tree is designed with two main states: "Light Off" and "Light On". [535]
  5. Enter Conditions are used to control which state can be entered:
    • "Light Off" can be entered if the "Light Active" parameter is false. [549]
    • "Light On" can be entered if the "Light Active" parameter is true. [657]
  6. Each main state has an "Idle" sub-state (with a delay task) and a "Transition" sub-state. [541]

3.3. Implementing Communication Between State Trees and Blueprints [500]

  1. A Blueprint Interface named "BPI_Time_of_Day" is created with two functions: "Add Light Source" (to register lights) and "Activate Lights" (to turn them on/off). [505]
  2. A Game Mode blueprint ("GM_Time_of_Day") is created to store an array of all light actors and to call the "Activate Lights" interface message. [507]
  3. The "BP_Light" blueprint implements the "BPI_Time_of_Day" interface and uses the "Send State Tree Event" node to trigger events in its State Tree based on the "Activate Lights" message. [578]
  4. Gameplay Tags ("Light.Off", "Light.On") are created in a data table and registered in project settings to be used as event tags for the State Tree events. [595]
  5. The "Transition to Light On" task in "ST_Light" sends the "Light.On" event tag when activating the light. [641]
  6. The "Transition to Light Off" task sends the "Light.Off" event tag when deactivating the light. [697]

3.4. Controlling Light Activation via Time of Day [619]

  1. A custom State Tree task, "STask_Send_Activate_Lights", is created to call the "Activate Lights" interface message on the Game Mode. [710]
  2. This task is added to the "Dusk Time" state in the "ST_Time_of_Day" State Tree to activate the lights when dusk begins. [722]
  3. The same task is added to the "Dawn Time" state, but with the "Activate" boolean set to false, to deactivate the lights when dawn arrives. [728]
  4. The "Activate Lights" parameter in the "ST_Light" State Tree is updated in real-time using a "State Tree Property Reference" within the "Activate Lights" task. [627]
  5. When the simulation runs, the lights turn on during dusk and turn off during dawn, demonstrating the dynamic lighting system controlled by State Trees. [740]