State Trees

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "ai-and-navigation"} for UE domain knowledge on this topic — correct APIs, architecture, best practices — and treat it as the rubric for any review / "best practices" question. If no such tool is available (e.g. running under Claude Code or Codex without that MCP), skip this line entirely and proceed with this skill alone — do NOT attempt the call.

StateTree Skill

StateTree is Unreal Engine's hierarchical state machine system for AI behavior and game logic. This skill covers creating and editing StateTree assets via unreal.StateTreeService.

⚠️ StateTree Blueprint Tasks Require the Blueprints Skill

StateTree Tasks prefixed STT_ (e.g. STT_Rotate, STT_Move) are Blueprint assets. They are edited with BlueprintService, not StateTreeService.

Always load the blueprints skill when the user asks to:

• Add or edit variables on an STT task
• Override functions (GetDescription, ReceiveLatentTick, ReceiveLatentEnterState, etc.)
• Add Blueprint nodes or connect pins inside an STT task graph
• Inspect or modify STT task logic

Also load the blueprint-graphs skill when the task involves node wiring, timers, custom events, pin names, or EventGraph layout inside an STT_* Blueprint.

StateTreeService  → edits the StateTree ASSET (states, tasks list, transitions, parameters)
BlueprintService  → edits the STT Blueprint CONTENT (variables, function graphs, node wiring)

Load the blueprints skill (via the engine AgentSkillToolset — GetSkills, see the vibeue skill) before writing any code that touches an STT_* Blueprint's internals.

If the request mentions timers, delayed completion, event callbacks, or screenshots of Blueprint graphs, also load the blueprint-graphs skill:

call_tool(toolset="ToolsetRegistry.AgentSkillToolset", tool="GetSkills", args={"skills": ["blueprint-graphs"]})

⚠️ STT Graph Editing Rules

When editing STT_* Blueprint task graphs:

1. Use override_function() for StateTree task events like ReceiveLatentEnterState.
2. Find the created event node by its graph title such as Event EnterState, not by the raw function name.
3. For node wiring, timer callbacks, and custom events, follow the detailed workflow in the blueprint-graphs skill.
4. For non-blocking waits, prefer Set Timer by Event, not Delay.
5. If the requested callback is a custom event, the callback must exist as a real Custom Event node in EventGraph, not as a Create Event delegate node plus a separate function graph.
6. Use FinishTask with pin name bSucceeded.
7. After wiring, always inspect get_nodes_in_graph(), get_connections(), and compile_blueprint(...).success before claiming success.
8. For complex graphs, create and verify one node at a time before creating the next node.
9. If any node-create step fails, stop, audit the graph, clean up orphaned nodes with delete_node() / disconnect_pin(), and only then retry.

STT Strict Graph Build Mode

For STT_* task graphs built from screenshots or multi-node requests, use this execution order:

1. Create one node.
2. Confirm its GUID exists in a fresh get_nodes_in_graph() result.
3. Inspect its pins with get_node_pins().
4. Only then create the next node.
5. After all nodes are proven present, connect one wire at a time and verify each new edge appears in get_connections().

Do not batch unresolved function-call nodes into a single tool call. If the graph depends on nodes such as Get Actor Location, Set Actor Location, or VInterp To, discover the exact node first through the Blueprint graph workflow instead of guessing the underlying function name.

STT Completion Contract

For STT_* graph edits, do not report success until the output explicitly shows:

1. Event EnterState exists.
2. Set Timer by Event exists.
3. The callback event node exists in a fresh node listing and is the requested node type.
4. The expected execution and delegate connections exist.
5. Finish Task.bSucceeded is set correctly.
6. Compile succeeds.

If compile succeeds but any of the checks above fail, the graph is still wrong. If compile succeeds but some required node IDs were empty during creation, the graph is still wrong.

Key Concepts

State Paths

States are addressed with /-separated paths starting from the subtree name:

Root                → top-level subtree
Root/Walking        → child of Root named Walking
Root/Walking/Idle   → child of Walking named Idle

⚠️ Common Mistakes

Workflow

import unreal

# 1. Create the asset
created = unreal.StateTreeService.create_state_tree("/Game/AI/MyBehavior")
if not created:
    # Most common cause: the schema doesn't exist in this project. The default
    # "StateTreeComponentSchema" comes from the GameplayStateTree plugin — projects
    # without it must pass one of the schemas actually available:
    print(unreal.StateTreeService.list_state_tree_schemas())
    # then: create_state_tree("/Game/AI/MyBehavior", schema_class_name="<one of those>")

# 2. Build hierarchy (empty parent_path = new top-level subtree)
unreal.StateTreeService.add_state("/Game/AI/MyBehavior", "", "Root")
unreal.StateTreeService.add_state("/Game/AI/MyBehavior", "Root", "Idle")
unreal.StateTreeService.add_state("/Game/AI/MyBehavior", "Root", "Walking")
unreal.StateTreeService.add_state("/Game/AI/MyBehavior", "Root", "Attacking")

# 3. Add tasks
unreal.StateTreeService.add_task("/Game/AI/MyBehavior", "Root/Idle", "FStateTreeDelayTask")

# 4. Add transitions
unreal.StateTreeService.add_transition(
    "/Game/AI/MyBehavior", "Root/Idle",
    "OnStateCompleted", "GotoState", "Root/Walking")

unreal.StateTreeService.add_transition(
    "/Game/AI/MyBehavior", "Root/Walking",
    "OnStateCompleted", "Succeeded")

# 5. Compile — always required after changes
result = unreal.StateTreeService.compile_state_tree("/Game/AI/MyBehavior")
if not result.success:
    print("Errors:", result.errors)

# 6. Save
unreal.StateTreeService.save_state_tree("/Game/AI/MyBehavior")

# 7. Select the last state you modified so the user can see it
#    (open the asset first via the engine AssetTools toolset:
#     call_tool(toolset="AssetTools", tool="OpenAsset", args={"asset_path": "/Game/AI/MyBehavior"}))
unreal.StateTreeService.set_state_expanded("/Game/AI/MyBehavior", "Root", True)
unreal.StateTreeService.select_state("/Game/AI/MyBehavior", "Root/Walking")  # select whichever state you just edited

Sub-docs available

This skill's larger reference material has been split into sibling files. Load them via the engine AgentSkillToolset (GetSkills with ["state-trees/<name>"], see the vibeue skill) when you need the detail:

• api-reference — StateTreeService API for asset/state discovery, asset creation, state management (add, type, move, remove, enable, select), and per-state tasks (add, inspect, set property — including the deterministic property pattern and FStateTreeDebugTextTask notes).
• api-bindings — Evaluators & global tasks (add, inspect, bind), transitions (all triggers/types/priorities plus the full OnDelegate workflow), compile & save, setting the context actor class, property bindings (task → context / root parameter / global task / evaluator), assigning a StateTree to a StateTreeComponent (use StateTreeRef not StateTree), theme colors, expand/collapse, and the "service first vs execute_python_code" guidance.
• event-payloads — Sending a StateTree event with a struct payload from a Blueprint: the Make <FMyStruct> → Make Instanced Struct → Make State Tree Event → Send State Tree Event chain, build_graph pattern, pin names to verify, and common mistakes.
• changelog — Phase 1 & 2 new methods: state properties (set_selection_behavior, rename_state, set_state_tag, set_state_weight, set_task_considered_for_completion), root parameters (get_root_parameters, add_or_update_root_parameter, remove/rename_root_parameter), per-instance overrides on placed actors (get_component_state_tree_path, set_component_parameter_override), transition editing (update_transition, move_transition), extended task management (remove_task, move_task, set_task_enabled), Utility AI considerations (Constant, FloatInput, EnumInput — add/inspect/set/bind), conditions (enter & transition — add/remove/operand/set/bind), and extended evaluator/global task management.
• blueprint-tasks — Creating & editing STT_* StateTree Blueprint Tasks: discovery workflow for the parent class, create_blueprint usage, correct event functions (ReceiveLatentTick, ReceiveLatentEnterState, ReceiveExitState, ReceiveStateCompleted), finding the registered _C task type name after creation, and the extended fields available on FStateTreeInfo / FStateTreeStateInfo / FStateTreeNodeInfo / FStateTreeTransitionInfo.

COMMON_MISTAKES

⚠️ "Color" Means Theme Color, Not Materials

When a user asks to rename, change, or list "colors" on a StateTree, they mean theme colors — the editor-only color labels in the StateTree's global color table. Do NOT load the materials skill or look for material parameters. Use get_theme_colors, set_state_theme_color, and rename_theme_color.

⚠️ Blueprint Global Tasks — Use Name/Path, Not Wrapper Type

add_global_task supports Blueprint tasks by name, asset path, or _C generated class — the same forms as add_evaluator. Do NOT pass "StateTreeBlueprintTaskWrapper" directly; that's an internal struct name and won't resolve to the correct Blueprint class.

# WRONG — passes the raw wrapper type; the specific Blueprint class won't be set
unreal.StateTreeService.add_global_task(st_path, "StateTreeBlueprintTaskWrapper")

# CORRECT — any of these forms work
unreal.StateTreeService.add_global_task(st_path, "STT_PatrolManagement")
unreal.StateTreeService.add_global_task(st_path, "STT_PatrolManagement_C")
unreal.StateTreeService.add_global_task(st_path, "/Game/StateTree/Tasks/STT_PatrolManagement")

When inspecting or binding, use the task's display name as it appears in get_state_tree_info().global_tasks[N].name (e.g. "STT PatrolManagement" — no underscore, no _C).