Unity Asset GUID Meta Audit
Overview
Build a read-only map of Unity assets, .meta files, GUIDs, and serialized references before any import, regeneration, or asset edit.
When to use
Use for duplicate GUID warnings, missing .meta files, broken prefab or scene references, stale GUIDs, merge damage, or unexplained import failures.
When NOT to use
Do not use for draw order, clipping, runtime UI state, or broad asset reimport. Route those cases to the narrower Unity workflow.
Required inputs and context discovery
Collect Unity version, project root, asset paths, meta paths, serialized reference sources, generated/vendor exclusions, version-control state, and no-touch asset rules.
Safety and risk level
Read-only only. Never create, delete, copy, or regenerate .meta files during diagnosis. Any repair requires exact ownership, backup, and safe-project-mutation.
Workflow
- Inventory assets and their adjacent
.metafiles without opening or saving Unity. Completion criterion: every inspected asset is classified as paired, missing-meta, generated, vendor, or excluded. - Normalize GUID ownership into a deterministic map. Completion criterion: duplicate GUIDs cite every owning path.
- Extract serialized GUID references from scoped text assets. Completion criterion: stale references cite source path and missing GUID.
- Trace the editable source for generated or copied assets. Completion criterion: no generated destination is proposed as the repair source.
- Produce a source-first repair plan and verification fixture. Completion criterion: proposed changes are reversible or remain BLOCKED.
Evidence and output contract
Produce unity-guid-meta-audit.json with asset/meta pairs, duplicate GUIDs, missing meta, stale references, exclusions, limitations, and source-first recommendations.
Handoff contract
Record Unity version, inspected roots, duplicate/stale GUIDs, protected paths, generated ownership, and the next safe repair experiment.
Pitfalls and anti-rationalization
- Never generate a new
.metamerely because one is missing. - A text search result is not proof Unity imported the asset.
- Do not rewrite GUIDs across the project to silence one error.
- Missing Editor access is BLOCKED for live import confirmation.
Verification checklist
- Asset and meta inventories are scoped.
- Duplicate GUIDs cite all paths.
- Stale references cite their sources.
- Generated/vendor paths remain untouched.
- Repair work is routed through safe mutation.
References and scripts
Use the bundled scripts/unity_guid_audit.py on normalized manifests and project-local Unity serialization rules.