Unity GUID Integrity Engine — Production Workflow Safety System
Publisher: Tools Studio
Unity projects accumulate GUID corruption silently. Broken references, duplicate GUIDs, malformed .meta files, and orphaned entries compound over time — surfacing at merge, during builds, or after prefab refactors. By then, the damage is structural.
MetaGuard is a production-grade Editor utility that scans, analyzes, simulates, and repairs GUID integrity issues with full rollback protection. It gives teams precise visibility into asset dependency health and the confidence to apply fixes without risking live project data.
- Full asset scan — Enumerates all
.metafiles, extracts GUIDs, maps asset-to-meta relationships across the entire project - Dependency graph construction — Builds a directed reference graph from YAML asset files for accurate impact analysis
- Multi-class issue detection — Identifies GUID collisions, zero GUIDs, malformed GUID entries, orphaned
.metafiles, missing.metafiles, broken references, and cyclic dependencies - Risk classification — Each issue is classified Critical / High / Medium / Low based on reference count, fix complexity, and downstream impact
- Simulation engine — Runs every proposed fix through a dependency-aware simulation before any file is touched; reports verdict (Safe / Warning / Dangerous / Destructive) per operation
- Safe apply pipeline — Applies only simulation-approved operations; atomic file writes with temp-file guard prevent partial state on crash
- Auto-fix controller — Generates, prioritizes, and applies fix batches automatically for eligible issues (GUID regeneration, orphan deletion, missing meta creation)
- 3-Tier rollback system — Pre-apply snapshot, 48-hour on-disk archive, and automatic trigger on any write failure; domain-reload resilient via ScriptableSingleton session store
- Scan cache — Avoids redundant full-project scans; invalidates on asset modification
Scan → Analyze → Simulate → Apply → Rollback
Scan — MetaScannerEngine enumerates the Assets folder, reads every .meta file, extracts GUIDs, and produces a ScanManifest with file statistics.
Analyze — IntegrityAnalyzer runs all registered analyzers (GUIDCollisionAnalyzer, ZeroGUIDAnalyzer, MalformedGUIDAnalyzer, BrokenReferenceAnalyzer, CyclicDependencyAnalyzer) against the manifest and dependency graph. Produces a ranked AnalysisResult with health score.
Simulate — SimulationEngine applies each proposed FixOperation against an in-memory clone of the AssetGraph. DependencyImpactWalker traverses downstream nodes; SimulationValidation assigns a verdict and reports issues resolved vs. introduced.
Apply — SafeApplyEngine writes only simulation-approved operations. Each write is staged through AtomicFileWriter using a .metaguard_tmp intermediate. AssetDatabaseTransaction batches the Unity refresh. Session ID is committed to MetaGuardSessionStore before the first write.
Rollback — RollbackSystem restores all files in the session snapshot. SHA-256 integrity is validated before restore. After successful rollback, the session record is cleared from the store.
MetaGuard is organized into two assemblies:
MetaGuard.Internal (ToolsStudio.MetaGuard.Internal) — Data model only. Contains all value types, enums, and result structs shared across systems: IssueReport, FixOperation, SimulationResult, RollbackRecord, AssetGraph, ScanManifest, and supporting types. No Unity Editor dependencies.
MetaGuard.Editor (ToolsStudio.MetaGuard.Editor) — All pipeline logic, UI, and Editor integration. Organized into subsystems:
| Subsystem | Responsibility |
|---|---|
Scanner |
Asset enumeration, GUID extraction, GUID map construction |
Graph |
Dependency graph construction, YAML GUID extraction, cycle detection |
Analyzers |
Per-class issue detection, risk classification |
Simulation |
Impact walking, operation simulation, verdict assignment |
Apply |
Atomic write, snapshot creation, session store, safe apply orchestration |
AutoFix |
Suggestion generation, batch planning, end-to-end fix pipeline |
Safety |
File integrity validation, path sanitization, temp file guard |
Performance |
Structured logger, scan cache |
The MetaGuardWindow EditorWindow orchestrates the full pipeline on the Unity main thread, delegating scan, graph build, and simulation to background tasks via Task.Run. Apply and rollback execute on the main thread as required by AssetDatabase.
MetaGuard enforces a 3-tier rollback guarantee on every Apply operation:
Tier 1 — Pre-Apply (session-lifetime) A file-level snapshot is created and written to disk before any project file is modified. If snapshot creation fails for any file, Apply aborts without writing.
Tier 2 — Post-Session (48-hour archive)
The snapshot manifest persists across Unity restarts via ScriptableSingleton. Rollback is available from the MetaGuard window after editor restart, domain reload, or crash — for up to 48 hours.
Tier 3 — Automatic failure rollback
Any exception during Apply triggers RestoreAll() automatically before surfacing the error to the user. The session is never left in partial state.
Snapshot integrity is validated by SHA-256 hash comparison before any restore. If the snapshot is corrupt or missing, rollback aborts with an explicit diagnostic error rather than attempting a partial restore.
- Scan performance scales linearly with project file count. Typical projects (5,000–20,000 assets) complete in under 3 seconds.
- Dependency graph construction is the most memory-intensive phase. Projects with dense cross-references between prefabs and scripts may require 30–60 seconds for graph build.
- Simulation runs in-memory against a graph clone and does not access the filesystem. Simulation of 50 operations on a 10,000-node graph typically completes in under 500ms.
- The scan cache eliminates redundant scans for unchanged projects. Cache invalidation is triggered by asset modification timestamps.
- Apply throughput is bounded by disk write speed. Each
.metafile is written atomically and individually.
- MetaGuard operates on
.metafiles only. It does not parse binary asset formats (.fbx,.png, textures, audio) for embedded GUID references. - YAML reference extraction covers standard Unity serialization formats. Custom YAML extensions or non-standard serializers may produce false negatives in reference analysis.
- The rollback archive is stored in
Temp/MetaGuard/Snapshots/and is not version-controlled. Snapshots are not a substitute for source control backups. - MetaGuard does not modify scene files (
.unity) or prefab files (.prefab) directly. Reference repair operations update GUID fields within.metafiles only.
MetaGuard is designed for Unity developers who require precise control over asset integrity in production workflows:
- Individual developers and solo studios — Preventive scan before major refactors, migrations, or Asset Store submissions
- Team leads and technical directors — Structural health checks during sprint milestones or before version releases
- Asset Store publishers — Pre-submission integrity validation to prevent broken reference reports from purchasers
- Technical artists — Safe GUID repair after large-scale asset reorganization or directory restructuring
Import the MetaGuard package into your Unity project. Open the tool via:
Tools > MetaGuard > Open MetaGuard
Requires Unity 2020.3 LTS or later. Editor-only — no runtime footprint.
Tools Studio Unity Asset Store — Professional Tooling
MetaGuard v1.0.0