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

Interrupt

Let a higher-priority branch take the agent away from running work the moment its condition becomes true, and let a gate drop its own branch when the fact stops holding.

Your guard is halfway along its patrol when a coin lands behind it. Without an interrupt it finishes the walk and then notices. With one, it turns around while the coin is still rolling.

A running branch keeps the agent. That is the right default, because work that gets abandoned every frame never finishes anything. It is also the reason a patrolling guard can walk past the player: the patrol action is Running, so the tree never gets back up to the sight check above it.

Dungeon Heist needs the other behavior. Guard2.bqbehavior orders eight branches under one priority Selector: a shared catch reset first, then catch, then chase, then capture, then the grouped suspicion branch, then search, then return, then patrol. The sight and stimulus conditions in the higher branches each carry a Lower Priority abort, so they get re-read while patrol runs. A thrown coin becomes a stimulus, the check becomes true, and the guard drops its patrol mid-step.

  • A threat or opportunity that must beat whatever the agent is doing: the player comes into view, a distraction lands, a teammate calls for help.
  • A recovery branch that has to win instantly, like Racing Line’s vehicle recovery above ordinary racing.
  • Work that stops being valid while it runs, which is the Self case: stop chasing the moment you lose sight, rather than arriving at where the player used to be.
Patrol runs while the sight condition reads FAILURE. When the condition turns true, the Lower Priority abort hands the tick to the chase and the patrol card reads INTERRUPTED. When the fact goes false again, the Self conditional ends the chase, which reads INTERRUPTED, and patrol runs again.
Patrol runs while the sight condition reads FAILURE. When the condition turns true, the Lower Priority abort hands the tick to the chase and the patrol card reads INTERRUPTED. When the fact goes false again, the Self conditional ends the chase, which reads INTERRUPTED, and patrol runs again.

Two moments, frame by frame. DocumentationReactiveAborts.bqbehavior has a Selector at the root of the tree, named choose chase or patrol and labelled ROOT on the canvas, with three children in priority order: the chase branch first, investigate plan second, and patrol the route last. The frames come from its Live capture copy, DocumentationReactiveAbortsLive.bqbehavior, which keeps the chase and patrol branches and leaves out investigate plan. Live paints every card with the last status it reported, so the branches that are not running still say how they last ended.

  1. Patrol reading RUNNING while the sight condition and the chase plan read FAILURE
    Figure 1. Patrol reading RUNNING while the sight condition and the chase plan read FAILURE

    The sight guard in the higher branch reads FAILURE, so chase plan reads FAILURE too and the Selector fell through to patrol, which reads RUNNING. chase the player has not run yet, so its card rests without a status.

  2. Chase reading RUNNING while the patrol card reads INTERRUPTED
    Figure 2. Chase reading RUNNING while the patrol card reads INTERRUPTED

    player_visible becomes true. The guard condition is re-checked before the active node ticks and reads SUCCESS, the Lower Priority abort hands the cursor to the chase branch on that same update, and chase plan and chase the player read RUNNING from there on. patrol the route reads INTERRUPTED, not FAILURE: it was stopped, it did not fail. Nothing about the patrol branch is remembered.

  1. Open Assets/Platformer/Behavior/DocumentationReactiveAborts.bqbehavior and select the Selector called choose chase or patrol.

  2. Read the Reactive abort heading in the rail and its Abort control, set to Lower priority. The help line under it says what the runtime does: while a lower-priority child runs, higher-priority children are re-checked each tick.

  3. Confirm the branch order in Children: the chase Sequence first, investigate plan second, patrol the route third. Priority is what makes an interrupt meaningful, so the branch that should win has to be above the branch that should lose.

  4. Select the condition player is visible inside the chase branch. Its rail holds variable, comparison, value, and its own abort mode field, left at none here: the Selector’s Reactive abort opt-in above it is what re-checks this condition while patrol runs, covering every condition left at none inside that Selector’s branches regardless of each one’s own abort mode.

  5. Enter Play Mode, leave player_visible false, and let patrol start. Then set it true in the Live blackboard.

The Selector carrying Reactive abort set to Lower priority, with the chase branch above the patrol branch
Figure 3. The opt-in lives on the Selector. The order of the Children list decides who can interrupt whom.
Guard_2 is waiting out a patrol waypoint when the coin noise lands, and the suspicion and investigation branch takes the tick: the dwell holds first, and the look around at the landing spot follows it.
Guard_2 is waiting out a patrol waypoint when the coin noise lands, and the suspicion and investigation branch takes the tick: the dwell holds first, and the look around at the landing spot follows it.

Dungeon Heist, Guard_2 running Guard2.bqbehavior. The guard patrols, a coin lands, the stimulus check in a higher branch becomes true, and the investigation branch preempts the patrol while the Live tree shows the takeover beside the game.

The Dungeon Heist chapter walks the whole guard graph, including the catch branch above the chase.

Self abort is the other half of the family. Instead of a rival branch taking over, the branch’s own gate gives up.

  1. The Self conditional’s chase child reading RUNNING while the fact is true
    Figure 4. The Self conditional’s chase child reading RUNNING while the fact is true

    while visible is a Conditional with abort mode set to self. Its fact is true, so chase the player under it reads RUNNING. patrol the route still reads INTERRUPTED from the takeover.

  2. The chase child reading INTERRUPTED, with patrol reading RUNNING again
    Figure 5. The chase child reading INTERRUPTED, with patrol reading RUNNING again

    The player breaks line of sight. The gate is re-evaluated on this update. It stops succeeding, and the chase is cancelled mid-run, so chase the player reads INTERRUPTED. The hosting Selector re-decides from its first child: player is visible and chase plan read FAILURE, and patrol the route reads RUNNING again.

The Conditional’s rail with its condition variable and abort mode set to self, over its chase child
Figure 6. Self cancels the branch it guards; it never promotes a sibling. Here that branch is the Conditional’s own subtree, but a Condition offers the same self choice: picked there, it ends the branch it sits in, the same way Lower priority already does for that branch from the Selector above.

A gate sometimes needs both halves at once: take the branch the moment its fact becomes true, and give it back the moment that fact stops holding, with no second authored node. both is the fourth abort mode choice for exactly this: one Condition or Conditional, one per-update check, both effects.

DocumentationReactiveAborts.bqbehavior adds a third branch, investigate plan, between the chase branch and patrol. Its guard, threat is nearby, is a Condition with abort mode set to both, reading a new threat_nearby field.

When threat_nearby becomes true, threat is nearby preempts whatever lower-priority branch is active that same update: the identical Lower Priority takeover already shown above in See it: the higher branch takes over, from this one condition. When threat_nearby then goes false while investigate the threat is running, the same condition cancels its own branch and the Selector falls back through its remaining children: the identical Self cancellation already shown above in See it: a gate dropping its own branch. Both effects come from the one authored node and the one per-update check of its condition; the editor’s abort mode control is the same control used for none, lower_priority, and self, with both as its fourth choice, identical on Condition and Conditional alike.

The Condition’s rail showing threat is nearby with its variable, comparison, and abort mode set to both
Figure 7. One Condition, one abort mode setting, both the Lower Priority takeover and the Self cancellation already shown above. Nothing about either effect changes; both only removes the second authored node a branch needing both used to require.

Result

Success
Nothing here reports Success. Both modes are about stopping work, and the branch that takes over reports its own result.
Failure
A Self gate that stops succeeding refuses its child, so the Conditional reports Failure to its parent.
Running
After a Lower Priority takeover, the winning branch is the Running branch from that update onward.

The scan runs once per update, before the active node ticks.

Lower Priority

  • Opt in on the Selector through Reactive abort > Abort. That one setting covers every Condition and Member condition left at abort mode: none inside its branches; a condition can also opt in on its own instead, directly through its own abort mode field (see Both below).
  • The observing condition has to sit in a branch that has at least one lower-priority sibling, under a Selector with two or more branches. A Lower priority Selector with nowhere to preempt is reported by validation.
  • It fires only when the active node is inside a strictly lower-priority sibling branch of that Selector, and only when the condition has just become Success. A condition that was already true when the branch started does not fire again.
  • On firing, pending work owned by the interrupted branch is cancelled with a Lower Priority reason, the interrupted node and the causing condition are recorded for the Live view, and the cursor descends into the winning branch. Composite cursors, Repeat counts, Time Limit clocks, and Random Selector draws in the interrupted branch are reset.
  • With several conditions becoming true at once, the highest-priority branch wins, then the earlier authored condition within that branch.

Self

  • Opt in on a Conditional, a Condition, or a Member condition through abort mode > self. Each has to sit inside a Selector branch, which is where the cancellation hands control back to: a Conditional cancels the subtree it wraps, and a Condition or Member condition cancels the branch it sits in.
  • A Condition’s fact is evaluated every update, whether or not the branch is the active one. A Member condition calls its bound member only while its own branch is active, because that call shares the one member request channel with the running node. It cancels when the fact stops succeeding while the active node is inside the guarded subtree; a member call that has not answered yet is not an observation and never cancels.
  • On cancelling, pending work owned by that subtree is cancelled with a Self reason and the cursor re-enters the hosting Selector at its first child.
  • A Lower Priority takeover and a Self cancellation in the same update both happen, and the takeover wins the cursor, so a higher-priority branch is never delayed by a gate letting go.

Both

  • Opt in directly on a Condition, Conditional, or Member condition through abort mode > both, the fourth choice beside none, lower_priority, and self. The node must independently satisfy both admission rules above: a Selector branch with a strictly lower-priority sibling, and an enclosing Selector branch it gates. Missing either half reports that half’s own diagnostic.
  • Both effects come from the one condition and the one per-update evaluation: the Lower Priority admission check and the Self cancellation check both read this same observation, never a second evaluation.
  • Baking, binding, and the Live view treat the two effects exactly as they already treat an independently authored lower_priority-moded condition and an independently authored self-moded condition: no new relationship table, no new cancellation primitive. Live shows the same pills shown above: after the takeover the preempted branch reads INTERRUPTED, and after the cancellation the guarded branch reads INTERRUPTED.

Abort mode has the identical four settings on every reactive kind in this release: none, lower priority, self, and both, on Condition, Conditional, and Member condition (the member rail shows the same Abort mode card beside its Interruption response card). A branch that needs both effects from one authored node now sets abort mode to both directly; the two-node shape above (a Self Conditional inside a branch of a Lower priority Selector) remains valid wherever the two effects are intentionally on different nodes, which is still how Guard2.bqbehavior composes its catch branch.

An interrupt tells the tree which branch to run next; it does not, by itself, tell your game which task just lost control. To mark the one task you want to hear about, switch on Interruption response > Response at the bottom of its form (the graph file gains response: true). When a Lower Priority or Self abort then interrupts that task while it runs, whichever of its steps was running, the agent raises BehaviorAgent.InterruptionResponseTriggered once with the task’s identity, and LastInterruptionHasConfiguredResponse reports it for the latest recorded interruption. The package draws nothing on its own: your game subscribes to the event or reads the property, then decides what the response looks like. A task that completes normally raises nothing. Dungeon Heist’s Guard2.bqbehavior switches it on for patrol_sequence, and GuardBehaviorActor subscribes and shows a cyan “?!” over Guard_2. See the Sequence entry for the field.

Guard_2 mid patrol beside the wall when a coin's landing noise reaches it: the cyan "?!" reaction pops over its head the instant patrol_sequence is interrupted, then clears a beat later while the guard investigates, and Guard_2 walks back to its route once the investigation ends.
Guard_2 mid patrol beside the wall when a coin's landing noise reaches it: the cyan "?!" reaction pops over its head the instant patrol_sequence is interrupted, then clears a beat later while the guard investigates, and Guard_2 walks back to its route once the investigation ends.

Guard_2 mid patrol, patrol_sequence carrying response: true: a coin’s landing noise reaches it, the cyan “?!” pops over its head on the very update the interruption is recorded, and the reaction clears again on its own while the guard investigates.

When it goes wrong

SymptomCheckFix
The higher branch never takes over.Read Abort on the Selector that owns both branches.Set it to Lower priority, then confirm the winning branch sits above the losing one.
The interrupt fires once and never again.Check whether the condition stays true the whole time.Nothing to repair. Firing needs a change to true, so let the fact go false before you expect another takeover.
The wrong branch wins.Read the Children list order on the Selector.Move the branch that should win above the branch that should lose.
Validation rejects a Lower priority opt-in.Look for a Selector with at least two branches and a lower-priority sibling below the observing branch.Add the lower branch, or set Abort back to None.
A movement request keeps running after the interrupt.Confirm the movement adapter implements the interruptible service contract.Handle cancellation in the adapter so the character stops when its request is cancelled.
Progress is lost every time the branch is interrupted.Composite cursors and decorator counters in the interrupted branch reset by design.Keep progress your agent must not forget in your own component, and let the graph own the decision.
Full-size image