Scanning and scopes

Scan scopes

Every scan runs against one scope, exposed in the API as ScanScope.

Scope	What it covers	Typical use
OpenScenes	Only the scenes currently loaded in the editor	Tight edit loop while working in a scene
AllScenes	Every scene asset in the project, without opening them	Catching breakage in scenes nobody has opened recently
AllPrefabs	Every prefab asset in the project	After a refactor that touched prefab structure
AllScriptableObjects	Every ScriptableObject asset	After moving or renaming data assets
EntireProject	Scenes, prefabs, and ScriptableObjects together	Pre-release validation, first pass on a new project
ChangedOnly	Only assets that changed since the last scan	Repeated re-scans during a fixing session

AllScenes is the one worth understanding: it validates scenes without opening them, by reading the serialized scene data directly. On a project with dozens of scenes this is the difference between a scan you run and one you avoid.

Incremental scanning

ChangedOnly relies on RefSafe tracking asset changes as you work. An asset postprocessor watches for imported, deleted, and moved .unity, .prefab, and .asset files and queues them.

This makes the fix-and-verify loop practical: fix a batch, re-scan changed-only, confirm the diff, repeat. A changed-only scan on a handful of assets completes near-instantly even on a large project.

The queue is cleared when a ChangedOnly scan completes. If you’re unsure the tracker is in sync — after a source control operation that rewrote many files outside Unity, for example — run a full EntireProject scan to re-baseline.

Auto-scan on change

Enable Auto Scan On Change in Settings and RefSafe re-scans automatically as scan-relevant assets change, keeping the Hierarchy and Project window badges live without you clicking Scan.

On very large projects this can be more churn than you want. It’s off by default.

Progress and cancellation

Scans run asynchronously against a per-frame time budget rather than blocking the editor. The progress bar reports the current phase and item count, and Cancel stops the scan while keeping whatever was already collected.

Targeted validation

You don’t have to scan the whole project to check one thing.

From the Hierarchy — right-click a GameObject → RefSafe → Validate Selected. Validates that object and its children.

From the Project window — right-click an asset → RefSafe → Validate Selected. Also available: RefSafe → Find References, which jumps to the References tab preloaded with that asset.

Drag and drop — drag assets or GameObjects directly onto the RefSafe Pro window to validate just those.

Targeted validation is useful when you suspect a specific prefab is the problem and don’t want to wait on a full pass.

Scan results and diffing

Each completed scan is cached to Library/RefSafePro/LastScan.json. The next scan diffs against it, so results distinguish:

• New — issues that weren’t in the previous scan
• Resolved — issues from the previous scan that are now gone
• Existing — issues present in both

This is what makes a refactor verifiable: run a scan before, run one after, and read the diff to confirm you closed issues without opening new ones. The Trends tab keeps a longer history and lets you compare any two scans, not just consecutive ones.

Rule faults

Custom rules, fixers, and exporters run inside a guarded invocation path. If yours throws, RefSafe catches it, completes the rest of the scan, and reports a RuleFault issue naming the failure — a misbehaving plugin degrades one rule rather than killing the whole scan. The full stack trace goes to the Unity console.