Patchwork

Patchwork

Module: Design · Category: LevelDesign · Tool ID: Patchwork

The missing source-control layer for Unreal levels. Save named snapshots of every reflected UPROPERTY on every actor and component in the level, diff two snapshots property-by-property in a tree view, then cherry-pick which changes to restore. Solves the “two artists editing the same level” conflict problem that traditional source-control (Git, Perforce) handles badly because UE’s .umap is binary.

ℹ️ Planned release: Free standalone Fab plugin. Currently registered as Patchwork in the EQLabs Hub. The class is internally FSceneSnapshotManager until the standalone extraction renames it.

---

When to use it

• “Save before risky change” — snapshot before a big lighting or layout change
• Two artists collaborating on the same level — diff their states and merge
• Pre-commit safety — snapshot before committing to source control as a fallback
• Iteration — save several variations and compare

When not to use it

• Don’t use this as your primary source control — it’s a layer on top of Git / Perforce, not a replacement
• Don’t expect this to handle level loads / saves — it captures actor state, not the level asset itself
• Don’t expect SCC integration in V1 — Phase C+D will add Git hooks and 3-way merge

---

Opening the tool

1. Open the EQLabs Hub and search for Patchwork (or browse to Design → LevelDesign)
2. Click the tool card

---

Interface tour

Section	What it does
Save Snapshot	Captures every reflected UPROPERTY across every actor + component
Snapshot list	Per-snapshot row: name, timestamp, author, tag, screenshot thumbnail
Compare Snapshot	Diffs the selected snapshot against current state
Restore Snapshot	Restores every property in the snapshot
Restore Checked	Restores only the cherry-picked properties from the diff tree
Delete Snapshot	Deletes the snapshot file
Diff tree	Hierarchical view of every change

Snapshot capture

When you save a snapshot, every actor in the level is walked. For each actor, every reflected UPROPERTY is exported via FProperty::ExportText_InContainer. Components are walked recursively. Only properties that differ from the class default (CDO) are captured — keeps JSON size reasonable.

Snapshot metadata (Phase B)

Each snapshot stores:

• Name — your label
• Description — free-text
• Tag — preset tags (Before Lighting Pass, Pre-Commit, Custom...) or your own
• Author — git config user.name / p4 info / OS username
• Timestamp — local ISO-8601
• Commit SHA / Branch — auto-captured from git
• Screenshot — viewport thumbnail captured at snapshot time

Diff tree

Compare any two snapshots (or one snapshot vs current state). The tree shows:

Node kind	Meaning
ActorAdded	New actor present in Current, missing from Saved
ActorRemoved	Actor in Saved, deleted in Current
ActorModified	Container for property changes within an actor
ComponentAdded / Removed / Modified	Same as Actor, for components
PropertyChanged	Leaf node — one property’s value differs
PropertyRevertedToDefault	Was captured in Saved (non-default), now matches CDO
PropertyDivergedFromDefault	Was matching CDO in Saved, now non-default

Each leaf has a cherry-pick checkbox. Tri-state propagation means you can check a parent and the whole subtree gets selected. Click Restore Checked to apply only the selected leaves.

---

Workflow

Save a snapshot

1. Click Save Snapshot
2. Enter a name (e.g., Pre-LightingPass)
3. Optionally fill description / tag
4. Snapshot is captured — viewport thumbnail saved alongside

Compare and restore

1. Select a snapshot in the list
2. Click Compare Snapshot — diff tree populates
3. Walk the tree, checking properties you want to restore
4. Click Restore Checked — only checked properties revert

Full restore

For “go back exactly to this state”, select the snapshot and click Restore Snapshot — every captured property is restored.

Export / Import / Duplicate

Right-click a snapshot for context-menu actions: Duplicate, Export (saves snapshot file to disk), Delete. Import Snapshot at the top of the list lets you load a snapshot file from another machine / project.

---

Settings reference

Snapshots persist to [Project]/Saved/EQLabs/Patchwork/snapshots.json. Thumbnails persist to [Project]/Saved/EQLabs/Patchwork/thumbnails/<snapshot-id>.png.

---

Output

• JSON snapshot file — versioned schema, human-readable
• PNG thumbnail — per snapshot
• Level state changes — Restore / Restore Checked modify actor state in-place
• Undo — Restore is wrapped in ScopedTransaction, but restore-of-restore can interact unpredictably; commit between large restores

---

Tips & gotchas

• Patchwork captures in-memory state, not disk state — save the level afterward to persist
• Property capture excludes transient / editor-only / internal-use properties — what’s captured is roughly what UE serializes via SaveGame
• Cherry-pick uses tri-state checkboxes — a parent shows partial when only some children are checked
• Future plan: Phase C will add a git pre-commit hook that auto-snapshots before each commit
• Future plan: Phase D will add 3-way merge — diff your changes against another artist’s changes against a shared base

---

Related tools

• Project Doctor Suite (Tech module) — broader project-state audit alongside snapshot history

---