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

States and lifecycle

Put setup, ongoing work, and cleanup in the group where each belongs, then choose how the group runs and when the mode counts as done.

A stomped Platformer enemy has to stop moving, stop hurting the player, and look defeated. A state gives each of those jobs a place to live and a moment to happen.

Cleanup is where modes go wrong. The enemy takes the stomp, the graph moves to the defeated mode, and the character keeps drifting along its patrol because the code that stops movement never ran. The same failure in reverse is a mode whose setup runs every frame instead of once, so an animation restarts forever.

EnemyStateMachine.bqbehavior in the Platformer sample answers both with grouping. Patrolling advances the patrol while it is the mode. Defeated stops movement, makes the enemy harmless, and applies the defeated look, all in Active update, all once.

  • A mode with one-time setup: acquire a target, start an animation, raise a flag your components read.
  • A mode with finite work whose end matters, like the Platformer guard walking to its post before the machine moves on.
  • A mode that owes the next mode a clean handover: clear movement intent, release a reservation, hide a marker.
Entry runs both of patrolling's actions Together and reports Complete once; Active Update then starts its single Once pass and holds Running.
Entry runs both of patrolling's actions Together and reports Complete once; Active Update then starts its single Once pass and holds Running.

DocumentationStateControlsLive.bqbehavior gives patrolling two Entry actions, raise the alert and face the patrol route, with Run set to Together. The rail is the honest readout: the group header goes from Entry 2 Running to Entry 2 Complete while Active Update 1 Running pass 1 takes over below it, and Exit 0 Waiting sits untouched until something takes the mode away. On the state card itself only one row shows the running pip at a time, so read the group header rather than the card rows when work is genuinely overlapping.

The defeated state’s rail during Play Mode, after the stomp
Figure 1. The clip above walks patrolling; this still is the same reading on a different mode of a shipped graph. After the stomp, each row in the Platformer enemy’s defeated mode carries its own result and the group above them reads Complete.

DocumentationStateTransitions.bqbehavior under Assets/Platformer/Behavior/Tutorials/ has a state built to be read: alarmed owns all three groups.

  1. Open the graph and select the alarmed state. The rail opens with SELECTED · STATE, the editable name, then the three lifecycle cards.

  2. Read Entry. Its caption says “Runs once when the state becomes active.” Two rows sit under it: sound the alarm and call for backup.

  3. Read the Run row on that same card. It is set to Together, which is why both alarm rows advance in the same update. Switch it to In order and the second row waits for the first.

  4. Read Active update. It holds one row, sweep the area, so there is no Run control to choose. Lifetime is Repeat, so the row starts a new pass after each completed one.

  5. Read Exit. clear the alert sits there, and the group’s caption says it runs once when switching, finishing, or returning.

  6. Select the action sound the alarm on its own. Its Action card names Group, Position as 1 of 2, and Owning state, and a Group execution card below repeats the group’s Run value, so a row always tells you which group owns it.

  7. Select the investigating state and read Completion > When done. It is set to Return, which is the setting Push and Return needs.

The alarmed state’s rail, from its identity header through its Entry, Active Update and Exit groups to Completion
Figure 2. Three groups, one state, named at the top of the rail. Each carries its own rows, its own caption, and the settings that belong to it.
The Group execution card on the sound the alarm action
Figure 3. A selected row names its Group, its Position as 1 of 2, its Owning state, and the group’s Run policy.

A state with one row shows no Run control, because there is no order to choose. Add a second row and the control appears.

One direct Active Update action inside the patrolling state
Figure 4. A direct action carries its own lifecycle group. The card on the canvas shows which mode owns it.

Lifecycle

Enter
Runs once per fresh activation, before Active Update. A Running Entry row keeps the state in Entry, and a failed row stays visible as the group's result instead of being skipped. Entry has no Lifetime, because once per activation is already its rule.
Active
The mode's work, from direct action rows or one hosted behavior tree. In order advances one unfinished row at a time; Together advances every unfinished row in the same update. Once holds the terminal result; Repeat starts a new pass on the next update.
Exit
One update, after a transition latches and before the destination's Entry. Unfinished work is canceled and unreached In order rows are marked skipped. An empty Exit skips the dedicated update entirely.
Finished
A terminal Active Update result that no transition claimed. Completion decides: Stay keeps the mode, Return pops the activation a Push suspended, Finish ends the machine with Success, Failure, or the result the mode just produced.

Run

  • In order starts one unfinished row at a time. A row that succeeds while later rows remain reports Running for the group, so the next row begins on the following update. A non-success terminal result stops the group and becomes the group’s result.
  • Together advances every row that has not finished during the same update. The group succeeds when all rows succeed; the first non-success terminal result cancels unfinished peers and becomes the group result. This is group scheduling on one update, so your code still runs on the host’s own thread.

Lifetime, on Active Update only

  • Once keeps the terminal result. An On finish transition or a Completion policy can then read it.
  • Repeat begins a new pass on the next update after Success or Failure, unless a transition latched first. Each completed pass is an On iteration boundary.
  • A state with no Active Update rows reaches an empty successful boundary immediately, which is how an actionless mode still gets its transitions and Completion evaluated.

The handoff order

A latched transition does not cut the current update short. The transition fires, Exit is deferred, the source gets exactly one Exit update, and the destination’s Entry starts on the update after that. The rail spells the same sequence out under Lifecycle.

Completion

When done What happens
Stay The mode stays active. Once holds its result; Repeat starts another pass.
Return Exit gets its one update, then the activation suspended by the matching Push becomes active again. Returning with nothing suspended finishes the machine instead: it stops with no result.
Finish Exit gets its one update, then the machine finishes with Success, Failure, or Use result, which publishes the terminal Active Update result.

A State can own one more rule: a minimum active duration that gates its own outgoing transitions until that much time has passed since it became active. Racing Line’s CPU recovery companion uses it so a car cannot bolt back onto the route the instant its fall animation ends. CpuRecoveryMode.bqbehavior’s recovering state authors min_active_seconds: 2.2 right in the graph file, directly beside its other parameters.

Plain text
%% parameters: { action_execution: sequence, action_lifetime: once, min_active_seconds: 2.2 }
recovering["recovering"]:::state

To set it in Static, select the State on the canvas. Its rail carries a Minimum active time card, just above the card that orders the State’s outgoing transitions, with a minimum active seconds field: type the number of seconds, press Enter, and save. The card’s caption says what the number does: above 0 it reads This state's outgoing transitions wait until it has been active this long. 0 means no minimum., and at 0 it reads No minimum: this state's outgoing transitions can fire as soon as it is active. The edit is one undo step and writes min_active_seconds into the State’s own %% parameters: line, exactly as above; entering 0 removes the parameter, because absent already means no minimum. A negative, non-numeric, or empty entry is refused in place and leaves the graph unchanged, and the caption says what it needs: minimum active seconds requires a number of at least 0. Enter 0 for no minimum. Only a plain State carries the field: the Entry State, Any State, a referenced state machine, and transitions do not. In Live the card is gone, and the running value reads in the rail’s Live values section instead.

The State Machine window’s STATE group with min_active_seconds raised from its authored 2.2 to 6 on car-cpu-1’s companion
Figure 5. car-cpu-1’s companion, attached Live. The State Machine rail’s own Live values section carries a STATE group with transition values and the selected State’s own min_active_seconds (the active State’s when nothing else is selected), here raised past its authored 2.2. Live values walks the edit step by step.

The authored window here is a real 2.2 seconds, too fast to type a number into by hand once the state is running, so tune it before it runs. Click recovering on the Live canvas while driving is still active: the STATE row follows your selection, reads recovering 2.2 with min_active_seconds on a quiet line beneath, and an edit there governs recovering’s next activation on that one instance. Live values then makes car-cpu-1 leave the road with the window’s per-follower pause and watches the longer hold.

During the countdown, car-cpu-1's companion has recovering selected and its min_active_seconds typed from 2.2 to 6. Its driving graph is paused one second after the lights go out, so the car misses the first corner and drops off the route; back on the companion, recovering stays active for the edited six seconds while the car waits motionless on the road, then hands back to driving.
During the countdown, car-cpu-1's companion has recovering selected and its min_active_seconds typed from 2.2 to 6. Its driving graph is paused one second after the lights go out, so the car misses the first corner and drops off the route; back on the companion, recovering stays active for the edited six seconds while the car waits motionless on the road, then hands back to driving.
A state's own duration gates its transitions per instanceTwo lanes, one per running car, both entering the recovering state at zero seconds. Each lane has a clock bar for its own min_active_seconds and a locked transition to driving. car-cpu-2 keeps the authored 2.2 seconds: its bar fills to 2.2, its lock opens, and driving becomes active. car-cpu-1 carries a live edit of 6 seconds: its bar keeps filling past 2.2 while its lock stays shut, until 6 seconds, when its lock opens and it moves to driving. The edit on car-cpu-1 never changed car-cpu-2's clock.both cars enter recovering at 0 sone clock per running instancecar-cpu-1min_active_seconds6 · live editrecovering6 sdrivingcar-cpu-2min_active_seconds2.2 · authoredrecovering2.2 sdriving0 s2.2 s6 s8 s0 to 2.2 sBoth cars are inside recovering. Every transition out is locked.2.2 scar-cpu-2 reaches its authored window and is free to leave. car-cpu-1 keeps holding.6 scar-cpu-1 reaches its edited window and leaves too. Nothing about car-cpu-2 changed.A state's own duration gates its transitions per instanceTwo lanes, one per running car, both entering the recovering state at zero seconds. Each lane has a clock bar for its own min_active_seconds and a locked transition to driving. car-cpu-2 keeps the authored 2.2 seconds: its bar fills to 2.2, its lock opens, and driving becomes active. car-cpu-1 carries a live edit of 6 seconds: its bar keeps filling past 2.2 while its lock stays shut, until 6 seconds, when its lock opens and it moves to driving. The edit on car-cpu-1 never changed car-cpu-2's clock.both cars enter recovering at 0 scar-cpu-1min_active_seconds6 · live editrecoveringdriving6 scar-cpu-2min_active_seconds2.2 · authoredrecoveringdriving2.2 s0 s2.2 s6 s8 s0 to 2.2 sBoth cars hold; every exit is locked2.2 scar-cpu-2 may leave; car-cpu-1 keeps holding6 scar-cpu-1 reaches its edited 6 s and leaves
Two cars enter recovering together. Each one holds its own clock against its own min_active_seconds, so the live edit on car-cpu-1 stretches only its hold. The transition out stays locked until that instance’s own window has passed.
Game view showing car-cpu-1 held motionless at neutral input under the extended hold
Figure 6. The effect, once recovering is active: car-cpu-1’s physical fall and bounce already finished, but the graph keeps its input neutral until the edited 6 second mark instead of its usual 2.2. car-cpu-2, never touched and off this single-car follow camera’s frame, keeps racing the whole time, confirmed by car.state cpu-2 rather than by this still.

Stop Play Mode and reopen the saved graph: min_active_seconds still reads its authored 2.2, in the recovering State’s Minimum active time card and in the source. The edit lived on the one running instance and nowhere else.

CpuRecoveryMode.bqbehavior reopened in Static with the recovering state selected; the rail’s Minimum active time card still reads minimum active seconds 2.2
Figure 7. CpuRecoveryMode.bqbehavior reopened in Static with the recovering state selected; the rail’s Minimum active time card still reads minimum active seconds 2.2

How the gate decides

  • Absent or 0 leaves the state’s outgoing transitions ungated: the ordinary rules in transitions apply with no extra wait.
  • The clock starts counting from the moment the state becomes active, and resets on every fresh activation, including a self transition that restarts it.
  • The clock only advances while the state is active and its host is actually ticking; pausing the follower freezes it exactly where it stood.
  • Every outgoing transition stays blocked, Continuous, On finish, and On iteration alike, until the clock reaches the parameter’s value. Active Update and Completion run on their own schedule underneath; the gate only holds the transitions back.
  • Two running instances of the same graph each own their own clock. Editing one instance’s min_active_seconds through Live never touches the other.

When it goes wrong

SymptomCheckFix
Setup work runs over and over.Read which group the row sits in on the action’s own rail.Move it to Entry with the Group row, or give Active Update Lifetime Once.
Cleanup never happens.Read whether the transition that fired is Switch or Push, then confirm the row is in Exit.Push suspends without Exit, so put final cleanup behind a Switch handoff.
Only the first Exit row ran.Read Run on the Exit group.Exit gets one update. In order stops at the first row that does not succeed immediately and skips the rest, so use Together when every row must get its turn.
The mode never finishes.Read the Active Update group in Live and find the row that still reads Running.Either let that operation complete or give the mode a Continuous transition that can take it out.
An On finish transition never fires.Read Lifetime on Active Update.Set it to Once. A Repeat group produces iteration boundaries and never a finish boundary.
The lifecycle controls are read-only in Static.Look for a Source compatibility card reading Legacy action list.Press Upgrade lifecycle source once. The graph keeps its current order, Run, and Lifetime, and the three groups become editable.
The State has no Minimum active time card.Read the selection header and the mode. Only a plain State carries the card; the Entry State and Any State carry none, nor does a referenced state machine, and Live hides it.Select a plain State in Static. A legacy action list State takes the duration without the lifecycle upgrade. In Live, edit the running value in the Live values STATE row.
Full-size image