Run a state machine
A Behavior Tree node runs a separately authored State Machine in place, so a self-contained routine keeps its own states out of the parent tree.
On this page
A guard’s search routine has its own states: close in, check the last known spot, give up and report back. That routine deserves its own machine, not three more branches tangled into the chase tree.
The problem
Section titled “The problem”Fold a self-contained routine’s states into the parent tree and the tree grows a branch per state, each one gating the next with a condition that really belongs to the routine, not the chase. The routine’s own transition rules get copied across every tree that needs it, and the first time one of those rules changes, somebody has to remember which trees to edit.
DocumentationHostedStateMachineLive.bqbehavior keeps the split visible: a Hosted State Machine node stands in for the whole routine, addressing DocumentationHostedStateMachineTargetLive.bqbehavior on its own canvas.
When to reach for it
Section titled “When to reach for it”- A routine with its own states and transitions: search and return, a multi-stage alarm, a vendor’s haggling sequence.
- A machine you already authored for one agent, dropped into a tree that should own only when the routine starts, not what happens inside it.
- A state machine’s own interrupt and lifetime rules (Any State, Push and Return) are the right tool for the routine, and a tree’s priorities are the right tool for the parent.
See it
Section titled “See it”

Both pictures follow one GameObject agent across two updates, and the SUCCESS stays on the node’s card after the run moves on. If a higher-priority branch takes over first, the card reads INTERRUPTED instead and the machine is released. The referenced machine’s own nodes never appear on the host tree’s canvas: the host node is the whole story there.
-
Author the routine as its own State Machine asset with Assets > Create > Behavior & State > State Machine. Mapping a terminal state or normal completion to Success or Failure is optional: a routine that just runs out of transitions reports Success on its own, with no Result events required.
-
In the host tree, add a state machine host node (under REFERENCES) where the routine should run.
-
Select it and use the Choose a state machine… field to assign the referenced machine. The node is named by the machine it runs, never by its address.
-
Optionally, under Result states, use the Success state and Failure state choosers to pick a state from the referenced machine directly: the host stops the routine and reports that result the moment it enters the chosen state, whether or not that state finishes the routine on its own. Leave a chooser on Machine’s own result to report however the machine finishes instead.
-
Save. Validation resolves the address and rejects a Behavior Tree address, exactly as it rejects an unresolved one; a chosen success/failure state that does not exist in the referenced machine is rejected the same way.
-
Run a host agent and watch Live. The node’s status pill reads RUNNING while the referenced machine works, then reports the result the moment the machine settles or the host’s own chosen state is reached.
How it decides
Section titled “How it decides”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.
- The host’s own chosen success/failure state (if set) takes precedence over everything else: the moment the hosted instance enters it, the host stops the routine and reports that result, even if the state is an ordinary state with no completion marker of its own. Two host nodes addressing the same machine can choose different states and settle to different results.
- The referenced machine’s own nodes are never flattened into the host: it keeps its own baked artifact, addressed by the node, not merged in at bake time (unlike Subgraph).
- 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.
- 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.
- A member call authored inside the referenced machine binds its own member declarations and its own provider, never the host tree’s.
When it goes wrong
Section titled “When it goes wrong”When it goes wrong
| Symptom | Check | Fix |
|---|---|---|
| Validation rejects the address. | Read what kind of graph the address points at. | Address a State Machine asset from a Hosted State Machine node; use Subgraph to address a Behavior Tree instead. |
| A result state chooser reads Missing state. | Read the help line under Result states: it names the referenced machine and the state it no longer has, the same sentence validation reports. | Choose a state that exists in the referenced machine, or set the chooser back to machine’s own result. |
| The routine restarts from its entry state every time, even mid-routine. | Confirm whether a higher-priority branch preempted the host node before the referenced machine settled. | This is the designed behavior: interruption never resumes. Keep state the routine must survive on a host-declared value instead. |
| A value the referenced machine reads never updates. | Compare the declared value’s name and kind on the host and on the referenced machine. | Seeding matches by exact name and kind; rename or retype one side to match the other. |
| The node settles to Success and you expected Failure, or the reverse. | Read which state the referenced machine actually reached: a Failure-mapped state, or an unmapped dead end. | An unmapped dead end is always Success (plain normal completion), regardless of which state it is. |
- A tree inside a state: the opposite composition, a state that runs a whole tree.
- Reuse a branch: the Behavior Tree equivalent, which flattens the referenced tree in instead of addressing it in place.