Upgrading

A package upgrade touches four things at once: the editor, the runtime, your graph files, and the C# generated from them. They are designed to move together, and the work is mostly letting Unity finish.

Before you change the package

1. Read the release notes for the versions between yours and the new one, and note anything about a node you use.

2. Write down the installed package version, from Window > Package Manager or the project manifest. The graph package it depends on comes with it; you never manage that one.

3. Run Reference Scan and keep its verdict. Repairing today’s stale identities now means you can tell them apart from anything the upgrade causes.

4. Close the graph editors that hold unsaved work, so nothing is half-written when package files change.

Let Unity rebuild what it derives

The .bqbehavior graph file is the authored thing. Imported executable caches and generated member providers are derived from it, and the upgrade path expects them to be rebuilt.

1. Install the new package and let compilation and import finish.

2. Open a few representative graphs in Static and read every verdict: validation, member binding, blackboard.

3. Use Save once you understand any offered format upgrade or changed verdict.

4. Run Reference Scan again, which covers closed graphs as well as open ones.

5. Enter Play Mode and attach Live to the newly initialized runtime instances.

A running instance keeps the artifact it initialized from. When the imported graph then changes, Live detaches instead of drawing your new graph beside an old running one, which is why the last step is a fresh attach and not a refresh.

The three version numbers

They are independent, and mixing them up is the most common upgrade confusion.

Number	Where it lives	What it governs
Package version	The package manifest	The installed product release. Release notes and dependency requirements belong here.
Behavior version	The %% behavior-version: header in a graph file	Graph composition. A subgraph and its parent have to be compatible. Leave it alone when you only change the package.
Graph file format	The %% source-format: header in a graph file	Which records the file is allowed to use. The writer raises it only when a feature needs the newer format.

Plain text

%% behavior-version: 1.0.0
%% source-format: bitquirky.behavior/1.9

Older valid graph files stay readable. Leave the format marker to the writer: a bulk rewrite claims records the file may not contain, and lowering a marker while newer records remain breaks the file. Format and migrations has the version-by-version list and the safe migration procedure.

Keep the dependency set coherent

Let Unity resolve the manifest you install. A newer Behavior editor beside an older Graph canvas than its declared dependency is outside the tested set, and the declared versions are on the compatibility page.

Installing or removing the Addressables package changes only whether the optional integration assembly compiles. Your graph files are unaffected.

When game code changed too

A C# refactor compiles happily while saved bindings go stale, because a member identity includes the target type, the declaring type, the name, the access, the parameter order with its modifiers, any generic arguments, plus the value type. Runtime calls are generated, and nothing guesses a replacement member at runtime.

1. Wait for Unity to finish compiling.

2. Run Reference Scan and read every occurrence it lists.

3. Restore the old declaration, repair the individual graphs, or use explicit remapping.

4. Preview a remap, approve only the replacements you recognize, and apply.

5. Scan again for a clean verdict.

One change stays compatible on its own: appending ordinary optional parameters with concrete compile-time defaults, when exactly one longer declaration qualifies. Required parameters, an ambiguous longer declaration, and an optional parameter with no concrete default all need a deliberate rebind.

The state machine lifecycle upgrade

An older action state machine can hold one legacy action list. The current editor maps that list into a read-only Active Update view and preserves its saved bytes, so opening, saving, undoing, and reloading a legacy graph all leave it alone.

Upgrade lifecycle source is the explicit, undoable edit that crosses the boundary. Use it when you intend to author separate Entry, Active Update, and Exit groups. It keeps action identities, order, bindings, run settings, and lifetime, writes the graph file format those phases need, and starts Entry and Exit empty. If the lifecycle controls are still read-only, read the Source compatibility card in the rail and decide whether you want that upgrade at all.

One node worth re-reading after an upgrade

A Repeat on Forever restarts after Success, Failure, or Blocked, and stops when the behavior around it exits. If an older design expected the loop to stop and report Failure, choose Until Failure for that node deliberately. Keep going covers the four policies.

If the upgrade goes sideways

Symptom	Check	Fix
A graph refuses to open and reports malformed text.	Read the earliest parser error and the line it names.	Repair that line in the graph file. The editor refuses to materialize half a graph.
The editor reports a conflict on save.	Use Open diff to compare what you have with what is on disk.	Choose Reload to take the disk version or Keep local to overwrite it.
A member or service no longer resolves.	Read the validation issue, then run Reference Scan.	Rebind in the picker or remap the identity. There is no reflection fallback to cover it.
Live detached itself after an import.	The running artifact and the newly imported one are different identities.	Reinitialize the runtime and attach again.
An entity graph now rejects a value it used to hold.	Compare the value shape with the unmanaged storage rules for entity variables.	Choose a representable shape, move the data behind a component, or run that graph on the GameObject host.
A remap preview refuses to apply.	The scan is stale, the graph changed, or the editor holds unsaved work.	Keep the work you want. Scan again, then remap against the current text.

Next

• Release notes: what changed, grouped by theme.
• Format and migrations: the file format detail.
• Reference Scan: finding and repairing stale identities.