Push and Return

A guard three quarters of the way along its patrol hears something. It should look, then carry on from where it stood, and an ordinary handoff cannot do that.

The problem

Switch is final. It cancels the work the old mode owned and throws its progress away, which is right for patrolling into defeated and wrong for a distraction. Send the guard from patrol to investigate with a Switch and it comes back to the start of its route every time, because the patrol activation no longer exists.

The fix is a different kind of transition. Push suspends the old mode instead of ending it, and the destination’s Completion > When done set to Return hands the actor back when the distraction is over.

When to reach for it

• A guard that investigates a noise, then continues the same waypoint progress. DocumentationStateTransitions.bqbehavior does exactly this with its noise heard row.
• A reaction that belongs to no single mode: flinch, stagger, a short emote, after which the actor resumes whatever it was doing.
• A brief scripted beat, like a barked line, where restarting the interrupted mode would look like a bug.

See it: the guard leaves and comes back

Figure 1. Patrolling has three ways out. Only the Push to investigating intends to give the mode back, and its edge says · push on the canvas.

Do it

1. Open Assets/Platformer/Behavior/Tutorials/DocumentationStateTransitions.bqbehavior and select the transition noise heard.

2. Read the Kind card. When taken is Push, and the caption under it states the deal: the source is suspended at its current row without Exit, work already in flight may finish, and the group waits for Return.

3. Read On return, which appears only for Push. It is set to Resume, so patrolling continues the exact activation it left.

4. Select the destination state investigating and read Completion > When done. It is Return, which is the half that gives the guard back. Without it, the investigation would sit there holding the actor.

5. Give the destination finite work. investigating has one check the noise row, and its Active Update card sets Lifetime to Once, so the group reaches a terminal result and Return can happen.

6. Enter Play Mode, let the patrol get part way along, then set noise_heard true.

Figure 2. The caption under When taken is the contract: suspended at its current row, no Exit, waiting for Return.

You should see

investigating becomes the active mode while patrolling keeps its cursor and its owned progress. The machine rail’s Runtime card reads one under Suspended. When the investigation finishes, its Exit gets one update, patrolling becomes active again without running its Entry, and the patrol continues from the same point rather than the beginning.

Change one thing

Set On return to Re-enter and reproduce the same interruption. patrolling now runs Entry and starts a fresh Active Update pass when it comes back. That is the setting to use when resuming stale work would be unsafe, for example when the investigation moved the actor into a different navigation region.

How it decides

What Push preserves

• The source mode and its scheduler cursor, so the row that was running is still the row that is running.
• Direct action progress, hosted behavior tree cursors and cycle counts, and an active referenced-machine selection.
• Pending request identities, which is why an operation still in flight can finish and be picked up on Resume.

Push runs no Exit group on the source. Exit belongs to a final handoff, so it happens when that mode is eventually left through a Switch, a Finish, or its own Return.

What Return does

Return happens when the pushed destination reaches a terminal Active Update result, no transition claims it, and its Completion is Return. The destination’s Exit group gets its one bounded update, then one suspended activation is popped.

• Resume restores the preserved activation and runs no Entry. Pending identities and progress go back to belonging to it.
• Re-enter restores the mode and runs Entry, starting a fresh Active Update activation.

Nested pushes pop last in, first out. The stack is runtime progress and grows itself when a deeper push needs room, so a push that arrives before the buffer has grown keeps the current mode running and lands on the following update.

What clears the stack

A Switch transition, a reset, or a whole-graph replacement discards suspended activations and cancels the work they owned. Late completions from that abandoned work cannot take control back.

A Return with nothing suspended finishes the machine instead of popping: the machine reports no result and stops. Author Return only on a mode that a Push can reach, and give the machine an ordinary route out of that mode if it can also be entered directly.

Self transitions are the other half of re-entry

A row whose From and To are the same state has a Re-entry card instead of On return. Restart runs the normal Exit and Entry handoff and starts the mode over; Resume keeps the progress and runs neither group. Transitions covers that card in place.

When it goes wrong

When it goes wrong

Symptom	Check	Fix
The actor never comes back.	Read the destination’s Completion row, then read its Active Update in Live.	Set Completion to Return, and make sure the work reaches a terminal result instead of holding Running.
It comes back to the start of the mode.	Read On return on the Push row.	Set it to Resume. Re-enter deliberately discards the preserved progress.
Cleanup from the interrupted mode never ran.	Confirm the row that fired is a Push.	Nothing to repair. Push skips Exit on purpose; put work that must happen on every departure in the destination’s Entry instead.
The machine stops entirely after a Return.	Read the Runtime card: Suspended reads zero before the Return.	Give that mode a reachable Push, or change its Completion to Stay or Finish.
A transition keeps winning before Return can happen.	Read the destination’s own outgoing rows and the machine’s Any State rows.	Completion applies only when no row matched, so narrow the predicate that keeps claiming the boundary.
Suspended progress disappeared.	Look for a Switch or an Any State row that fired while the stack was deep.	A Switch discards the whole stack. Make the global interrupt a Push if the interrupted mode must survive it.

Next

• States and lifecycle: Completion in full, beside Entry and Exit.
• Referenced machines: a whole machine as the mode that gets suspended.
• Transition reference: Kind, On return, Re-entry as fields.