Behavior tree nodes

Twelve nodes build every behavior tree in the product. Each entry here gives the result rule, the fields on the right rail, and the guide that shows the node doing its job.

Every selected node starts with the same identity header: SELECTED NODE, the editable name, and a kind line. Edit the name there; no node form repeats it. A Children list is structural, so you reorder it by dragging rows, and a decorator’s Child line is a reading rather than a field. In Live the same values are readings instead of controls.

Results across the whole set: Success, Failure, and Running do the everyday work. Blocked is a false guard, which composites treat as a failed step. Interrupted, Timeout, and Authority mismatch travel up to the root so the reason survives. The status pill on the active card shows RUNNING, SUCCESS, FAILURE, or INTERRUPTED, and the rail’s Graph runtime status section names the precise Last result. A decorator renders as a chip on its child’s card, so the decorator’s own result appears on that same card.

Selector

Try alternatives in priority order and keep the first one that works. Source token selector.

Figure 1. Selector with three ordered branches

Result

Success

A child returned Success. The Selector stops there.

Failure

Every child returned Failure or Blocked.

Running

The current child is Running, or a child declined and the cursor moved on.

Field	What to enter	Effect
Children	Add, remove, or drag direct child rows.	This list is the priority order. Canvas positions carry none.
Reactive abort > Abort	None or Lower priority.	Lower priority re-checks the conditions in higher branches while a lower branch runs, and preempts down to one that becomes true.

The typed stops (Interrupted, Timeout, Authority mismatch) pass through to the parent; the Selector offers no fallback for them. At least one child is required.

Use it when an agent should do the most urgent thing it currently can, as in Dungeon Heist’s Guard2.bqbehavior (sample). Guide: choose.

Random Selector

Draw one branch by weight, and redraw if the drawn branch fails. Source token probability_selector.

Figure 2. Random Selector with weighted children

Result

Success

The drawn child returned Success.

Failure

Every candidate was drawn and failed, or Direct failure was drawn, or no outcome has a usable positive weight.

Running

The drawn child is working, or a failed child has just been replaced by a fresh draw.

Field	What to enter	Effect
Branches	+ Add creates a row. Each row has the child name, an ENABLED switch, and a WEIGHT.	Enabled rows with a finite weight of 0 or more join the candidate set.
WEIGHT	A finite number of 0 or more.	Relative chance. Zero stays authored and can never be drawn.
Direct failure	Add the row, then give it a finite weight of 0 or more. Remove it to make the outcome absent.	When drawn, the selector reports Failure without running a child. Absent differs from present with weight 0.
FIRST PICK	Read only; reads NEXT PICK in Live.	The chance the editor computes from the usable weights. Never, Not included, or Not used mark a zero weight, an invalid one, or a disabled row.

Only Failure triggers a redraw; Blocked and the typed stops travel up. Each agent holds its own random state. Up to 64 direct branches, with Direct failure stored separately. Weight text that is empty, negative, or not a number blocks a valid bake.

Use it when variety matters more than priority, as in Horde Survival’s surge director (sample). Guide: roll the dice.

Sequence

Run required steps in order and stop at the first failure. Source token sequence.

Figure 3. Sequence with a condition followed by work

Result

Success

Every child returned Success, including the last.

Failure

A child returned Failure or Blocked, and the remaining children did not run.

Running

The current child is Running, or a child succeeded and the cursor advanced.

Field	What to enter	Effect
Children	Add, remove, or drag rows into execution order.	The order steps run in. There is no threshold, mode, or parallelism field.

The cursor belongs to the running agent, so two agents on one graph sit at different steps. A typed stop (Interrupted, Timeout, Authority mismatch) ends the Sequence and passes upward.

Use it when later work is only valid after earlier work succeeded, as in the Platformer patrol (sample). Guide: do in order.

Parallel

Group the children that all have to succeed for the branch to count as done. Source token parallel.

Figure 4. Parallel control with its direct children

Result

Success

Every child has returned Success.

Failure

A child returned Failure or Blocked.

Running

A child is Running, so the group holds, or a child succeeded and the next one is up.

Field	What to enter	Effect
Children	Add, remove, or drag rows.	Membership of the set, and the order the children are visited in. There is no policy, threshold, or worker-count control.

This release walks the set one child at a time in Children order, through the same cursor contract as Sequence: a Running child holds the group and the children after it have not started. Several children that finish immediately still complete inside one update. The completion rule is fixed at “every child must succeed”; the runtime holds a second policy value that nothing in the graph file or editor selects. The palette line “run children at once; a policy decides the result” is product text being corrected.

Use it when the set membership is the point rather than the ordering. Guide: do together, and what it does not do yet for what is still to come.

Inverter

Read one child’s answer backwards. Source token inverter.

Figure 5. Inverter decorating a condition

Result

Success

The child returned Failure.

Failure

The child returned Success.

Running

The child is Running.

Field	What to enter	Effect
Child	No entry. Attach exactly one child on the canvas.	Names the subtree whose Success and Failure are swapped.

Success and Failure swap. Running, Blocked, Interrupted, Timeout, and Authority mismatch pass through unchanged, which means a blackboard Condition reporting Blocked for a false comparison is not flipped. Invert the comparison inside the Condition, or map a member condition’s false case to Failed. The decorator is stateless and ticks its child once per parent visit.

Use it when one authored check has to serve both directions. Guide: flip it.

Repeat

Run one child again under an explicit stopping rule. Source token repeat.

Figure 6. Repeat decorating a patrol action

Result

Success

Count finished on a successful attempt, Until Success saw a success, or the passed-through attempt succeeded.

Failure

Until Failure saw Failure or Blocked, or the final counted attempt failed.

Running

The child is working, or an attempt completed and the policy asked for another.

Field	What to enter	When it appears	Effect
END POLICY	Count, Until Success, Until Failure, or Forever.	Always.	Chooses the stopping rule.
Count	An integer of at least 1.	Only with Count selected.	Completed attempts before the final attempt’s result leaves the node.
Child	Attach exactly one child.	Always, as a reading.	Names the repeated subtree.

Running is never an attempt. A typed stop passes through without counting. A restart yields for the rest of the update, so one restart happens per update. Leaving the decorator clears its per-agent counter. In Live the rail reads Status, Run 2 of 3, and Last child result.

Use it to keep a decision loop alive, as EnemyPatrol.bqbehavior does with Forever (sample). Guide: keep going.

Time Limit

Put a wall-clock deadline on one subtree. Source token timelimit.

Figure 7. Time Limit decorating a movement action

Result

Success

The child succeeded before the budget elapsed.

Failure

The child failed or reported Blocked before the budget elapsed, unchanged.

Running

The child is working and the budget has time left.

Field	What to enter	Effect
seconds	A finite number of 0 or more.	A positive value is the deadline. 0 never expires. The canvas pill shows the node’s name, not the budget.
Child	Attach exactly one child.	Names the subtree under the deadline.

A still-Running child at the deadline produces Timeout: pending external work owned by that subtree is cancelled with a Timeout reason, an outstanding member request is cleared, and Timeout travels up without being treated as a declined branch. Expiry is checked before a pending completion is read, so a late success cannot revive an expired wait. Elapsed time accumulates only while this ancestry is active and resets on exit.

Use it around anything that waits on your game, such as a Move To. Guide: give up after.

Conditional

Admit one subtree while a declared fact succeeds, and optionally cancel it when the fact stops. Source token conditional.

Figure 8. Conditional decorating chase work

Result

Success

The admitted child returned Success. The gate never rewrites a child result.

Failure

The fact did not succeed, so the child was refused.

Running

The fact succeeded and the child is working.

Field	What to select	Effect
condition variable	A readable declared value. The empty prompt reads Choose a condition variable….	Supplies the admission fact. A removed variable stays visible as invalid until repaired.
abort mode	none or self.	none checks admission when the tree reaches it. self re-checks every update and cancels the running child when the fact stops succeeding.
Child	Attach exactly one child.	Names the guarded subtree.

Admission needs Success, so a Blocked comparison refuses the child and the decorator reports Failure. With self, cancellation cancels pending work owned by the subtree with a Self reason and the hosting Selector re-decides from its first child; the node has to sit inside a Selector branch, which validation enforces. There is no combined abort mode.

Use it for work that stays valid only under a fact, as in Dungeon Heist’s chase guard (sample). Guides: only if and interrupt.

Condition

Compare one declared value with a typed value and use the answer as a guard. Source token condition.

Figure 9. Blackboard Condition node

Result

Success

The comparison held.

Failure

The comparison did not hold. The typed reason is Blocked.

Running

Never. A Condition answers on the update it is reached.

Field	What to enter	Rules
variable	A readable declared value. The empty prompt reads Choose a blackboard variable….	Required. The type chip reads bool, float, or int; a removed name stays visible as missing.
comparison	Boolean: == or !=. Numeric: <, <=, ==, !=, >=, or >.	Disabled until a valid variable is chosen.
value	A constant, or the name of a same-typed declared value.	Typed literals are normalized and incompatible input is rejected instead of coerced.

The node is read only at runtime; it writes nothing. There is no abort field on this node: the reactive opt-in is Reactive abort > Abort on the Selector above it, which covers every condition in its branches. An observing condition needs a Selector with at least one lower-priority sibling branch, and it fires on the update its answer becomes Success.

Use it for facts that already live on the graph. Guides: actions and conditions and interrupt.

Action

Ask a composed game service to perform work the graph only names. Source token action.

Figure 10. Action node for a patrol announcement

Result

Success

An action with no awaited service finishes in one update, or the awaited service completed successfully.

Failure

The awaited service failed, or a valid request was refused.

Running

A request is outstanding and its correlated completion has not arrived.

Field	What to enter	Effect
(identity only)	The editable name in the shared header.	An Action names the operation; its service and wait contract is established when the operation is authored.

Required handlers and adapters are composed explicitly on the host; a missing one is a typed composition fault. A completion has to match the request’s correlation identity, so a late completion from an abandoned activation is discarded. For a direct C# call, use a member node rather than expecting the name to resolve a method.

Use it when a host-composed service owns the work. Guide: actions and conditions.

Move To

Send one backend-neutral movement request to a world-space destination. Source token move_to.

Figure 11. Move To action with an authored waypoint

Result

Success

The movement service reported the request completed.

Failure

The service reported failure, or refused a valid request.

Running

The request is outstanding and the adapter is advancing it.

Field	What to enter	Units
TARGET WORLD SPACE · METERS > X, Y, Z	Finite world coordinates.	Meters.
Speed	A finite number above 0.	Meters per second.
Arrival tolerance	A finite number of 0 or more.	Meters. How close counts as arrived.

Move To never touches a Transform or an entity itself. GameObject hosts compose BehaviorMovementService around an IBehaviorMovementAdapter, whose five methods begin, advance, pause, resume, and stop one request; entity hosts supply a compatible command handler for the same movement service. One request is active at a time, and a second request while one is active is refused. Movement requests do not support authority replay, so a handoff restarts them. An interrupt or a Timeout cancels this exact request identity.

Use it for “walk there, tell me when you arrive”. Guide: move somewhere.

Subgraph

Run another saved behavior tree in place, without copying its nodes. Source token subgraph.

Figure 12. A Subgraph node carrying the address of the tree it runs

Result

Success

The referenced tree's root reported Success.

Failure

The referenced tree's root reported Failure or Blocked.

Running

The referenced tree is still working.

Field	What to enter	Effect
graph address	The referenced tree’s stable project identity.	Resolved during loading. The field is read only in Live.

Loading folds the referenced tree’s nodes plus its declared values and bindings into one parent executable before the bake, and each agent runs its own cursor through the result. Missing addresses, a referenced graph of the wrong kind, an invalid nested root, and cycles block composition or the bake. There is no input, output, or two-way variable mapping on this node in this release, no runtime subtree swap, and no subtree pool; BehaviorAgent.ReplaceGraph replaces the whole graph instead.

Use it when several trees share one authored branch. Guide: reuse a branch.

Next

• Behavior tree guides: the same twelve nodes, with the problem each one solves.
• Member nodes and bindings: the six nodes that call your C#.
• State machine controls: states, transitions, and hosted trees.