RefSafe Pro – Project Validator & Cleaner

Unity Compatibility

• Unity 2021 LTS
• Unity 2022 LTS
• Unity 2023 LTS
• Unity 6

Editor-only tool (does not affect runtime builds).

Validation Scope

RefSafe Pro supports:

• Active scene scanning
• Multi-scene scanning
• Build Settings scene scanning
• Project-wide scene scanning
• Prefab asset scanning
• ScriptableObject asset scanning
• Material, shader, and project settings scanning
• Incremental "Changed Only" scanning (since last scan)
• Path-based exclusions (per-folder)

Unloaded assets are processed safely via editor asset enumeration. Scenes are opened, scanned, and the original scene setup is restored.

Detection Coverage

RefSafe Pro detects:

• Missing MonoBehaviour scripts on GameObjects
• Missing serialized object references in components
• Duplicate components on the same GameObject
• Broken UnityEvent persistent listeners
• Invalid or undefined layer assignments
• Invalid materials and shader compilation errors
• Missing prefab instance roots
• Broken Addressable AssetReference GUIDs (no hard dependency on the Addressables package)
• Suspicious transform positions (NaN / extreme values)
• Deleted scenes still referenced in Build Settings
• Prefab variant component overrides — components removed from the base prefab (opt-in)
• Broken Addressable AssetReference GUIDs and orphan entries in Addressables groups (no hard dependency on the Addressables package)

Each issue includes:

• Asset path
• Scene or prefab name
• GameObject reference (pingable)
• Component type and serialized field
• Severity classification (Critical / Warning / Info)
• Stable hash for cross-session identity (diff, ignore, history)
• Inline explanation and Unity documentation link

Auto-Fix System

Built-in fixers for common issues:

• Missing scripts → remove null MonoBehaviours
• Missing references → clear broken serialized refs on scenes, prefabs, and ScriptableObjects
• Duplicate components → remove duplicates
• Missing prefab instances → unpack
• Deleted build scenes → remove from Build Settings

Missing references also get ranked replacement suggestions — pick the intended

asset from a dropdown instead of hunting for it. Custom fixers register via

[IssueFixer]; custom suggestion sources via IFixSuggestionProvider.

Fixers run per-issue, in batch ("Fix Selected"), or bulk ("Fix All"). Custom fixers can be registered via [IssueFixer].

References Finder

• Bidirectional asset dependency graph (Used By / Depends On)
• Async incremental cache persisted to Library/RefSafePro/AssetMap.json
• Interactive dependency graph view with pan, zoom, and chain navigation
• Public ReferenceSearchAPI for scripting and tooling integration
• Project-wide or Open-Scenes search scope; scene scope reports component-level hits with hierarchy path and component name

Project Cleaner

• Unused-asset detection via reverse dependency map
• Smart exclusions for entry points (Resources, Editor, Plugins, StreamingAssets, build scenes, scripts, asmdefs)
• Empty-folder detection
• Safe deletion via AssetDatabase.MoveAssetToTrash() with confirmation
• Two-layer Protected Assets list — built-in safe defaults (sprite atlases, Input System actions, Localization, lighting data) plus user-defined path and extension patterns
• Empty-folder detection (respects .gitkeep)
• Duplicate detection via size-bucketing + MD5, with a persistent hash cache at Library/RefSafePro/AssetHashes.json — re-scans only hash-changed files
• Import-settings audit — texture Read/Write Enabled and audio Decompress On Load ≥ 1 MB, each with a one-click Fix and a batched Fix All
• Build-weight analyzer — BFS over the dependency graph from every enabled Build Settings scene, reporting the heaviest reachable assets by disk size
• Dry-run preview before every batch delete — total count, disk recovered, breakdown by asset type, and the 10 largest items
• Automatic .unitypackage backup plus JSON manifest written before deletion, under Library/RefSafePro/CleanerBackups/, with one-click Restore
• Deletion via AssetDatabase.MoveAssetToTrash() — recoverable at the OS level

Health Trends

• Project health score (0–100) computed per scan
• Persistent history (last 50 scans) at Library/RefSafePro/ScanHistory.json
• Critical / Warning / Info trend chart with hover tooltips
• Average / Best / Worst summary metrics
• Compare any two recorded scans with a delta summary
• Line / stacked-area / grouped-bar chart variants
• Configurable health-score weights (Critical / Warning / Info) per team

Performance & Control

• Async frame-based scanning via EditorApplication.update (non-blocking editor)
• Synchronous mode for batch-mode / CI runs
• Non-blocking progress bar UI
• Cancellation support for long scans (Escape key)
• Scan duration and per-scope metrics
• Auto-scan on asset changes with 3-second cooldown
• Optimized traversal and zero-allocation IMGUI rendering for large projects
• Performance budgets (p95) on the hot path: hashing, diffing, detection, path filtering

Reporting & Export

Supported export formats:

• CSV
• JSON
• HTML
• TXT
• Markdown
• GitHub Actions annotations (::error / ::warning / ::notice workflow commands)
• GitLab Code Quality (JSON array with fingerprints, consumed by the codequality artifact)

Reports include structured issue metadata suitable for:

• Team review
• QA validation
• Build verification workflows
• CI documentation
• Pull-request comments (Markdown)

Custom export formats can be registered via [ReportExporter].

CI/CD & Build Integration

• Headless CLI entry point: Unity -batchmode -executeMethod RefSafe.Pro.CliRunner.RunScan
• Arguments: --scope, --format, --output, --fail-threshold
• Deterministic exit codes (0 = clean, 1 = issues above threshold, 2 = error)
• Pre-build hook (IPreprocessBuildWithReport) with configurable severity threshold; can block builds on violations

Architecture Notes

• Editor-only assembly (RefSafe.Pro.Editor) plus runtime-safe data assembly (RefSafe.Pro.Core, noEngineReferences: true)
• Hand-rolled dependency injection — zero external runtime dependencies (no VContainer, Zenject, or UniTask)
• Service-oriented composition root via RefSafeApp ([InitializeOnLoad])
• Typed event bus replaces ad-hoc static events
• Public SDK with stable extension points: [ValidationRule], [IssueFixer], [ReportExporter][ValidationRule], [IssueFixer], [ReportExporter], IFixSuggestionProvider
• Manual resolution workflow by default — fixers are explicit, never automatic
• Safe for version-controlled projects (no destructive changes without user action)
• Cache and history stored under Library/ (not committed)
• Compatible with Unity 2021 LTS through Unity 6