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

Reference Scan

Find every graph in the project that still names a member, field, service, or node type you renamed, then remap them under review.

You renamed a method. Somewhere in the project, a graph you have not opened for a month still names the old one. Reference Scan reads every saved graph and tells you which ones, then rewrites the ones you approve.

Platformer’s patrol binds AdvancePatrol(List<Vector2>, PatrolProfile, string). Rename that method and the binding goes stale, which is the honest outcome: the saved binding is an exact identity, so no nearby overload is substituted behind your back. Opening the graph shows the problem clearly, and opening every graph in the project to find them all is the part nobody does.

Reference Scan covers the graphs you did not open. It reads saved text from disk, so a closed graph and a graph with import errors are both in scope.

  • After renaming, moving, or resharing a C# member that graphs bind.
  • After removing a service token or a blackboard field that graphs consume.
  • Before a release, as a check that no graph in the project still names something that no longer exists.

One rename, three steps, in the real window.

  1. The Reference Scan window scanning, three of twenty-nine graphs read, every facet count still zero
    Figure 1. The Reference Scan window scanning, three of twenty-nine graphs read, every facet count still zero

    The scan reads saved text from disk, graph by graph. The facet counts stay at zero until a finding exists.

  2. The verdict reading one stale reference in one graph, with a GuardAdvance finding on its advance node and a truncated member identity
    Figure 2. The verdict reading one stale reference in one graph, with a GuardAdvance finding on its advance node and a truncated member identity

    The verdict names the count, and the row names the graph, the node, the kind, plus the stored identity GuardMotor.AdvanceRoute. Select the row and the reason appears beside it, no method AdvanceRoute on GuardMotor. The footer keeps the scale and the contract in view: the graphs that run scanned, the references it checked, read-only.

  3. The remap plan with the stale game-code member identity, its occurrence count, and a replacement not yet chosen
    Figure 3. The remap plan with the stale game-code member identity, its occurrence count, and a replacement not yet chosen

    The plan groups every occurrence of one stale identity under one choice: Choose one current definition for a stale identity. Every occurrence follows the same mapping. Until you pick one the row reads Choose replacement… and the footer reads No mappings approved.

The Reference Scan window reporting one stale member on the Platformer patrol graph
Figure 4. One deliberately changed saved identity produces one member finding. The row names the graph and the node that owns it, its kind, plus the reason the identity no longer resolves.
  1. Open Tools > Behavior & State > Scan Project References. The window is titled Reference Scan and starts at rest: opening it scans nothing.

  2. Read the scope line and the READ-ONLY chip. The scan checks every authored graph in the project, behavior trees and state machines alike, open or not, and the whole surface stays read-only until you press Remap stale references.

  3. Choose Scan project.

  4. Wait for one verdict: everything resolves, findings exist, or the result is incomplete because named graphs could not be read. An incomplete result is never a clean result.

  5. Select a finding to read its stored identity and reason. It also names the graph and the line, plus the node when one owns it.

  6. Choose Open in editor to look at the context. Navigation changes selection and nothing else.

A graph is scanned when it sits under the project’s Assets/ tree, or inside a package Unity classifies as Embedded. Dependency packages are excluded, and a source Unity cannot classify fails closed. To include a package you own, embed it in the project first.

Kind What is checked
TASK TYPE The authored node-kind token and its current task shape
MEMBER Target, declaring type, member, access, parameters and modifiers, generic arguments, notification, plus the value or return type
BLACKBOARD FIELD The authored name, and a stored expected type where the file carries one
SERVICE The authored service token against current declarations and task use

One node can store several references, and every occurrence is kept, even when the same stale identity appears twice on one line. A finding without an honest node owner, like a declaration or a graph-level projected binding, locates the graph instead of selecting an unrelated card.

Reference Scan is not a second validator. An unassigned object reference, a runtime-only target failure, a stale generated provider, or a conversion problem that left the identity intact belongs to validation.

  1. From a completed result, choose Remap stale references. Occurrences of the same exact stale identity group under one choice, viewable By identity or By graph, sharing one plan.

  2. For each identity, choose Choose replacement…, search the current candidates, and read the compatibility. An incompatible candidate stays visible with its refusal reason.

  3. Select a candidate and choose Set replacement. Confirm the mapping reads APPROVED. Nothing is preselected, and similarity only orders the list.

  4. Choose Review before apply. The review states how many references in how many graphs will change, promises other lines stay untouched, and lists every blocked graph as BLOCKED with its reason.

  5. Choose Apply remapping. Anything left unapproved, ambiguous, or invalid stays stale and is not written.

If search does not offer the definition you intend, keep the same picker open:

  1. In Name a replacement, type Type.Member or Namespace.Type.Member for a game-code member, a task-kind token for a task type, or the declared name for a blackboard field or service. Choose Find.
  2. Read every matching definition and overload, including definitions in other loaded assemblies. Typed names receive the same compatibility check as searched candidates. An incompatible match stays visible with its refusal reason; a name with no definition reads no current definition named followed by the name you entered.
  3. Select the intended row and choose Set replacement. Finding a name never selects or approves it for you. Continue with Review before apply and Apply remapping to repair every occurrence governed by that mapping through the normal pass.

Clear Name a replacement to return to the existing candidate search. The ordinary search is unchanged while the typed field is empty.

If a member kept its name but its parameter types or return type changed, scan again and open its replacement picker. The same-named current overloads are offered alongside renamed members:

  1. Choose the intended signature and read its compatibility. A change from int to float can be remapped when the parameter count and every ref, out, in, or params modifier stay the same and the existing arguments still convert.
  2. Choose Set replacement, then Review before apply and Apply remapping. The pass updates that binding’s saved parameter type identities and return type identity together. Authored argument records, unrelated bindings, layout, comments, and settings stay untouched.
  3. Scan again to confirm the repaired binding is no longer listed.

A changed parameter count or modifier is not a remap. The incompatible row names the first changed parameter, using its zero-based ordinal, and says which argument needs authoring. An added parameter needs an argument authored in the graph; a removed parameter needs the remaining arguments reviewed there. If an existing constant or blackboard argument cannot convert to the new type, the picker shows the member resolver’s own conversion refusal. Nothing is written for that incompatible mapping.

Behavior Trees and State Machines provides the saved-reference repair outcome associated with NodeCanvas’s [fsMigrateVersions], without requiring that attribute on your C# types. Graphs store authored task-kind tokens, so renaming a task’s implementing class while keeping its token needs no migration. A changed task token, member declaring type, member name, or compatible signature is repaired through the reviewed remap pass, including a replacement you name yourself.

This does not migrate arbitrary serialized C# object data or invent arguments. Added or removed parameters and changed modifiers must be authored in the graph. Existing argument values are retained, not replaced to make a conversion pass; an incompatible conversion needs your authored change before the binding can resolve.

Before a graph is ready, remapping confirms that the saved text still matches what the scan read, the asset exists and is writable, each occurrence still stores the expected stale identity, the replacement can be written at that exact position, and the rewritten graph parses.

Apply closes open graph editors first, then replaces each graph atomically through a temporary file. A blocked or failed graph stays exactly as it was while independent ready graphs complete, and the result separates REPAIRED graphs from ones that are still stale or blocked. Apply writes outside the editor’s undo history, so the graphs it rewrote are recovered from your own project backups.

After applying, choose Scan project again. The fresh verdict catches unapproved mappings, save failures, and definitions that changed while you were reviewing.

A renamed class used to leave every graph binding under it stale with nothing to approve, because the candidate search stopped at a declaring type that no longer resolved. It now looks past that and matches the renamed class’s own members by shape, so a renamed declaring class repairs through the same Remap stale references flow as an ordinary renamed member.

  1. In Unity’s Project window, rename the class’s script to match its new name. Then rename the class itself in any code editor. Choose Scan project. Every binding under the old class now reports MEMBER, naming the reason the stale identity no longer resolves.
The pace_smooth node in CpuRace.bqbehavior selected in Static, reading missing: SmoothPaceGap, with the Target card showing PacingDocCapture095 target type no longer resolves and a Reselect button
Figure 5. Racing Line’s pace_smooth node with a deliberately stale declaring-type identity: the node reports the missing member and the Target card names the unresolved class.
  1. Choose Remap stale references. For each of the renamed class’s stale member rows, choose Choose replacement…, pick the renamed class’s matching member, and choose Set replacement to confirm it reads APPROVED: approving one row repairs only that row, so repeat until every row under the class is approved. Choose Review before apply, then Apply remapping. Every approved occurrence under the renamed class repairs in that one pass, including a sibling binding whose own argument only restates another binding’s result: that reused-result occurrence is confirmed current by re-resolving the rewritten source, not written a second time.
The pace_smooth node using the canonical Pacing.SmoothPaceGap binding, with the Target card resolved to Pacing
Figure 6. The canonical binding shown for comparison: the Target card names the current Pacing class. This image uses the restored source rather than a recorded remapping pass.

A removed-and-replaced blackboard variable repairs the same way. Declare a replacement through the Blackboard panel’s own declare-variable control, remove the field it replaces, then run the scan: the candidate search offers the newly declared variable alongside anything restored from a saved %% fields: line, so a node that read or wrote the removed field approves it and repairs through the same remap flow above.

When it goes wrong

SymptomCheckFix
No graphs are in scope.Read where the graphs live and how Unity classifies that package.Move authored content under Assets/, or embed the package you own.
The result says incomplete.Read which graph could not be read.Repair that file, then run a fresh scan. Zero visible findings on an incomplete run means nothing.
A candidate cannot be approved.Read its kind and the compatibility reason.Pick a definition of the same kind with a compatible shape, or repair that graph by hand.
Review says the source changed since the scan.Something saved that graph after the scan read it.Cancel and scan again so the coordinates are current.
Apply reports a save failure.Read the per-graph result.That graph is unchanged. Fix the file permission or the disk problem, then rescan before retrying.
A build still fails after a clean remap.Read the graph’s own validation and the generated provider state.Reimport so generated direct calls rebuild, as in Addressables and builds.
Full-size image