StateTree

63 tools. Back to the index.

add_consideration

Additive, idempotent.

Attach a utility-AI consideration (any struct deriving from FStateTreeConsiderationBase) to a state's Considerations array on a UStateTree. Considerations rank selectable children by score (0..1) when the state's selection behavior is utility-driven (e.g. TrySelectChildrenWithHighestUtility). Friendlier aliases are accepted in addition to the full struct name: "Constant" -> StateTreeConstantConsideration, "FloatInput"/"Float Input" -> StateTreeFloatInputConsideration, "EnumInput"/"Enum Input" -> StateTreeEnumInputConsideration. Use set_consideration_property to set initial values like Constant.Constant or FloatInput.Input. Idempotent: re-adding the same struct-type appends another consideration (engine semantics; considerations of the same type are valid).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the UStateTree
state_name	string	yes	Name of the state to attach the consideration to
consideration_class	string	yes	Struct name (FStateTreeConstantConsideration / StateTreeConstantConsideration) or alias (Constant|FloatInput|Enum Input|...)

Returns: { tree_path, state_name, consideration_class, consideration_count, added, saved }

add_state

Additive, idempotent.

Add a top-level state (a new SubTree, never a child of another state) to a StateTree asset, then compile and save it. Idempotent: if any state already has that name nothing changes and already_existed is true. Returns state_count, added and saved.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the new state, e.g. "Patrol"; the other state commands find states by this name.

Returns: { tree_path, state_name, state_count, already_existed, added, saved }

add_state_enter_condition

Additive.

Attach an enter-condition node (by struct name, resolved via reflection) to a state's EnterConditions on a UStateTree.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
state_name	string	yes	Name of the state to add the enter condition to
condition_struct	string	yes	Condition struct name or /Script path; must derive from StateTreeConditionBase (e.g. "StateTreeRandomCondition")

Returns: { tree_path, state_name, condition_struct, enter_condition_count, added, saved }

add_state_evaluator

Additive, idempotent.

Attach an evaluator node (by struct name, via reflection) to a UStateTree; evaluators are TREE-scoped (they live on UStateTreeEditorData::Evaluators, not on a state) and tick for the whole tree, so this command takes no state_name. Idempotent: an evaluator of the same struct already present is not appended again.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
evaluator_class	string	yes	Evaluator struct name or /Script path; must derive from StateTreeEvaluatorBase (e.g. "TestEval_A" from the StateTree test suite, or any project/plugin evaluator struct).

Returns: { tree_path, evaluator_class, evaluator_count, already_existed, added, saved }

add_state_task

Additive.

Attach a task node (by struct name, resolved via reflection) to a state's Tasks list on a UStateTree.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
state_name	string	yes	Name of the state to add the task to
task_struct	string	yes	Task struct name or /Script path; must derive from StateTreeTaskBase (e.g. "StateTreeDebugTextTask")

Returns: { tree_path, state_name, task_struct, task_count, added, saved }

add_state_transition

Additive.

Append a transition from from_state to to_state on a StateTree asset (trigger OnStateCompleted, type GotoState), then compile and save it; each call adds another one. event_name only fills RequiredEvent, which matters with an OnEvent trigger: set that with set_transition_properties. Returns transition_count and saved.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
from_state	string	yes	Name of the source state, which owns the new transition.
to_state	string	yes	Name of the target state the transition goes to.
event_name	string	no	Gameplay tag stored as the transition RequiredEvent, e.g. "AI.Event.Alert"; a tag that is not registered is ignored without error.

Returns: { tree_path, from_state, to_state, event_name, transition_count, added, saved }

add_state_tree_binding

Destructive, idempotent.

Bind a UStateTree root parameter (source) to a target node's input property (target), so the node reads the parameter at runtime. The target defaults to a state Task, but target_kind selects any FStateTreeEditorNode list: enter_condition/consideration (on the state) or global_task/evaluator (on the tree) — the binding anchor (FStateTreeEditorNode::ID) is identical for every kind. Authors an FStateTreePropertyPathBinding in the editor data's property bindings (idempotent per target path — re-binding the same target replaces it); validate it resolves with compile_state_tree.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
target_property	string	yes	Name of the target node's input property to bind (the binding target), e.g. "BindableText".
source_parameter	string	yes	Name of the root parameter to bind from (the binding source; add it with add_tree_parameter first).
state_name	string	no	Name of the state owning the target node (required for target_kind task|enter_condition|consideration; ignored for global_task|evaluator, which live on the tree).
target_kind	string	no	Which node list holds the target: "task" (default) | "enter_condition" | "consideration" | "global_task" | "evaluator".
target_index	number	no	Optional index into the selected node list (default 0).

Returns: { tree_path: string, state_name: string?, target_kind: string, target_index: int, target_property: string, source_parameter: string, source_struct_id: string, target_struct_id: string, bound: bool, binding_count: int, saved: bool }

add_state_tree_global_task

Additive.

Attach a global task node (by struct name, via reflection) to a UStateTree; global tasks run for the whole tree's lifetime.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
task_struct	string	yes	Task struct name or /Script path; must derive from StateTreeTaskBase (e.g. "StateTreeDebugTextTask")

Returns: { tree_path, task_struct, global_task_count, added, saved }

add_state_tree_global_task_property

Additive.

Write one property of an existing global task of a StateTree asset by reflection and save the asset; despite the name it adds nothing (create the task with add_state_tree_global_task). Only node struct properties are reachable, not instance data. Returns value_changed, new_value and saved.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
global_task_index	number	yes	0-based index into the tree GlobalTasks, as listed by list_global_tasks; out of range is an error.
property	string	yes	Name of a property on the global task node struct, e.g. "FontScale" on a debug text task; case-insensitive.
value	any	yes	New value as JSON: a number, bool or string, or an object for a struct property, applied through FJsonObjectConverter.

Returns: { tree_path, global_task_index, property, set, value_changed, saved }

add_transition_condition

Additive.

Attach a condition node (by struct name, via reflection) to a transition on a state of a UStateTree.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
state_name	string	yes	Name of the state owning the transition
condition_struct	string	yes	Condition struct name or /Script path; must derive from StateTreeConditionBase (e.g. "StateTreeRandomCondition")
transition_index	number	no	Index of the transition within the state (from get_state_tree_info)

Returns: { tree_path, state_name, transition_index, condition_struct, condition_count, added, saved }

add_tree_parameter

Additive.

Add a typed parameter to a UStateTree's root parameter bag (usable for bindings).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
parameter_name	string	yes	Name of the parameter to add
parameter_type	string	no	Scalar type: bool, int (default), int64, float, double, name, string, text, byte

Returns: { tree_path, parameter_name, parameter_type, parameter_count, added, saved }

compile_state_tree

Destructive.

Compile a UStateTree via the editor subsystem (validate + compile); reports success and error/warning counts.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree

Returns: { tree_path, compiled, error_count, warning_count, message_count, saved }

create_state_tree

Additive.

Create a StateTree asset at package_path/tree_name (or load the one already there), giving it any missing editor data, the plugin UMCPStateTreeSchema when it has no schema and a Root state when it has no states, then compile and save it. Returns tree_path, state_count, created and saved.

Parameter	Type	Required	Description
tree_name	string	yes	Asset name without path, e.g. "ST_Guard"; an asset of another class with that name is an error.
package_path	string	no	Content folder for the asset, e.g. "/Game/AI" (default /Game/MCP).

Returns: { tree_path, tree_name, state_count, created, saved }

delete_state_tree

Destructive, idempotent.

Delete a UStateTree asset from the project. Idempotent — deleting a non-existent asset is a no-op (returns deleted:false, already_existed:false) so re-runs don't fail.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
confirm	boolean	no	Must be true to actually delete. Honest-headless safety against accidental wipe.

Returns: { tree_path, deleted, already_existed, note }

get_component_state_tree_path

Read-only.

Resolve a UStateTreeComponent on a placed actor and return the bound asset path (read-only).

Parameter	Type	Required	Description
actor_label	string	yes	Actor label/name to inspect

Returns: { actor_label, has_state_tree_component, state_tree_path }

get_condition_info

Read-only.

Dump one condition node of a StateTree state as JSON without changing the asset: an enter condition of the state or, with target_kind "transition", a condition of one of its transitions. Returns class, instance_id and properties, the node struct fields (instance data is not included).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the condition; the command fails without it.
condition_index	number	yes	0-based index into the selected condition list, as counted by list_conditions or list_transitions.
target_kind	string	no	Which list to read: "state" (default, the state EnterConditions) or "transition" (the Conditions of transition transition_index); any other value reads the enter conditions.
transition_index	number	no	0-based index into the state transitions; required when target_kind is "transition" and ignored otherwise.

Returns: { tree_path, state_name, target_kind, transition_index, condition_index, class, instance_id, properties: {...} }

get_condition_property

Read-only.

Read one property of a condition node on a StateTree state by reflection, without changing the asset: an enter condition, or a transition condition with target_kind "transition". Returns the value as JSON with its C++ type and has_value; only node struct properties are reachable, not instance data.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the condition; the command fails without it.
property	string	yes	Name of a property on the condition node struct, e.g. "bInvert" on a compare condition; case-insensitive.
target_kind	string	no	Which list holds the condition: "state" (default, EnterConditions) or "transition" (Conditions of transition transition_index); any other value means "state".
condition_index	number	no	0-based index into the selected condition list; omitting it fails as out of range.
transition_index	number	no	0-based index into the state transitions; used only when target_kind is "transition", where omitting it fails.

Returns: { tree_path, state_name, target_kind, transition_index, condition_index, property, type, value, has_value }

get_consideration_info

Read-only.

Serialize a single consideration's instance data (FJsonObjectConverter over the consideration struct) for inspection.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
consideration_index	number	yes	0-based index into State->Considerations.

Returns: { tree_path, state_name, consideration_index, class, instance_id, properties: {...} }

get_consideration_property

Read-only.

Read one property of a consideration node on a StateTree state by reflection, without changing the asset. Returns the value as JSON with its C++ type and has_value; only node struct properties are reachable, not instance data. Find the index with list_considerations.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the consideration; the command fails without it.
consideration_index	number	yes	0-based index into the state Considerations, as listed by list_considerations.
property	string	yes	Name of a property on the consideration node struct; case-insensitive.

Returns: { tree_path, state_name, consideration_index, property, type, value, has_value }

get_evaluator_info

Read-only.

Dump one tree-scoped evaluator of a StateTree asset as JSON without changing it. Returns evaluator_index, class, instance_id and properties, the node struct fields (instance data is not included). Find the index with list_evaluators.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
evaluator_index	number	yes	0-based index into the tree Evaluators, as listed by list_evaluators; out of range is an error.

Returns: { tree_path, evaluator_index, class, instance_id, properties: {...} }

get_evaluator_property

Read-only.

Read one property of a tree-scoped evaluator node of a StateTree asset by reflection, without changing it. Returns the value as JSON with its C++ type and has_value; only node struct properties are reachable, not instance data. Write it with set_evaluator_property.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
property	string	yes	Name of a property on the evaluator node struct, e.g. "Name"; case-insensitive.
evaluator_index	number	no	0-based index into the tree Evaluators, as listed by list_evaluators; omitting it fails as out of range.

Returns: { tree_path, evaluator_index, property, type, value, has_value }

get_state_theme_colors

Read-only.

List the theme color palette of a StateTree asset (UStateTreeEditorData Colors) without changing it. Returns count and colors [{display_name, color_ref, r, g, b, a}], color_ref being the GUID that states point to. Takes state_tree_path, not tree_path; set colors with set_state_theme_color.

Parameter	Type	Required	Description
state_tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard"; named state_tree_path here, unlike its sibling tools.

Returns: { count, colors: [{display_name, color_ref, r, g, b, a}] }

get_state_tree_info

Read-only.

Read a StateTree asset without changing it: every state with its type, selection behavior and task, enter-condition, child and transition counts, every transition with trigger, priority, event tag and delay, the root parameters, root_state and evaluator, global task and binding counts.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".

Returns: { name, transitions, children, from_state, to_state, trigger, event_tag, type, tree_path, state_count, states, transition_count, parameter_count, parameters, root_state }

get_task_info

Read-only.

Read one task of a named state in a StateTree asset without changing it: the task node's struct name (class), its instance_id and every property of the node struct as JSON (properties). The task's instance data is not included. Errors when the tree, its editor data or the state is missing, or task_index is out of range; state_name picks the first state with that name. List a state's tasks with list_tasks; read or write one field with get_task_property or set_task_property; global tasks: list_global_tasks.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
task_index	number	yes	0-based index into State->Tasks.

Returns: { tree_path, state_name, task_index, class, instance_id, properties: {...} }

get_task_property

Read-only.

Read one property of a task node on a StateTree state by reflection, without changing the asset. Returns the value as JSON with its C++ type and has_value; only node struct properties are reachable, not instance data. Use get_task_info for the whole node and set_task_property to write.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the task; the command fails without it.
task_index	number	yes	0-based index into the state Tasks, as listed by list_tasks.
property	string	yes	Name of a property on the task node struct, e.g. "FontScale" on a debug text task; case-insensitive.

Returns: { tree_path, state_name, task_index, property, type, value, has_value }

list_condition_types

Read-only.

List the concrete condition struct types (children of FStateTreeConditionBase, abstract ones skipped) of the loaded modules, sorted by name, for add_state_enter_condition and add_transition_condition. Returns count and types [{name, struct_path}]; struct_path always assumes /Script/StateTreeModule, so pass name for other modules.

No parameters.

Returns: { count, types: [{ name, struct_path }] }

list_conditions

Read-only.

List the enter conditions of a state. (Transition-level conditions are exposed via list_transitions' condition_count; a full per-transition dump is not available yet.)

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.

Returns: { tree_path, state_name, count, conditions: [{ index, class, instance_id }] }

list_considerations

Read-only.

List all considerations of a state, with their struct class name and instance ID.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.

Returns: { tree_path, state_name, count, considerations: [{ index, class, instance_id }] }

list_evaluator_types

Read-only.

List the concrete evaluator struct types (children of FStateTreeEvaluatorBase, abstract ones skipped) of the loaded modules, sorted by name, for add_state_evaluator. Returns count and types [{name, struct_path}]; struct_path always assumes /Script/StateTreeModule, so pass name for other modules.

No parameters.

Returns: { count, types: [{ name, struct_path }] }

list_evaluators

Read-only.

List all evaluators on the tree (UStateTreeEditorData::Evaluators — tree-scoped).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.

Returns: { tree_path, count, evaluators: [{ index, class, instance_id }] }

list_global_tasks

Read-only.

List the global tasks of a StateTree asset (tasks that run for the whole tree, not one state) without changing it. Returns count and global_tasks [{index, class, instance_id}]; index is what add_state_tree_global_task_property and remove_state_tree_global_task take.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".

Returns: { tree_path, count, global_tasks: [{ index, class, instance_id }] }

list_state_trees

Read-only.

List all UStateTree assets under a content path (default /Game).

Parameter	Type	Required	Description
package_path	string	no	Content path to filter on (default "/Game").

Returns: { package_path, count, trees: [{ path, name, class }] }

list_states

Read-only.

Walk the state hierarchy of a UStateTree, returning a flat list with parent/child/sibling info plus a recursive child_count.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
root_state	string	yes	Optional. If set, walk from this state as root (top-level SubTrees are skipped).

Returns: { tree_path, count, states: [{ name, type, completion, has_children, child_count, depth, parent }] }

list_task_types

Read-only.

Enumerate all concrete UScriptStructs deriving from FStateTreeTaskBase (instantiable, RF_Abstract excluded), via TObjectIterator<UScriptStruct>.

No parameters.

Returns: { count, types: [{ name, struct_path }] }

list_tasks

Read-only.

List all tasks of a state, with their struct class name, instance ID, and per-task condition count.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.

Returns: { tree_path, state_name, count, tasks: [{ index, class, instance_id, condition_count }] }

list_transitions

Read-only.

List all transitions of a state, with their target name, trigger event, conditions count, delay, and priority.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.

Returns: { tree_path, state_name, count, transitions: [{ index, target, trigger, condition_count, delay, priority }] }

list_tree_bindings

Read-only.

List the property bindings stored in the editor data of a StateTree asset, without changing it. Returns count and bindings [{index, source_path, target_path, source_id, target_id}], where source_id and target_id are the struct GUIDs of the two ends. Add bindings with add_state_tree_binding and remove them with remove_tree_binding.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".

Returns: { tree_path, count, bindings: [{ index, source_path, target_path, source_id, target_id }] }

list_tree_parameters

Read-only.

List the root parameter bag (typed parameters declared on the tree).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.

Returns: { tree_path, count, parameters: [{ name, type, value_type }] }

remove_consideration

Destructive, idempotent.

Remove a consideration (by index) from a state. Idempotent at the index-out-of-range boundary.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
consideration_index	number	yes	0-based index into the state's Considerations array.

Returns: { tree_path, state_name, consideration_index, removed, remaining, saved }

remove_evaluator

Destructive, idempotent.

Remove a tree-scoped evaluator (by index). Idempotent at the index-out-of-range boundary.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
evaluator_index	number	yes	0-based index into the tree's Evaluators array.

Returns: { tree_path, evaluator_index, removed, remaining, saved }

remove_state

Destructive, idempotent.

Remove a state from the tree by name. Idempotent: removing a non-existent state returns removed:false with a note.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state to remove.
with_descendants	boolean	no	When true (default), also removes all child states recursively.

Returns: { tree_path, state_name, removed, with_descendants, remaining_top_level, note }

remove_state_enter_condition

Destructive.

Remove one enter condition, by index, from a state of a StateTree asset and save the asset. An out-of-range index removes nothing and still succeeds, with removed false and a note. Returns removed, remaining and saved; for transition conditions use remove_transition_condition.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the condition; the command fails without it.
condition_index	number	yes	0-based index into the state EnterConditions, as listed by list_conditions.

Returns: { tree_path, state_name, condition_index, removed, remaining, saved, note }

remove_state_tree_global_task

Destructive, idempotent.

Remove a tree-scoped global task (by index). Idempotent at the index-out-of-range boundary.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
global_task_index	number	yes	0-based index into the tree's GlobalTasks array.

Returns: { tree_path, global_task_index, removed, remaining, saved }

remove_task

Destructive, idempotent.

Remove a task (by index) from a state. Idempotent at the index-out-of-range boundary.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
task_index	number	yes	0-based index into the state's Tasks array.

Returns: { tree_path, state_name, task_index, removed, remaining, saved }

remove_transition

Destructive, idempotent.

Remove a transition (by index) from a state. Idempotent at the index-out-of-range boundary.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
transition_index	number	yes	0-based index into the state's Transitions array.

Returns: { tree_path, state_name, transition_index, removed, remaining, saved }

remove_transition_condition

Destructive.

Remove one condition, by index, from a transition of a StateTree state and save the asset. An out-of-range transition_index is an error; an out-of-range condition_index removes nothing and still succeeds, with removed false. Returns removed, remaining and saved.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the transition; the command fails without it.
transition_index	number	yes	0-based index into the state transitions, as listed by list_transitions.
condition_index	number	yes	0-based index into the Conditions of that transition.

Returns: { tree_path, state_name, transition_index, condition_index, removed, remaining, saved, note }

remove_tree_binding

Destructive.

Remove the property binding whose target is target_property on one node of a StateTree asset (and any binding to a sub-property of it), the way the StateTree editor clears a binding, then save the asset. Nothing bound there is not an error: removed is false and the asset is not saved. Returns removed, removed_count and remaining (bindings left in the tree); list them with list_tree_bindings.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
target_kind	string	yes	Node list of the binding target: "task", "condition" (a state enter condition; "enter_condition" also works), "consideration", "transition" (a transition condition), "global_task" or "evaluator".
target_property	string	yes	Property path of the binding target on that node, as list_tree_bindings shows it in target_path, e.g. "BindableText".
state_name	string	no	Name of the state that owns the target node; needed for the task, condition, consideration and transition kinds.
transition_index	number	no	0-based index into the state transitions; used only by the transition kind.
target_index	number	no	0-based index of the target node in its list, default 0; for the transition kind, the index into the Conditions of that transition.

Returns: { tree_path, target_kind, state_name?, target_index, target_property, target_struct_id, removed, removed_count, remaining, saved }

remove_tree_parameter

Destructive, idempotent.

Remove a named parameter from a UStateTree's root parameter bag. Idempotent — removing an absent parameter is a no-op (removed:false).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
parameter_name	string	yes	Name of the root parameter to remove.

Returns: { tree_path, parameter_name, removed, parameter_count, saved }

set_component_parameter_override

Destructive, idempotent.

Override a single UStateTree root parameter on a UStateTreeComponent living on a placed actor. CRITICAL: the implementation calls UStateTreeStateTreeReference::SetPropertyOverridden(ParamGuid, true) — without this, the runtime reads from the asset default and the per-instance value is silently dropped. The value is written via FInstancedPropertyBag::SetValueSerializedString so the engine parses the string into the parameter's actual type (Bool/Int/Float/Vector/Struct/...). The tree must already declare the parameter; add it with add_tree_parameter first. Use clear_overrides=true to remove the override (asset default takes over again) without writing a value. If the component has no bound tree, pass state_tree_path to auto-bind before overriding (cold-start convenience); the public UStateTreeComponent::SetStateTree(UStateTree*) handles the bind through reflection on the protected StateTreeRef member.

Parameter	Type	Required	Description
actor_label	string	yes	Actor label/name that owns the UStateTreeComponent (resolved against the editor world)
parameter_name	string	yes	Root parameter name to override (must exist on the bound tree)
value	string	yes	Optional string-encoded value; type-driven by the parameter's FPropertyBagPropertyDesc
state_tree_path	string	no	Optional path to a UStateTree to bind the component to if no tree is already bound
clear_overrides	boolean	no	If true, drop all per-instance overrides on the component (asset defaults take over); value is ignored

Returns: { actor_label, component_class, parameter_name, parameter_id, value, was_overridden, cleared, saved, bound_tree }

set_condition_property

Destructive, idempotent.

Write one property of a condition node on a StateTree state by reflection and save the asset: an enter condition, or a transition condition with target_kind "transition". Only node struct properties are reachable, not instance data. Returns value_changed, new_value and saved; the same value again gives value_changed false.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state that owns the condition; the command fails without it.
property	string	yes	Name of a property on the condition node struct, e.g. "bInvert" on a compare condition; case-insensitive.
value	any	yes	New value as JSON: a number, bool or string, or an object for a struct property, applied through FJsonObjectConverter.
target_kind	string	no	Which list holds the condition: "state" (default, EnterConditions) or "transition" (Conditions of transition transition_index); any other value means "state".
transition_index	number	no	0-based index into the state transitions; used only when target_kind is "transition", where omitting it fails.
condition_index	number	no	0-based index into the selected condition list; omitting it fails as out of range.

Returns: { tree_path, state_name, target_kind, transition_index, condition_index, property, set, value_changed, saved }

set_consideration_property

Destructive, idempotent.

Set a single field of a consideration instance by reflection (FJsonObjectConverter::JsonValueToFProperty). Idempotent — re-applying the same value is a no-op (returns set:true, value_changed:false).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
consideration_index	number	yes	0-based index into State->Considerations.
property	string	yes	FProperty name on the consideration struct.
value	any	yes	JSON value to apply (any FJsonObjectConverter-supported type).

Returns: { tree_path, state_name, consideration_index, property, set, value_changed, saved }

set_evaluator_property

Destructive, idempotent.

Write one property of a tree-scoped evaluator node of a StateTree asset by reflection and save the asset. Only node struct properties are reachable, not instance data. Returns value_changed, new_value and saved; the same value again gives value_changed false. Read it back with get_evaluator_property.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
evaluator_index	number	yes	0-based index into the tree Evaluators, as listed by list_evaluators; out of range is an error.
property	string	yes	Name of a property on the evaluator node struct; case-insensitive.
value	any	yes	New value as JSON: a number, bool or string, or an object for a struct property, applied through FJsonObjectConverter.

Returns: { tree_path, evaluator_index, property, set, value_changed, saved }

set_state_completion_type

Destructive, idempotent.

Set how a state aggregates its tasks' completion (UStateTreeState::TasksCompletion). NOTE: this is the tasks-aggregation policy EStateTreeTaskCompletionType {All, Any} (All = the state completes when ALL its tasks complete; Any = when ANY single task completes) — NOT a success/failed result.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state to modify.
completion_type	string	yes	Aggregation policy: "All" (default in engine: Any) | "Any" (case-insensitive).

Returns: { tree_path, state_name, completion_type, set, saved }

set_state_linked_asset

Destructive, idempotent.

Turn a state into a LinkedAsset state pointing at another UStateTree (UStateTreeState::SetLinkedStateAsset). This forces the state's Type to EStateTreeStateType::LinkedAsset (the engine setter asserts on Type) and the setter clears Tasks, fixes the parameter layout from the linked subtree, and sets SelectionBehavior=TryEnterState — so a linked-asset state runs the target tree instead of local tasks.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the owning UStateTree.
state_name	string	yes	Name of the state to convert into a LinkedAsset state.
linked_asset_path	string	yes	Asset path to the target UStateTree to link (must exist).

Returns: { tree_path, state_name, state_type, linked_asset, set, saved }

set_state_selection_behavior

Destructive, idempotent.

Set a state's selection behavior (EStateTreeStateSelectionBehavior) on a UStateTree.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
state_name	string	yes	Name of the state to modify
selection_behavior	string	yes	One of None | TryEnterState | TrySelectChildrenInOrder | TrySelectChildrenAtRandom | ...

Returns: { tree_path, state_name, selection_behavior, set, saved }

set_state_theme_color

Destructive, idempotent.

Upsert a theme color in UStateTreeEditorData::Colors. CRITICAL: if a color with the same DisplayName (case-insensitive) already exists, its ColorRef UUID is preserved — state-level ColorRef references keep resolving, and the editor retains the original color identity in the asset's change history. Newly-created colors get a fresh UUID; the caller is responsible for re-binding any state ColorRefs that referenced an orphaned previous UUID. r/g/b default to 1.0; a defaults to 1.0. The engine stores Colors as a TSet<FStateTreeEditorColor> keyed on ColorRef (display name uniqueness is the caller's responsibility — duplicate names are allowed by the engine but produce ambiguous lookups downstream).

Parameter	Type	Required	Description
state_tree_path	string	yes	Asset path of the UStateTree
color_name	string	yes	Display name (required, case-insensitive lookup)
r	number	no	red 0..1 (default 1.0)
g	number	no	green 0..1 (default 1.0)
b	number	no	blue 0..1 (default 1.0)
a	number	no	alpha 0..1 (default 1.0)

Returns: { state_tree_path, color_name, color_ref, r, g, b, a, was_new, saved }

set_state_tree_root

Destructive, idempotent.

Make a top-level state the root of a StateTree asset by moving it to the first SubTree slot, then compile and save it. A nested state is refused. Returns root_state with set and saved, or already_root when it was already first (nothing saved).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
root_state_name	string	yes	Name of a top-level state, such as one made by add_state; a state nested under another is refused.

Returns: { tree_path, root_state, already_root, set, saved }

set_state_type

Destructive, idempotent.

Set the type of a StateTree state (EStateTreeStateType: State, Group, Linked, LinkedAsset or Subtree) and save the asset without recompiling it. An unknown name is an error. To point a state at another tree prefer set_state_linked_asset, which also sets the linked asset.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
state_name	string	yes	Name of the state to change; the command fails without it.
state_type	string	yes	Enum value name: State, Group, Linked, LinkedAsset or Subtree (an EStateTreeStateType:: prefix is accepted).

Returns: { tree_path, state_name, state_type, set, saved }

set_task_property

Destructive, idempotent.

Set a single field of a task instance by reflection (FJsonObjectConverter::JsonValueToFProperty). Idempotent — re-applying the same value is a no-op (returns set:true, value_changed:false).

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree.
state_name	string	yes	Name of the state.
task_index	number	yes	0-based index into State->Tasks.
property	string	yes	FProperty name on the task struct.
value	any	yes	JSON value to apply (any FJsonObjectConverter-supported type).

Returns: { tree_path, state_name, task_index, property, set, value_changed, saved }

set_transition_properties

Destructive, idempotent.

Set properties (trigger, priority, delay, enabled) on a transition of a state in a UStateTree.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path to the UStateTree
state_name	string	yes	Name of the state owning the transition
transition_index	number	no	Index of the transition within the state
trigger	string	no	Optional EStateTreeTransitionTrigger name (e.g. OnStateCompleted, OnTick)
priority	string	no	Optional EStateTreeTransitionPriority name (e.g. Low, Normal, High)
enabled	boolean	no	Optional whether the transition is enabled
delay	boolean	no	Optional whether to delay the transition
delay_duration	number	no	Optional delay duration in seconds (requires delay=true to take effect)

Returns: { tree_path, state_name, transition_index, trigger, priority, enabled, delay, delay_duration, saved }

set_tree_parameter

Destructive, idempotent.

Set the value of an existing root parameter of a StateTree asset and save it. Works for bool, byte, int32, int64, float, double, name, string and text parameters; array and other types return an error. Add the parameter first with add_tree_parameter. Returns value_changed, new_value and saved.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".
parameter	string	yes	Name of a root parameter that already exists, as listed by list_tree_parameters; an unknown name is an error.
value	any	yes	New value as JSON matching the parameter type: true or false, a number, or a string for name, string and text parameters.

Returns: { tree_path, parameter, set, value_changed, saved, new_value? }

update_transition

Destructive.

Update any subset of a transition's metadata fields on a state. Only fields explicitly passed are written; everything else is preserved. Unknown enum strings are rejected (no silent no-ops on bad input). Superset of set_transition_properties: adds transition_type (None|Succeeded|Failed|GotoState|Parent|NextState|...), target_state (rebind by name), event_tag (FGameplayTag, when trigger=OnEvent), and payload_struct (event-payload struct, when trigger=OnEvent). Use this when set_transition_properties doesn't expose the field you need.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the UStateTree
state_name	string	yes	State that owns the transition
transition_index	number	no	Index into the state's Transitions array (0-based)
trigger	string	no	Optional EStateTreeTransitionTrigger name (None|OnStateCompleted|OnStateTick|OnEvent|OnDelta|...)
priority	string	no	Optional EStateTreeTransitionPriority name (Lowest|Low|Normal|High|Highest)
transition_type	string	no	Optional EStateTreeTransitionType name (None|Succeeded|Failed|GotoState|Parent|NextState|NextSelectableState|NextParent|NextSelectableParent)
target_state	string	no	Optional re-target by state name (only when you want to redirect the edge)
event_tag	string	no	Optional event tag as a literal FGameplayTag string (e.g. "GameplayCue.Movement.Jumped")
payload_struct	string	no	Optional UScriptStruct name or /Script path for the event payload
enabled	boolean	no	Optional bool (defaults preserved when omitted)
delay	boolean	no	Optional bool (when true, delay_duration and delay_variance are honored by the editor)
delay_duration	number	no	Optional number (seconds)
delay_variance	number	no	Optional number (seconds of random variance)

Returns: { tree_path, state_name, transition_index, applied_fields: [string], errors: [string], saved }

validate_state_tree

Destructive.

Compile a StateTree asset in memory and report its errors and warnings without saving: valid, compiled, error_count, warning_count and the messages. It still marks the package dirty and refreshes the compiled data in memory; compile_state_tree compiles and saves.

Parameter	Type	Required	Description
tree_path	string	yes	Asset path of the StateTree, e.g. "/Game/AI/ST_Guard".

Returns: { tree_path, valid, compiled, error_count, warning_count, message_count, saved, errors: [{severity, message}], warnings: [{severity, message}], note }