Reuse a branch

Copy a branch into four trees and you will fix a bug in three of them. A Subgraph node points at one saved tree instead, so the branch has a single home.

The problem

Three guard types share one chase routine and disagree about everything else. Copy and paste gives each of them its own copy of the chase, and the first time the chase changes, somebody has to remember which trees to open. A month later they have drifted.

DocumentationLeafNodes.bqbehavior shows the alternative: its fourth step is a Subgraph pointing at DocumentationPatrolSubgraph.bqbehavior, which holds the shared patrol work on its own canvas.

When to reach for it

• A routine several agent types share: chase, flee, interact with a device.
• A branch big enough to deserve its own canvas, so the parent tree stays readable at a glance.
• Work a second designer owns. They edit the referenced tree; your parent tree keeps its own priorities.

See it

Figure 1. One card stands in for a whole tree. The referenced graph is edited in its own window.

In Live, the active path runs through the Subgraph position and continues into the referenced tree’s nodes, because composition folded them into the same running tree.

Do it

1. Create the reusable tree with Assets > Create > Behavior & State > Behavior Tree and keep its root focused on one decision. DocumentationPatrolSubgraph.bqbehavior holds exactly one action.

2. In the parent tree, add a Subgraph node where that decision should happen.

3. Select it and fill in graph address with the referenced tree’s stable project identity. In the fixture that address is 9b996ba6517f94fadba96f7b45c0a380, which is the referenced asset’s project identity rather than a file path or a display name.

4. Save. Validation resolves the reference as part of loading the parent, so an address that cannot be resolved is a validation error you see before Play Mode.

5. Edit the referenced tree in its own window when the shared decision changes. Every parent that points at it picks up the change on its next load.

6. Run a parent agent and watch Live. The active path crosses the Subgraph card and continues into the referenced tree’s nodes.

You should see

The parent agent runs the referenced branch as if those nodes had been authored in place, and the status pill travels into them. One authored tree, many agents, each with its own cursor.

Change one thing

Point a second tree at the same address, then change one action in the referenced tree. Both parents change. That is the whole return on this node, and it is worth feeling once before you rely on it.

How it decides

A Subgraph has no result rule of its own. The referenced tree’s root reports, and that result flows to the Subgraph’s parent.

Result

Success

The referenced tree's root reported Success.

Failure

The referenced tree's root reported Failure or Blocked, or resolution left the reference unusable.

Running

The referenced tree is still working.

• Loading resolves the reference and folds the referenced tree’s nodes, declared values, and bindings into one parent executable before the bake. There is no second graph instance at runtime.
• Each agent gets its own cursor through that composed tree. Sharing the authored asset never shares execution state.
• Missing addresses, a referenced graph of the wrong kind, an invalid nested root, and reference cycles all block composition or the bake, with the problem reported rather than worked around.
• Behavior tree Subgraph has no input, output, or two-way variable mapping surface in this release. Keep a reusable branch on declared values and bindings that compose cleanly with the parent. Per-candidate overrides exist on Referenced State Machines.
• There is no runtime subtree swap and no subtree pool. BehaviorAgent.ReplaceGraph replaces the agent’s whole graph, cancels the previous graph’s owned work, and starts a fresh instance.

When it goes wrong

When it goes wrong

Symptom	Check	Fix
Validation reports an unresolved reference.	Compare the graph address against the referenced asset identity.	Paste the address the graph-authoring workflow gives you for that asset.
A state machine cannot be referenced here.	Read what kind of graph the address points at.	Reference a behavior tree from a behavior tree, and use a Referenced State Machine for a machine.
Composition reports a cycle.	Follow the chain of references out of this tree.	Break the loop; a tree cannot reference itself through any depth.
Changes to the referenced tree do not show up.	Confirm the parent reloaded after the referenced asset changed.	Reimport the parent graph and let the bake run again.
You want to pass a value into the referenced branch.	The node has no mapping surface in this release.	Share the fact through a declared value both trees read, or keep the varying part in the parent.

Next

• Actions and conditions: what usually lives inside a reusable branch.
• Graph files: what an import resolves and what the bake leaves behind.
• Subgraph reference: the field and its rules.