Introduction

Feature Atlas

SyncShield is easiest to understand as six cooperating modules: one status surface and five save-centric services.

Quick Start

YourProject/
|- Plugins/
|  \- SyncShield/
|     |- SyncShield.uplugin
|     \- Source/
\- Saved/

# SyncShield shared presence heartbeat files
.syncshield/presence/

Toolbar and Menu

The toolbar still behaves like a compact status surface, but the menu now fronts a broader save pipeline.

Menu action reference

Tooltip expansion

The tooltip is now more than an SCM diagnostic. When the new services are enabled, it also appends subsystem summaries such as:

• History: 4 snapshots this session, last /Game/Blueprints/BP_Door
• Auto-Save: 9 shadow saves, last /Game/Maps/MainHub
• Validation: 1 errors, 2 warnings
• Presence: 2 teammates online, 5 remote assets open
• Profiles: SyncShield processed 3 package(s) for dirty Blueprints.
• LFS Locked Files: 2 followed by the locked file paths when Git LFS locks are held.
• Locked by Others: 1 and Checkout Required: 3 when the provider reports lock or checkout state.

Status Model

The toolbar label remains intentionally narrow. It reports source control and unsaved-work state directly, while the new save subsystems contribute detail in the tooltip and menu.

Local Save History

Local Save History is the biggest unlock in the upgrade. Before a SyncShield-observed manual package save overwrites the package file, SyncShield copies the current on-disk package into a per-asset history folder.

Folder example

Saved/
\- SyncShield/
   \- History/
      \- Game/
         \- Blueprints/
            \- BP_Door/
               |- 20260311-194222-113.uasset
               |- 20260311-194222-113.json
               |- 20260311-201745-087.uasset
               \- 20260311-201745-087.json

Behavior notes

• History capture skips procedural saves and auto-save writes.
• Retention is bounded by Max Snapshots Per Asset.
• Restore operates on the active asset known from the last opened asset editor.
• If the package reload fails after restore, the on-disk file is still restored and SyncShield reports that fact explicitly.

Smart Auto-Save

Unreal's stock auto-save tends to batch work. Smart Auto-Save spreads that work out by shadow-saving one dirty package at a time into a dedicated backup directory while keeping the original package dirty.

Pre-Save Validation

Rule sources

Example output

Validation: 2 errors, 1 warning
- /Game/Blueprints/BP_Door :: Blueprint has compile errors or broken references.
- /Game/Blueprints/BP_Door :: Blueprint is missing its parent class.
- /Game/Textures/T_MasterWall :: Texture exceeds the SyncShield size guideline (8192 > 4096).

Team Presence

Folder example

RepoRoot/
|- .git/
|- .syncshield/
|  \- presence/
|     |- alice_ws01_76F4B1....json
|     \- bob_ws07_C30A5E....json
\- SyncShieldDev/

Heartbeat example

{
  "sessionId": "76f4b10f2f6841f981ca3b2f14b7b1d0",
  "userName": "alice",
  "machineName": "WS-01",
  "projectName": "SyncShieldDev",
  "heartbeatUtc": "2026-03-11T20:22:18Z",
  "openAssets": [
    "/Game/Blueprints/BP_Door",
    "/Game/UI/WBP_PauseMenu"
  ],
  "recentSaves": [
    {
      "packageName": "/Game/Blueprints/BP_Lever",
      "savedAtUtc": "2026-03-11T20:21:46Z"
    }
  ]
}

Save Profiles

Unreal normally pushes developers toward an awkward binary choice: save everything or work through a raw package list. SyncShield introduces named save profiles so common save intent becomes a single menu action.

Each profile still flows through the same safety pipeline: collect eligible packages, validate them, snapshot their current on-disk state, then save what remains allowed.

Conflict Sentinel

Safe Branch Shifter

Source Control

The original SyncShield source-control layer is still intact. The plugin still probes Git and Plastic SCM directly, still surfaces degraded states in the toolbar, and still gates risky sync commands when the project is dirty or the repository state is unsafe.

The major upgrade adds save-safety systems around that core rather than replacing it. In practice, SyncShield now answers two different questions at once: “is my repository state healthy?” and “is this specific save safe to perform?”

Provider support

Checkout and locking behavior

Command gating

Git LFS Locks

Git LFS file locking prevents two developers from editing the same binary asset simultaneously. SyncShield 0.6 adds first-class lock management so you never have to leave the editor to release orphaned locks.

How LFS locking works

When lockable is set in .gitattributes, LFS-tracked files are made read-only on disk. A developer must explicitly git lfs lock a file before editing it, and git lfs unlock when done. Locks are server-side and enforced globally, not per-branch.

What SyncShield does with LFS locks

The orphaned lock problem

A common misconception is that git push automatically releases LFS locks. It does not. Without SyncShield, locks acquired during editing persist on the server indefinitely until someone manually runs git lfs unlock from the command line. This blocks teammates from editing those files even after you have pushed your changes.

SyncShield solves this by automatically releasing locks after push and check-in, and by providing a manual unlock action as a safety net.

Cross-Branch Locking

A common question is whether SyncShield only protects developers on the same branch, or whether it can prevent two developers on different branches from modifying the same asset simultaneously. The answer depends on the source control provider.

How SyncShield detects locks

SyncShield does not implement its own locking mechanism. It delegates entirely to Unreal Engine's ISourceControlProvider API, specifically the IsCheckedOutOther() and CanCheckout() methods on each package's cached state. What SyncShield sees depends on what the underlying provider reports.

Provider comparison

What this means for teams

Enabling Git LFS locking

If your repository uses Git LFS but does not yet have locking enabled, add the lockable attribute to your .gitattributes:

*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap filter=lfs diff=lfs merge=lfs -text lockable

SyncShield 0.6 ships with this configuration by default. After adding lockable, tracked files become read-only on disk until explicitly locked with git lfs lock <file>. UE's built-in Git plugin and SyncShield will then surface lock state through the standard checkout and lock UI paths.

Storage Layout

The upgrade introduces three important storage areas. Two live under the project's Saved directory and stay local by default. The presence sidecar lives near the repository root so multiple editors can see it.

RepoRoot/
|- .git/ or .plastic/
|- .syncshield/
|  \- presence/
|     \- user_machine_session.json
\- Project/
   \- Saved/
      \- SyncShield/
         |- History/
         |  \- Game/...
         \- ShadowAutoSaves/
            \- Game/...

Settings

SyncShield settings live under Editor Preferences -> Plugins -> SyncShield. The plugin uses editor-per-project user settings, which means the values are intended to be tuned per project and per workstation rather than shipped as gameplay data.

Workflow Playbooks

The upgraded SyncShield stack is most valuable when used deliberately. These playbooks show how the subsystems combine in real editing sessions.

Current Limits

The upgraded build is materially more capable, but it still has deliberate scope limits. Those are worth understanding up front so you do not over-assume what the plugin guarantees.

Troubleshooting

FAQ