Skip to content
Bit Quirky Behavior Trees and
State Machines

Search documentation

All topics and APIs

Close returns focus to Search.

What are you looking for?

Try a common topic or enter a complete API identifier.

Browse the reference instead

Esc closes · Tab reaches results · Enter opens the focused link

v0.11.0
Menu

Behavior tree nodes

Every built-in behavior tree node, with its result rule, its right-rail fields, and the guide that teaches it.

Fourteen 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.

Every node on this page except Condition ends its form with an Interruption response block holding one Response switch. Switched on, it writes response: true on that node; when a Lower Priority or Self abort interrupts that task while it runs, the agent raises BehaviorAgent.InterruptionResponseTriggered once and records LastInterruptionHasConfiguredResponse. The package draws nothing: your game subscribes and decides what the response looks like (interrupt). Switched off, the entry leaves the graph file and the row reads false with default beside it. In Live the switch is read only.

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.

One value elsewhere on the canvas breaks that read-only rule: a Member condition’s own bool, whole-number, or float comparison constant is the Task value the rail’s Live values section can tune per running instance, covered in Live values. None of the fourteen nodes on this page carries one.

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

Selector with three ordered branches
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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts whichever child this Selector holds raises the response once.

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.

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

Random Selector with weighted children
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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the drawn child raises the response once.

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.

Score every branch from its considerations and run whichever one currently scores highest. Graph token utility_selector.

Flank branch selected, two considerations combined by minimum, interrupt execution mode
Figure 3. Flank branch selected, two considerations combined by minimum, interrupt execution mode

Result

Success
The running branch returned Success.
Failure
Every enabled branch has been tried and failed.
Running
The highest-scoring remaining branch is still working.
Field What to enter Effect
CONSIDERATIONS + Add a row, choose a declared numeric value, then Direct or Curve. 1 to 8 per branch. Each row supplies one value toward the branch’s score. A curve needs at least two keys.
AGGREGATION Average, Minimum, or Maximum. Shown and required past one consideration. How 2 or more consideration values combine into the branch’s score. Ignored, and hidden, with exactly one consideration.
EXECUTION MODE Finish first or Interrupt, per branch. Finish first protects the running branch until it finishes on its own. Interrupt hands off the instant a rival scores strictly higher.

The selector re-scores every enabled branch every evaluation and runs the strictly highest; an exact tie keeps the earlier-authored branch. A failed branch leaves the candidate set and the selector re-picks from what remains, the same fallback a Selector uses, and a Blocked result counts as a failure here, including a first child that refuses on the very evaluation its branch is chosen. A branch score that comes out NaN or infinite faults the agent, with no clamping or substitute value, and leaves every other agent ticking. A consideration naming a value outside the selector’s own declared read set, a non-numeric value, a curve under two keys, or a multi-consideration branch missing an aggregation each block a valid bake with a diagnostic on the row.

Use it when the winner should move as the game’s numbers move, like a brute weighing whether to close distance, flank, or fall back. Guide: weigh it up.

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

Sequence with a condition followed by work
Figure 4. 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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts any running step raises the response once. Dungeon Heist’s patrol_sequence is on.

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.

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

Parallel control with its direct children
Figure 5. 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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts a running child of the group raises the response once.

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.

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

Inverter decorating a condition
Figure 6. 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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the running child raises the response once.

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.

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

Repeat decorating a patrol action
Figure 7. Repeat decorating a patrol action
Selected Horde Attack Flurry Repeat reads Count 3 and completed 3 of 3 after a real burst.
Figure 8. Horde’s selected Attack Flurry Count has finished: status success and completed 3 of 3 beside attacks_landed at 3. The Platformer still above shows the Static authoring shape.

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, the final counted attempt failed, or stop on failure ended an earlier attempt.
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.
stop on failure Switch on, or leave off. Offered with Count and Forever; retained settings remain visible with an Until policy. Off by default. On returns the first Failure or Blocked attempt immediately, without waiting for Count or another repetition.
Child Attach exactly one child. Always, as a reading. Names the repeated subtree.
Interruption response > Response Switch on, or leave off. Always. On: an abort that interrupts the current attempt raises the response once.

The optional source parameter stop_on_failure defaults to false, so existing graphs keep their stopping rules. A saved true retained under Until Success ends on the first completed result; switch it off to retry failures. Under Until Failure, true changes nothing. Running never counts as a failed attempt, and typed interruption, timeout, authority, and runtime fault results retain their existing propagation.

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, select the Repeat pill itself: its read-only rail shows status, the current run or completion, and last child result. A running Count can read run 2 of 3, while a finished Count with retained success or failure reads completed 3 of 3 even though the runtime has cleared its iteration storage. A finished Until Success or Until Failure reads completed without inventing a total; an untouched decorator reads not started. Entity and GameObject Live both read the selected decorator’s retained status. An unselected child’s Failure can appear while its Until Success wrapper stays running for another attempt.

Use it when a decision needs a repeatable stopping rule: Horde Survival has a Count attack flurry, an Until Success pursuit, and a Forever decision loop. The Platformer sample keeps its patrol alive with Forever. Guide: keep going.

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

Time Limit decorating a movement action
Figure 9. 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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the subtree under the deadline raises the response once.

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.

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

Conditional decorating chase work
Figure 10. 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, lower priority, self, or both. none checks admission once, when the tree reaches it. lower priority re-checks every update and takes over from a lower-priority sibling branch the update the fact starts succeeding. self re-checks every update and cancels the running child when the fact stops succeeding. both does the lower priority and self effects from the same check.
Child Attach exactly one child. Names the guarded subtree.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the admitted child raises the response once.

Admission needs Success, so a Blocked comparison refuses the child and the decorator reports Failure. With lower priority, the hosting Selector drops back to this branch the update the fact starts succeeding; the node has to guard a Selector branch with at least one lower-priority sibling, which validation enforces. 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. With both, it does both from the same check.

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

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

A Condition card named route is clear, tagged blackboard above its glyph
Figure 11. A Condition card named route is clear, tagged blackboard above its glyph

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.
abort mode none, lower priority, self, or both. none evaluates the comparison once, when the tree reaches it. lower priority re-checks every update and takes over from a lower-priority sibling branch the update the comparison starts succeeding. self re-checks every update and cancels its own Selector sibling branch the update the comparison stops succeeding. both does both from the same check.

The node is read only at runtime; it writes nothing. Its own abort mode field supplies the reactive opt-in: any mode other than none needs a Selector with at least one lower-priority sibling branch, which validation enforces.

A saved guard with no explicit comparison uses != false or != 0. Editing its value preserves that comparison. Integer comparisons keep adjacent Int32 values distinct even above 16,777,216, whether the right side is a constant or another variable. Positive and negative floating-point zero both count as zero.

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

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

Action node for a patrol announcement
Figure 12. 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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the outstanding request raises the response once.

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.

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

Move To action with an authored waypoint
Figure 13. 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.
Interruption response > Response Switch on, or leave off. No unit. On: an abort that interrupts the movement request raises the response once.

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.

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

A Subgraph node carrying the address of the tree it runs
Figure 14. 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.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the referenced tree raises the response once.

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.

Run a separately authored State Machine graph in place, without flattening its nodes into the host. Graph token state_machine_host.

A Hosted State Machine node carrying the State Machine it runs, named by that machine’s asset
Figure 15. A Hosted State Machine node carrying the State Machine it runs, named by that machine’s asset

Result

Success
The hosted instance entered the host's own chosen success state (if one is set), or an authored terminal-event transition reached the referenced machine's Success-mapped state, or the referenced machine reached a reachable dead end with no outgoing transition and no terminal-event transition firing (plain normal completion).
Failure
The hosted instance entered the host's own chosen failure state (if one is set), or an authored terminal-event transition reached the referenced machine's Failure-mapped state.
Running
The referenced machine has not yet reached the host's own chosen state, a mapped terminal state, or a dead end.
Field What to enter Effect
Choose a state machine… Pick an existing State Machine asset. The node is named by the machine it runs, never by its address. Validation rejects a Behavior Tree address. Mapping a terminal state or normal completion to Success or Failure is optional: a machine with neither, either, or both is valid.
Result states > Success state / Failure state Optionally pick a state from the referenced machine for each. Machine’s own result, the default, reports however the machine finishes. The moment the hosted instance enters a chosen state, the host stops the routine and reports that result, even when the state has no completion marker of its own; this takes precedence over an authored terminal-event mapping and over plain normal completion. A saved state the machine no longer has reads Missing state · and its name, and validation rejects it.
Interruption response > Response Switch on, or leave off. On: an abort that interrupts the referenced machine while it runs raises the response once.

Activation materializes a fresh instance of the referenced machine and seeds every declared value whose name and kind match one the host also declares, from the host’s current values at that exact moment. The referenced machine’s own nodes are never flattened into the host: it keeps its own baked artifact, addressed by the node and resolved at runtime, not merged in at bake time, unlike Subgraph. Interruption tears the instance down with no resume: a later activation always starts the referenced machine fresh, from its own entry state, never from wherever an earlier, interrupted activation left off.

Use it for a self-contained routine with its own states and transitions, as in the Platformer enemy’s search and return branch (sample). Guide: run a state machine.

Full-size image