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

Keep going

Repeat runs one branch again and again, with an explicit rule for what finally stops it.

A tree that finishes is a tree that stops deciding. Repeat is the node that keeps a branch alive, with the stopping rule written on the card.

The Platformer enemy walks a route forever. Its Sequence does one lap and reports Success, which would end the tree and leave the enemy standing in place. The naive fix is a while loop in game code, and a while loop cannot be interrupted by the graph.

EnemyPatrol.bqbehavior wraps the whole patrol Sequence in a Repeat instead. The lap finishes, the Repeat starts it again, and the agent keeps making the same decision with fresh facts each time.

  • Keep a decision loop alive for the life of the agent, which is the Forever policy around a root Sequence.
  • Retry until a fact turns true: attempt the interaction with Until Success so a failed attempt is tried again next update.
  • Do something a fixed number of times, like the three patrol points in DocumentationDecorators.bqbehavior, which uses Count with 3.

Horde Survival uses the same controls for a different problem. One enemy has to land three real attacks, keep pursuing until it reaches the keeper, and start its whole decision again after each completed pass. The three Repeat wrappers each surround the branch whose work should recur.

Repeat with the count policy holds one child: visit the next point keeps the running pill pass after pass, and the count lives on the repeat chip above the card rather than on the card itself.
Repeat with the count policy holds one child: visit the next point keeps the running pill pass after pass, and the count lives on the repeat chip above the card rather than on the card itself.

check 3 points counts its child’s completions: one, two, three, then hands the third result to its parent. The counter lives on the running agent, so the status pill returns to the same child once per attempt.

In Horde, Attack Flurry uses Count 3, Pursuit uses Until Success, and the Repeat above Enemy Decisions uses Forever. The selected Live inspector belongs to the decorator pill you clicked; an unselected card still shows its evaluated branch status without claiming that the rail is showing that decorator.

A selected Horde Pursuit Repeat reads Until Success, Running, run 511, and a failed child result.
Figure 1. Selected Pursuit during the real walk: the failed attempt is retried while the decorator stays Running. The moving Live view shows the run number changing beside the game.
  1. Open Assets/Platformer/Behavior/DocumentationDecorators.bqbehavior and select the Repeat called check 3 points.

  2. The rail shows END POLICY with four choices: Count, Until Success, Until Failure, and Forever. This node is on Count.

  3. With Count selected, a Count field appears below it, holding 3. Enter 1 and the decorator becomes a pass-through for one attempt; enter 5 and the child completes five times before the result leaves the node.

  4. Switch to Until Success. The count field disappears, because the child’s own result now decides when the loop ends.

  5. Switch to Forever for a decision loop, then put that Repeat at the root of the tree so the whole tree keeps deciding. EnemyPatrol.bqbehavior is the playable version of that shape: a Repeat on Forever around the patrol Sequence, running on the Platformer enemy.

To inspect the playable Horde example:

  1. In the Horde Survival project, open Assets/_Project/Behavior/HordeEnemy.bqbehavior, select Enemy, then Edit tree. Enemy Decisions sits below the repeat forever pill.

  2. Find Attack Sequence and its Attack Flurry Repeat. END POLICY is Count, and Count reads 3. The distance, contact radius, and cooldown prechecks precede Reset Attack Tally and that pill.

  3. Find Chase Sequence and select the Pursuit decorator. Its END POLICY reads Until Success. In Wander, Acquire Target uses the same policy for the immediate target-lock handoff.

  4. Play HordeSurvival.unity, attach Live to a living enemy entity, and select a Repeat pill. The selected rail reads this decorator’s status, run progress, and last child result. Clear selection to read the evaluated cards without treating another node’s inspector as this Repeat’s status.

The Horde Count Repeat finishes with completed 3 of 3 and attacks_landed at 3.
Figure 2. A finished Attack Flurry keeps its Success result and completed 3 of 3 reading. A later fresh flurry starts a new tally.
Repeat decorating a patrol action with its count policy
Figure 3. The pill on the card is the decorator. One child, one policy, one counter per agent.

In the Horde chapter, three completed attack grants make the Attack Flurry Count finish. Reset Attack Tally clears attacks_landed on the next eligible fresh flurry, and Attack Tally increments it for each grant. ContactDamageSystem applies the actual contact damage that frame; the graph does not deal damage itself. Pursuit retries failed distance checks during the ordinary walk. The Forever wrapper restarts the whole Enemy Decisions Selector after a successful attack or pursuit cycle and after the failed target-lock handoff.

In Horde, watch Pursuit in selected Live while the enemy walks: status reads running, the run number advances after a failed child attempt, and last child result records that failure. On a running Count, progress reads run 2 of 3 when the second attempt is active. Once the third attempt finishes, the selected Count reads completed 3 of 3 with its retained success or failure status; it does not display a new running first attempt. A completed Until Success reads completed without inventing a total. Forever remains running through its child results. If the branch has not run, progress reads not started and the child result may read not observed.

The selected Attack Flurry Count is Running on run 2 of 3 with attacks_landed at 1.
Figure 4. Same Horde enemy on its next eligible flurry: Count 3 is Running on run 2, and attacks_landed is 1 after its first new grant.
The unselected Horde Live graph shows a failed Enemy Decisions Selector with its read-only entity blackboard.
Figure 5. With no decorator selected, the complete Enemy Decisions Selector reports Failure after the immediate target lock. The blackboard shows has_target true; this is the handoff Forever restarts from.

Repeat wraps exactly one child. Every completed attempt increments a counter stored per agent, and a Running child keeps the current attempt open.

Result

Success
Count reached its target on a successful attempt, or Until Success saw the child succeed, or a passed-through attempt result was Success.
Failure
Until Failure saw the child fail or report Blocked, the final counted attempt failed, or stop on failure ended an earlier attempt.
Running
The child is still working, or an attempt just completed and the policy asked for another one.
End policy What it repeats What it finally returns
Count Completed attempts, until the count is reached The last attempt’s own result
Until Success Failed and Blocked attempts Success, from the attempt that succeeded
Until Failure Successful attempts Failure or Blocked, from the attempt that stopped succeeding
Forever Every completed attempt Running, until the branch above it ends or is interrupted

These are the policies with stop on failure off, which is also the default for existing graphs. Turn it on with Count to stop at the first Failure or Blocked attempt instead of waiting for the count, or with Forever to repeat only while attempts succeed. A child that is still Running is not a failure and keeps its current attempt.

Live retains the actual number of completed attempts, not the configured target. An early failed exit from Count can therefore finish before its target, without claiming those unperformed attempts. A containing Repeat can re-arm the branch without erasing its just-finished reading; the retained completion clears when the child branch actually executes again, or when the instance resets.

Switching policies retains the saved stop setting. Under Until Success, a retained on setting ends on the first completed result, whether Success, Failure, or Blocked; switch it off to retry failures. Under Until Failure, the setting is redundant because that policy already stops on failure. The rail explains these retained states rather than changing the source silently. The source parameter is the optional Boolean stop_on_failure; omitting it is the same as false.

  • Running is never an attempt. The counter moves only when the child produces a result.

  • Interrupted, Timeout, and Authority mismatch pass straight through without counting, so a Time Limit above a Repeat still ends the branch.

  • A restart yields for the rest of the update. Without that yield, a child that succeeds instantly would spin through attempts in a single frame; with it, one restart happens per update.

  • Leaving the decorator clears its active attempt counter. Its last completed total remains available to Live until a new execution begins; the new execution starts counting from zero.

  • A selected decorator’s status is that Repeat’s retained result on either an entity or a GameObject agent. The unselected canvas can show a child Failure while Pursuit is still running, because the failed attempt is being retried.

  • Count must be at least 1. The authoring schema rejects zero and negatives.

When it goes wrong

SymptomCheckFix
The agent stops deciding after one pass.Look for a Repeat at the root of the tree.Wrap the root branch in a Repeat set to Forever.
A counting Repeat never finishes.Check whether the child ever produces a result rather than holding Running.Give the child a result, or add a Time Limit so a stuck attempt ends.
Until Success loops forever on a fact that will never turn true.Read the fact the child depends on while the game runs.Wrap the Repeat in a Time Limit, or use Count so the branch gives up.
The count seems to reset at random.Check whether the branch is being left and re-entered, which clears the counter by design.Keep the counter meaningful by placing the Repeat inside the branch that stays active.
The Count field is missing from the rail.Read the END POLICY selection.Choose Count. The field belongs to that policy alone.
The rail says a Count has completed while the card nearby is running.Check which decorator pill is selected and whether that card belongs to the same Repeat.Select the intended Repeat pill; read its retained Status and completed count, then clear selection to follow the current branch.
Full-size image