BehaviorTree

27 tools. Back to the index.

add_blackboard_key

Additive.

Append a key to a UBlackboardData asset and save it.

Parameter	Type	Required	Description
blackboard_path	string	yes	Path to the UBlackboardData asset.
key_name	string	yes	New key name (must be unique on the asset).
key_type	string	yes	One of Bool|Int|Float|Vector|Rotator|String|Name|Object|Class|Enum.
instance_synced	boolean	no	Whether the key is instance-synced (optional, default false)

Returns: { blackboard_path: string, key_name: string, key_type: string, key_count: number, verified: bool, saved: bool, already_exists: bool?, save_error: string?, keys: [{ name, type, instance_synced }] }

add_bt_composite_child

Additive, idempotent.

Add a child composite (Selector/Sequence/SimpleParallel) under a BehaviorTree composite. The child is appended to the parent's Children (array order = execution order). Authoring is data-only: ParentNode/ExecutionIndex are assigned by the BT runtime at load (run_behavior_tree). Idempotent by child_name within the parent. The returned child_name is how you address this composite as a parent for further children.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset (its RootNode must already be set via set_behavior_tree_root).
composite	string	yes	Concrete composite class: "Selector" | "Sequence" | "SimpleParallel" (or a BTComposite_* class name).
parent_name	string	no	Optional parent composite name (a child_name from a prior add); "Root" or omitted targets the RootNode.
child_name	string	no	Optional stable name for the new node (its identity for idempotency/addressing); defaults to the composite type.

Returns: { behavior_tree_path: string, parent_name: string, child_name: string, child_class: string, child_kind: string, already_exists: bool, child_count: int, saved: bool, save_error?: string }

add_bt_decorator

Additive, idempotent.

Attach a decorator (execution condition) to a specific child-edge of a BehaviorTree composite. The decorator is appended to that child's Decorators array and gates whether the child may run. Authoring is data-only: ParentNode/ExecutionIndex are assigned by the BT runtime at load (run_behavior_tree). Idempotent by decorator_name within the child-edge.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset (its RootNode must already be set, with the target child added).
child_name	string	yes	Name of the existing child (a child_name from a prior add_bt_task_child/add_bt_composite_child) whose edge the decorator gates.
decorator_class	string	yes	Concrete decorator class: "Cooldown" | "Loop" | "TimeLimit" | "Blackboard" | ... (or a BTDecorator_* class name).
parent_name	string	no	Optional parent composite name owning the child-edge; "Root" or omitted targets the RootNode.
decorator_name	string	no	Optional stable name for the new decorator (its identity for idempotency); defaults to the decorator type.

Returns: { behavior_tree_path: string, parent_name: string, child_name: string, decorator_name: string, decorator_class: string, already_exists: bool, decorator_count: int, saved: bool, save_error?: string }

add_bt_service

Additive, idempotent.

Attach a service (background tick) to a BehaviorTree composite. The service is appended to the composite's Services array and ticks while that composite branch is active. Authoring is data-only: ParentNode/ExecutionIndex are assigned by the BT runtime at load (run_behavior_tree). Idempotent by service_name within the composite.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset (its RootNode must already be set via set_behavior_tree_root).
service_class	string	yes	Concrete service class: "DefaultFocus" | "RunEQS" | ... (or a BTService_* class name).
parent_name	string	no	Optional composite name to attach the service to; "Root" or omitted targets the RootNode.
service_name	string	no	Optional stable name for the new service (its identity for idempotency); defaults to the service type.

Returns: { behavior_tree_path: string, parent_name: string, service_name: string, service_class: string, already_exists: bool, service_count: int, saved: bool, save_error?: string }

add_bt_task_child

Additive, idempotent.

Add a leaf task node (Wait/MoveTo/PlaySound/RunBehavior/...) under a BehaviorTree composite. The task is appended to the parent's Children (array order = execution order). Authoring is data-only: ParentNode/ExecutionIndex are assigned by the BT runtime at load. Idempotent by child_name within the parent.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset (its RootNode must already be set via set_behavior_tree_root).
task_class	string	yes	Concrete task class: "Wait" | "MoveTo" | "PlaySound" | "RunBehavior" | "FinishWithResult" (or a BTTask_* class name).
parent_name	string	no	Optional parent composite name; "Root" or omitted targets the RootNode.
child_name	string	no	Optional stable name for the new node; defaults to the task type.

Returns: { behavior_tree_path: string, parent_name: string, child_name: string, child_class: string, child_kind: string, already_exists: bool, child_count: int, saved: bool, save_error?: string }

create_behavior_tree

Additive.

Create and save a new UBehaviorTree asset, optionally binding a blackboard.

Parameter	Type	Required	Description
name	string	yes	Asset name (e.g. "BT_Enemy").
package_path	string	no	Target /Game package path (optional, default "/Game/AI")
blackboard_path	string	no	Path to a UBlackboardData asset to bind to the new BT (optional)

Returns: { name: string, package_path: string, behavior_tree_path: string, asset_path: string, blackboard_asset: string?, already_exists: bool, saved: bool, save_error: string? }

create_blackboard_data

Additive, idempotent.

Create an empty UBlackboardData asset at package_path/name and save it; success requires the save. Idempotent: an existing blackboard there is returned with already_exists=true and is not re-saved. Returns blackboard_path and key_count; add keys with add_blackboard_key.

Parameter	Type	Required	Description
name	string	yes	Asset name (e.g. "BB_Enemy").
package_path	string	no	Target /Game package path (optional, default "/Game/AI")

Returns: { name: string, package_path: string, blackboard_path: string, asset_path: string, key_count: number, already_exists: bool, saved: bool, save_error: string? }

get_behavior_tree_info

Read-only.

Get information about a behavior tree's structure and properties

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path or name of the behavior tree to query

Returns: { behavior_tree_path: string, name: string, blackboard_asset: string|null, blackboard_keys: [{ name: string, type: string, instance_synced: bool }], root_node: object|null }

get_behavior_tree_status

Read-only.

Reader: runtime BT status + active task name (if any) on an AI pawn.

Parameter	Type	Required	Description
actor_name	string	yes	Name or label of the AI-possessed pawn (or AIController) whose UBehaviorTreeComponent to query.

Returns: { actor_name, run_status, run_status_name, active_task_name, bt_asset_name }

get_blackboard_component

Read-only.

Read the UBlackboardComponent of an editor-world actor (its AIController blackboard, else one on the actor): component_name, has_valid_asset, num_keys and the key list. Read-only. Editor world only, never PIE, where pawns are not auto-possessed; for asset keys use get_blackboard_keys_asset.

Parameter	Type	Required	Description
actor_name	string	yes	Object name or label of the pawn, its AIController, or an actor with its own UBlackboardComponent, in the editor world (first match).

Returns: { actor_name: string, component_name: string, has_valid_asset: bool, num_keys: number, blackboard_asset: string?, keys: [{ name: string, type: string, instance_synced: bool }]? }

get_blackboard_data

Read-only.

Retrieve all key-value pairs and complete data from an actor's blackboard

Parameter	Type	Required	Description
actor_name	string	yes	Name of the actor whose blackboard to dump (use blackboard_path for asset-based read)
blackboard_path	string	no	Path to a UBlackboardData asset (alternative to actor_name)

Returns: { actor_name: string?, blackboard_asset: string?, name: string?, parent: string?, keys: [{ name, type, instance_synced }]?, entries: [{ name, type, value }]?, key_count: number }

get_blackboard_keys

Read-only.

List blackboard key definitions (name, type, instance_synced, base_class or enum subsettings): of the running blackboard of an editor-world actor when actor_name is given, else of the UBlackboardData asset at blackboard_path. Read-only; returns keys and key_count. Editor world only, never PIE.

Parameter	Type	Required	Description
actor_name	string	no	Object name or label of an editor-world actor whose live blackboard to read; takes precedence over blackboard_path.
blackboard_path	string	no	Path to a UBlackboardData asset (alternative to actor_name)

Returns: { actor_name: string?, blackboard_asset: string?, keys: [{ name: string, type: string, instance_synced: bool }], key_count: number }

get_blackboard_keys_asset

Read-only.

Read key definitions from a UBlackboardData asset (no live component needed).

Parameter	Type	Required	Description
blackboard_path	string	yes	Path to the UBlackboardData asset.

Returns: { blackboard_path: string, name: string, parent: string?, keys: [{ name: string, type: string, instance_synced: bool }], key_count: number }

get_blackboard_value

Read-only.

Read one key of the running blackboard of an editor-world actor (its AIController blackboard, else one on the actor). value is a number for Int, Float and Enum keys, a bool for Bool, else a string (objects as paths). Read-only; editor world only, never PIE.

Parameter	Type	Required	Description
actor_name	string	yes	Name of the actor whose blackboard to query
key_name	string	yes	Name of the blackboard key to retrieve

Returns: { actor_name: string, key_name: string, key_type: string, value: number|string|bool }

pause_behavior_tree

Destructive.

Pause the behavior tree of an editor-world actor (its AIController brain component, else a UBehaviorTreeComponent on the actor) with PauseLogic. paused is always true, not read back; was_running is measured. Editor world only, never PIE. Continue it with resume_behavior_tree.

Parameter	Type	Required	Description
actor_name	string	yes	Object name or label of the pawn, its AIController, or an actor with a UBehaviorTreeComponent, in the editor world (first match).

Returns: { actor_name, paused, was_running }

remove_blackboard_key

Destructive, idempotent.

Remove a key from a UBlackboardData asset and save it. Inverse of add_blackboard_key: drops the matching FBlackboardEntry from UBlackboardData::Keys (then UpdateKeyIDs to re-index). Addresses the key by key_name (as add_blackboard_key created it) or by index into the asset's own Keys array (parent-chain keys are not touched). Idempotent: a missing key returns removed:false / already_absent:true.

Parameter	Type	Required	Description
blackboard_path	string	yes	Path to the UBlackboardData asset.
key_name	string	no	Name of the key to remove (as passed to add_blackboard_key); provide this or 'index'.
index	number	no	Alternative to key_name: 0-based position in this asset's own Keys array (excludes inherited parent keys).

Returns: { blackboard_path: string, key_name: string, key_type: string?, removed: bool, already_absent: bool, key_count: number, saved: bool, save_error?: string, keys: [{ name, type, instance_synced }] }

remove_bt_composite_child

Destructive, idempotent.

Remove a child composite (Selector/Sequence/...) from a BehaviorTree composite. Inverse of add_bt_composite_child: drops the matching entry from the parent's Children array. Only composite child-edges are considered, so a task with the same name is untouched. Idempotent: a missing child returns removed:false / already_absent:true.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset.
child_name	string	no	Name of the composite child to remove (a child_name from a prior add_bt_composite_child); provide this or 'index'.
index	number	no	Alternative to child_name: 0-based position in the parent's Children array (the edge at that index must be a composite).
parent_name	string	no	Optional parent composite name owning the child; "Root" or omitted targets the RootNode.

Returns: { behavior_tree_path: string, parent_name: string, child_name: string, child_kind: string, removed: bool, already_absent: bool, child_count: int, saved: bool, save_error?: string }

remove_bt_decorator

Destructive, idempotent.

Remove a decorator (execution condition) from a specific child-edge of a BehaviorTree composite. Inverse of add_bt_decorator: drops the matching entry from that child's Decorators array (FBTCompositeChild::Decorators). Idempotent: a missing decorator returns removed:false / already_absent:true.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset.
child_name	string	yes	Name of the existing child (a child_name from a prior add) whose edge the decorator gates.
decorator_name	string	no	Name of the decorator to remove (a decorator_name from a prior add_bt_decorator); provide this or 'index'.
index	number	no	Alternative to decorator_name: 0-based position in the child-edge's Decorators array.
parent_name	string	no	Optional parent composite name owning the child-edge; "Root" or omitted targets the RootNode.

Returns: { behavior_tree_path: string, parent_name: string, child_name: string, decorator_name: string, removed: bool, already_absent: bool, decorator_count: int, saved: bool, save_error?: string }

remove_bt_service

Destructive, idempotent.

Remove a service (background tick) from a BehaviorTree composite. Inverse of add_bt_service: drops the matching entry from the composite's Services array (UBTCompositeNode::Services). Idempotent: a missing service returns removed:false / already_absent:true.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset.
service_name	string	no	Name of the service to remove (a service_name from a prior add_bt_service); provide this or 'index'.
index	number	no	Alternative to service_name: 0-based position in the composite's Services array.
parent_name	string	no	Optional composite name the service is attached to; "Root" or omitted targets the RootNode.

Returns: { behavior_tree_path: string, parent_name: string, service_name: string, removed: bool, already_absent: bool, service_count: int, saved: bool, save_error?: string }

remove_bt_task_child

Destructive, idempotent.

Remove a leaf task node (Wait/MoveTo/...) from a BehaviorTree composite. Inverse of add_bt_task_child: drops the matching entry from the parent's Children array. Only task child-edges are considered, so a composite with the same name is untouched. Idempotent: a missing child returns removed:false / already_absent:true.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset.
child_name	string	no	Name of the task child to remove (a child_name from a prior add_bt_task_child); provide this or 'index'.
index	number	no	Alternative to child_name: 0-based position in the parent's Children array (the edge at that index must be a task).
parent_name	string	no	Optional parent composite name owning the child; "Root" or omitted targets the RootNode.

Returns: { behavior_tree_path: string, parent_name: string, child_name: string, child_kind: string, removed: bool, already_absent: bool, child_count: int, saved: bool, save_error?: string }

restart_behavior_tree

Destructive.

Restart the current behavior tree of an editor-world actor from its root (RestartTree), through its AIController brain component or a UBehaviorTreeComponent on the actor. restarted is always true, not measured: check get_behavior_tree_status. Editor world only, never PIE.

Parameter	Type	Required	Description
actor_name	string	yes	Name or label of the AI-possessed pawn (or AIController) whose UBehaviorTreeComponent to restart.

resume_behavior_tree

Destructive.

Resume a behavior tree paused by pause_behavior_tree (ResumeLogic) on an editor-world actor, through its AIController brain component or a UBehaviorTreeComponent on the actor. Returns was_paused and is_paused, both read from the component. Editor world only, never PIE.

Parameter	Type	Required	Description
actor_name	string	yes	Name or label of the AI-possessed pawn (or AIController) whose UBehaviorTreeComponent to resume.

run_behavior_tree

Destructive.

Start a BehaviorTree asset with AAIController::RunBehaviorTree on an AIController or the pawn it possesses. The actor is searched in the editor world only, never PIE, where pawns are not auto-possessed, so it usually errors with no AIController. Returns started and ai_controller; nothing is saved.

Parameter	Type	Required	Description
actor_name	string	yes	Object name or label of the pawn or AIController in the editor world (first match).
behavior_tree_path	string	yes	Asset path of the UBehaviorTree, e.g. "/Game/AI/BT_Enemy"; a bare asset name is not resolved.

Returns: { actor_name: string, behavior_tree_path: string, started: bool, ai_controller: string }

set_behavior_tree_root

Destructive, idempotent.

Set a BehaviorTree's RootNode to a new composite (Selector or Sequence) and save.

Parameter	Type	Required	Description
behavior_tree_path	string	yes	Path to the UBehaviorTree asset.
composite	string	no	Root composite type: "Selector" or "Sequence" (optional, default "Selector")

Returns: { behavior_tree_path: string, composite: string, has_root_node: bool, root_node_class: string, saved: bool, save_error: string? }

set_blackboard_key_subsettings

Destructive, idempotent.

Constrain an existing blackboard key's subsettings on a UBlackboardData asset and save. This is the SECOND HALF of add_blackboard_key, which only sets EntryName/KeyType/bInstanceSynced: it fills the per-type filter the editor would otherwise make you pick by hand -- BaseClass for an Object/Class key, EnumType for an Enum key. At least one of base_class / enum_type is required, and the one you supply must match the key's type.

Parameter	Type	Required	Description
blackboard_path	string	yes	Path to the UBlackboardData asset.
key_name	string	yes	Name of the existing key to constrain.
base_class	string	no	Class path/name (e.g. "/Script/Engine.Actor" or "Actor") for an Object/Class key (optional).
enum_type	string	no	Enum path/name (e.g. "/Script/Engine.ECollisionChannel") for an Enum key (optional).

Returns: { blackboard_path: string, key_name: string, key_type: string, base_class: string?, enum_type: string?, enum_name: string?, already_set: bool, saved: bool, save_error: string?, keys: [...] }

set_blackboard_value

Destructive, idempotent.

Write one key of the running blackboard of an editor-world actor, converting the value string by key type. Not read back: set is always true, and an unparsable number or vector is written as 0. Runtime state only, nothing saved; editor world only, never PIE. Verify with get_blackboard_value.

Parameter	Type	Required	Description
actor_name	string	yes	Name of the actor whose blackboard to modify
key_name	string	yes	Name of the blackboard key to set
value	string	no	Value as a string, converted by key type: "42", "0.5", "true" or "1", a name, an enum index, a vector "X=1 Y=2 Z=3", a rotator "P=0 Y=90 R=0", an object or class path. Omitted means empty (0, false, none).

Returns: { actor_name: string, key_name: string, key_type: string, value: string, set: bool }

stop_behavior_tree

Destructive.

Stop the behavior tree of an editor-world actor with StopTree (Safe mode), through its AIController brain component or else a UBehaviorTreeComponent on the actor. Runtime state only, nothing saved; editor world only, never PIE. was_running is read before the stop (running and not paused); stopped is true when a started tree, running or paused, is no longer started afterwards. A tree that was not started is not an error: success with stopped false and a note. A tree still started after the call (a task still aborting) is an error. An unknown actor, or one with no behavior tree component, is an error. Unlike pause_behavior_tree it cannot be continued with resume_behavior_tree: start again with restart_behavior_tree (the last tree) or run_behavior_tree.

Parameter	Type	Required	Description
actor_name	string	yes	Object name or label of the pawn or AIController in the editor world (first match)

Returns: { actor_name: string, was_running: bool, stopped: bool, note?: string }