Broken Import Demo Walkthrough
This interactive 3-stage walkthrough demonstrates how ImportShield detects, explains, and heals real-world project breakages using the bundled Broken Import Demo and FantasyProps_v2.unitypackage.
Scenario Overview
You have a functioning game project containing combat prefabs (Sword.prefab, Shield.prefab) and a combat scene (Arena.unity). You purchase a new asset pack from the Asset Store (FantasyProps_v2.unitypackage) promising higher-fidelity weapons.
Unknown to you, the author of FantasyProps_v2 included a script named Weapon.cs with a newly generated GUID, overwriting your project’s existing script .meta file and breaking references across your prefabs and scenes.
Here is how ImportShield handles this situation.
Stage 1: Baseline & Package Preflight
1. Establish Baseline Protection
- Open
Assets/Samples/ImportShield/<version>/BrokenImportDemo/Scenes/Arena.unity. - Open Tools ▸ ImportShield ▸ ImportShield Window.
- Confirm that the status indicator in the top header is 🟢 Protected.
2. Preflight FantasyProps_v2.unitypackage
- Navigate to: Tools ▸ ImportShield ▸ Preflight Package….
- Locate
FantasyProps_v2.unitypackageinside the sample directory:Assets/Samples/ImportShield/<version>/BrokenImportDemo/FantasyProps_v2.unitypackage - Drag the
.unitypackageinto the Preflight drop zone. - Notice the immediate 🔴 RED: Conflicts Detected safety verdict:
- Will Overwrite:
Weapon.cs(matches existing project path). - GUID Collision:
Weapon.cs.metauses GUIDb1c2...while your project usesa0f9.... - Duplicate Class:
Weaponclass declared in both packages.
- Will Overwrite:
- Click Import Safely. ImportShield automatically captures a Pre-Import Freeze snapshot, byte-backs up the existing
Weapon.cs, and allows Unity to extract the package.
Stage 2: Change Investigation & Blast Radius Map
As soon as Unity finishes extracting the package:
- ImportShield immediately detects the settle event and opens the Changes tab.
- Inspect the Blast Radius Map:
- The root epicenter shows
FantasyProps_v2.unitypackage. - Radiating outward,
Weapon.csis highlighted in red as a direct casualty. - Connected nodes
Sword.prefab,Shield.prefab, andArena.unityare highlighted in amber.
- The root epicenter shows
- Review the Provenance Separation:
- New Breaks: 3 (Directly caused by
FantasyProps_v2). - Pre-existing Breaks: 0.
- New Breaks: 3 (Directly caused by
- Click on the broken
Sword.prefabreference to open its Evidence Card:- Why It Broke:
Cause C2: Target file overwritten at same path with new GUID. - Fix Candidates:
- Candidate 1:
R3: Path Match with New GUID (High, 92%). - Candidate 2:
R4: Script Class Match 'Weapon' (High, 94%).
- Candidate 1:
- Why It Broke:
Stage 3: Two-Pane Diff, Repair & Rollback
1. Preview the Line Diff
- Click ⚡ Fix All High+ Confidence (Preview).
- The Diff Viewer modal opens:
- Left pane displays the broken line in
Sword.prefab:m_Script: {fileID: 11500000, guid: a0f9...}. - Right pane displays the surgical candidate replacement:
m_Script: {fileID: 11500000, guid: b1c2...}. - Sibling components and line endings remain completely intact.
- Left pane displays the broken line in
2. Apply the Plan & Cascade to Green
- Click Apply Plan.
- ImportShield executes the line patch inside a fail-closed transaction.
- In the Scene View and Changes tab, watch the Cascade-to-Green:
- The red and amber nodes on the Blast Radius Map transition dynamically to green.
- The inspector on
Sword.prefabandArena.unityimmediately reconnects theWeaponcomponent without any manual dragging!
3. Verify 1-Click “Undo Import”
Want to revert the entire experiment as if the import never happened?
- In the ImportShield Window, click ↩ Undo Import.
- ImportShield restores the original
Weapon.csand its original.metaGUID from the transaction backup. - Unity re-indexes the clean originals. Your project is restored byte-for-byte to its pristine pre-import baseline!
“No tool can truthfully guarantee ‘zero risk’ or ‘zero data loss’; ImportShield fails closed and tells you the truth instead of pretending otherwise.”