Behavior Trees

Search Behavior Tree node classes, ranked

Searches every composite, task, decorator and service class the editor knows, engine and project alike, including Blueprint-authored nodes that are not loaded yet. Results are ranked: an exact name beats a prefix, a prefix beats a word-boundary hit, and that beats a loose substring. Pass --queries to ask several keywords in one call and get a ranked list per keyword instead of N round trips. Backed by the editor's own class cache, so what comes back is what the node menu shows.

cfa search_bt_nodes --query move --kind task --max-results 5
cfa search_bt_nodes --queries "move,wait,blackboard" --max-results 3
cfa search_bt_nodes --kind composite

Read a node class: its properties and what each accepts

Returns a node class in full: whether it takes children, decorators or services, its class chain, and every editable property with its type, default and tooltip. Blackboard key selector properties additionally report which key types they accept, and when --behavior-tree is given, exactly which keys on that tree's blackboard would be accepted. That is the call to make before set_bt_node_property so a key is never rejected on the way in.

cfa get_bt_node_type_info --node-class BTTask_MoveTo
cfa get_bt_node_type_info --node-class BTDecorator_Blackboard --behavior-tree /Game/AI/BT_Guard

List available blackboard key types

Lists every blackboard key type in this project, discovered by reflection rather than a fixed list, so a project's own key type shows up too. Each entry reports the short name add_blackboard_keys takes and the settings that type accepts, such as an Object key's BaseClass or an Enum key's EnumType.

cfa list_blackboard_key_types

Create a Behavior Tree with its graph and Root node

Creates a Behavior Tree and builds its editor graph and Root node, replicating what the Behavior Tree editor does when it opens an asset. The factory alone leaves the graph null, so an asset made any other way opens blank and cannot take nodes. By default a Blackboard named <Name>_BB is created alongside and attached; pass --blackboard to attach an existing one, or --create-blackboard=false for none.

cfa create_behavior_tree --name BT_Guard --path /Game/AI
cfa create_behavior_tree --name BT_Guard --path /Game/AI --blackboard /Game/AI/BB_Shared

Create a Blackboard

Creates a Blackboard asset. With --parent it inherits that blackboard's keys and the inherited set is refreshed immediately, so the new asset reports its full key list right away.

cfa create_blackboard --name BB_Guard --path /Game/AI
cfa create_blackboard --name BB_Elite --path /Game/AI --parent /Game/AI/BB_Guard

Attach a Blackboard to a Behavior Tree, or set what it inherits from

Attaches a Blackboard and then re-runs the tree's blackboard update, which is what re-resolves every cached key selector on every node and sub-node. Setting the asset without that step leaves stale key IDs behind and nodes silently read the wrong key. --parent instead points the Blackboard at one it inherits keys from, through the engine's own edit path so the inherited keys and the synchronised-key flag are both refreshed; a parent that would form a cycle is refused by name rather than silently cleared the way the engine does it. Pass --parent none to clear it. Either argument may be given on its own.

cfa set_bt_blackboard --behavior-tree /Game/AI/BT_Guard --blackboard /Game/AI/BB_Guard
cfa set_bt_blackboard --blackboard /Game/AI/BB_Guard --parent /Game/AI/BB_Base

Create a Blueprint task, service or decorator

Creates a node Blueprint from the right base class for the kind (BTTask_BlueprintBase, BTService_BlueprintBase, BTDecorator_BlueprintBase) and compiles it. Composites are not Blueprintable in Unreal, so --kind takes task, service or decorator only. The reply names the generated class, which is the name add_bt_node and search_bt_nodes use, and it is not the asset name. Author the graph afterwards with the blueprint graph commands.

cfa create_bt_node_blueprint --name BTT_Patrol --kind task --path /Game/AI/Nodes
cfa create_bt_node_blueprint --name BTS_ScanForEnemies --kind service

Read a Behavior Tree as a tree

Returns the tree from the Root down: every node with its stable node_id, class, decorators, services and children, in execution order. Nodes left unconnected are reported separately rather than hidden, because they are still in the asset and still visible in the editor. Use --verbosity summary for ids and classes only, or full to include every node property.

cfa get_behavior_tree --behavior-tree /Game/AI/BT_Guard
cfa get_behavior_tree --behavior-tree /Game/AI/BT_Guard --verbosity summary

Read a Blackboard's keys

Lists a blackboard's keys with their type, per-type detail such as an Object key's base class, instance syncing, description and category. Accepts either a Blackboard path or a Behavior Tree path, in which case the tree's attached blackboard is read. Keys inherited from a parent blackboard are included and flagged.

cfa get_blackboard --blackboard /Game/AI/BB_Guard
cfa get_blackboard --blackboard /Game/AI/BT_Guard --filter target

Check a Behavior Tree and return a verdict

Compiles the tree and then judges the result, returning pass, pass_with_warnings or fail with the reasons. Errors cover a missing or childless Root, nodes with no runtime instance, and blackboard key selectors pointing at a missing key or a key whose type the property does not accept. Warnings cover a tree with no blackboard, empty composites and unconnected nodes. It compiles first on purpose: judging the in-memory graph alone would pass a tree whose runtime chain never builds.

cfa validate_behavior_tree --behavior-tree /Game/AI/BT_Guard

Add composites and tasks to a Behavior Tree

Places composite and task nodes under a parent and wires them up. Pass --node-class for one node, or --nodes with a JSON array to build a whole subtree in one call: give an entry an "id" and a later entry can name it as its "parent", so a selector and its children land together. Sibling order comes from child_index, which is what the compiled execution order is derived from. Properties are set as the node is placed, and a blackboard key selector takes the key name as a string.

cfa add_bt_node --behavior-tree /Game/AI/BT_Guard --node-class BTComposite_Selector
cfa add_bt_node --behavior-tree /Game/AI/BT_Guard --nodes '[{"node_class":"BTComposite_Selector","parent":"root","id":"sel"},{"node_class":"BTTask_Wait","parent":"sel","properties":{"WaitTime":3.0}}]'
cfa add_bt_node --behavior-tree /Game/AI/BT_Guard --nodes '[{"node_class":"BTComposite_Sequence","parent":"root","decorators":[{"node_class":"BTDecorator_Blackboard","properties":{"BlackboardKey":"HasEnemy"}}],"services":[{"node_class":"BTService_DefaultFocus"}]}]'

Attach decorators and services to a node

Attaches decorators and services, which are sub-nodes owned by a node rather than nodes in the graph. Decorators attach to composites and tasks; services attach to composites only, and asking for anything else is refused with that reason. Use --index to order them, or --sub-nodes with a JSON array to attach several at once.

cfa add_bt_subnode --behavior-tree /Game/AI/BT_Guard --node-class BTDecorator_Blackboard --parent sel --properties '{"BlackboardKey":"TargetActor"}'
cfa add_bt_subnode --behavior-tree /Game/AI/BT_Guard --sub-nodes '[{"node_class":"BTService_DefaultFocus","parent":"sel"}]'

Re-parent a node or change its sibling order

Links a child to a parent. A Behavior Tree node has exactly one parent, so the child's existing link is dropped first unless --reparent=false. child_index sets the position among siblings, which is what decides execution order once compiled.

cfa connect_bt_nodes --behavior-tree /Game/AI/BT_Guard --parent root --child BTComposite_Sequence --child-index 0

Remove a node, a subtree, or a sub-node

Removes a node and, by default, everything below it. Pass --recursive=false to remove just that node and leave its children unparented. Naming a decorator or service detaches it from its owner instead. The Root node cannot be removed.

cfa remove_bt_node --behavior-tree /Game/AI/BT_Guard --node BTTask_Wait

Set properties on a node, decorator or service

Writes any reflected property on a node's runtime instance, so every property type works without per-type handling. Setting a decorator's FlowAbortMode (None, LowerPriority, Self, Both) is checked against reality: the engine clamps a mode the parent composite cannot support, so a Sequence turns Both into Self and a Simple Parallel turns everything into None, and the reply reports the change under 'coerced' instead of leaving you with a tree that behaves differently from what you asked for. A blackboard key selector is the one other special case: pass the key name as a plain string and it is resolved against the tree's blackboard. If the key does not exist, or its type is not one the property accepts, the write is refused and the error names the key's actual type and what the property wanted, rather than leaving a tree that compiles and misbehaves. An unknown property name comes back with the close matches.

cfa set_bt_node_property --behavior-tree /Game/AI/BT_Guard --node BTTask_MoveTo --property BlackboardKey --value TargetActor
cfa set_bt_node_property --behavior-tree /Game/AI/BT_Guard --node BTTask_Wait --properties '{"WaitTime":2.5,"RandomDeviation":0.5}'

Rebuild the runtime node chain from the graph

Rebuilds parent links, execution order and the runtime node chain from the editor graph. Behavior Trees have no compiler results log, so the honest signal is whether a runtime root came out and what per-node error messages the graph recorded; both are reported. The authoring commands compile by default, so this is for after a batch run with --compile=false.

cfa compile_behavior_tree --behavior-tree /Game/AI/BT_Guard

Auto-arrange the graph layout

Runs the Behavior Tree editor's own auto-arrange over the graph, then recompiles. The recompile is not optional: node X position is what sibling order is derived from, so a layout pass can change execution order and the tree must be rebuilt to match what is now on screen.

cfa arrange_behavior_tree --behavior-tree /Game/AI/BT_Guard

Combine decorators with AND, OR or NOT

Attaches a composite decorator: several decorators combined into one condition. --operator takes and, or or not; and/or need two or more children, not takes exactly one. The inner logic graph is built by the engine from the expression, which is the only workable route because the inner graph node classes carry no API tag in any engine version and cannot be linked at all. Each child is an ordinary decorator with its own properties, so a blackboard key selector still takes the key name and is still type-checked.

cfa add_bt_composite_decorator --behavior-tree /Game/AI/BT_Guard --parent BTTask_MoveTo --operator and --children '[{"node_class":"BTDecorator_Blackboard","properties":{"BlackboardKey":"HasEnemy"}},{"node_class":"BTDecorator_Blackboard","properties":{"BlackboardKey":"Alert"}}]'
cfa add_bt_composite_decorator --behavior-tree /Game/AI/BT_Guard --parent BTTask_Wait --operator not --children '[{"node_class":"BTDecorator_Blackboard","properties":{"BlackboardKey":"HasEnemy"}}]'

Inspect Behavior Trees running in play

Reports every Behavior Tree component running in PIE: its root and current tree, whether it is running or paused, the engine's own active-task and active-tree debug strings, the active node, and every blackboard key with its live value. Nothing runs in the editor world, so this needs play started. It also states the template-cache rule: a tree executes from a template captured when it first ran and nothing in the engine invalidates it, so editing the asset mid-play changes nothing until play restarts.

cfa get_bt_runtime
cfa get_bt_runtime --actor Enemy --include-blackboard=false

Start, stop, restart, pause or resume running logic

Drives the brain component's own lifecycle on running actors, so a tree can be halted and restarted without leaving play. Applies to every running component unless --actor narrows it.

cfa control_bt_runtime --action restart
cfa control_bt_runtime --action stop --actor Enemy

Swap the subtree behind a Run Behavior Dynamic task

Injects a Behavior Tree into a Run Behavior Dynamic task on a running tree. The tag is matched by equality, not by tag hierarchy, so it must equal the task's InjectionTag exactly. This is the only way to change what a running tree does without restarting play, because a plain Run Behavior task is baked into the template. Where no task carries the tag the engine does nothing and says so only in its log, so the reply repeats that caveat.

cfa set_bt_dynamic_subtree --inject-tag AI.Combat --subtree /Game/AI/BT_Aggressive

Add keys to a Blackboard

Adds one or many keys in a single edit, following the editor's own add sequence so key IDs and instance-sync state are recomputed exactly as they would be by hand. Per-type settings go in the same call: --base-class for Object and Class keys, --enum-type for Enum and NativeEnum, --struct-type for Struct. Every key type is validated before anything is written, so a bad type in one entry cannot leave the earlier ones half-added.

cfa add_blackboard_keys --blackboard /Game/AI/BB_Guard --name TargetActor --type Object --base-class Actor
cfa add_blackboard_keys --blackboard /Game/AI/BB_Guard --keys '[{"name":"HasTarget","type":"Bool"},{"name":"PatrolPoint","type":"Vector"}]'

Remove a key from a Blackboard

Removes a key and recomputes key IDs. A name that is not there comes back with the list of keys that are, so a typo costs one call rather than two.

cfa remove_blackboard_key --blackboard /Game/AI/BB_Guard --name PatrolPoint

Rename, retype or edit a Blackboard key

Edits an existing key: rename it, change its type, adjust the per-type settings, or set its description, category and instance syncing. Changing the type replaces the key's type object rather than mutating it, because the class is what defines the key. instance_synced is only applied when actually passed, so the flag's default cannot silently unsync a key you were only renaming.

cfa set_blackboard_key --blackboard /Game/AI/BB_Guard --name TargetActor --new-name EnemyActor
cfa set_blackboard_key --blackboard /Game/AI/BB_Guard --name TargetActor --type Object --base-class Pawn