Blueprint merge conflicts: prevent and resolve

An Unreal blueprint is saved as a .uasset file, a packed binary format that encodes nodes, connections, variables, and default values. It's not text. It's not JSON. Diff tools see it as an opaque blob.

When two people edit the same blueprint on parallel branches and try to combine, there's no meaningful "merge" operation. You can only pick one version or the other. Whatever you don't pick is lost.

Since you can't merge the conflict, you must prevent the parallel edit. The standard answer across game dev is file locking, also called exclusive checkout.

The workflow:

1. Before opening a blueprint in the editor, lock it in the desktop app.
2. Edit the blueprint. Save and close.
3. Commit the change. The lock releases automatically.

If a teammate tries to lock the same blueprint while you hold it, they're told who has the lock and can plan accordingly. When the team locks consistently, parallel edits stop happening.

Always lock before editing:

• Blueprints (.uasset), especially widely-shared ones like player controllers, game modes, UI widgets.
• Levels (.umap): large, unmergeable, high-risk.
• Materials and material instances: binary .uasset.
• Animation blueprints, state machines, montages.

Generally don't need to lock:

• Config files (.ini): text, merges fine.
• C++ source: text, handled by normal diff/merge.
• Static meshes, textures, audio. You can lock if two people are touching them, but they're usually "owned" by one role at a time.

Technical locking is only half the battle. The other half is communication:

• Use informative lock messages."boss fight balance pass, ETA 3h" tells teammates when they can pick up adjacent work. "editing" tells them nothing.
• Release locks at end of day. Commit what you have, release the lock, re-lock tomorrow. Dangling overnight locks block distributed teams across time zones.
• Call out shared blueprints in planning. If two tasks both touch the player controller, sequence them or decide explicitly who goes first.
• Split large blueprints.A character blueprint that's touched by five people every sprint deserves to be broken into smaller components. Refactor when it becomes a bottleneck.

Sometimes locking fails. Someone bypassed it, the team forgot, or two branches diverged over a weekend. When you see the "blueprint was edited on both sides" situation, the recovery playbook:

1. Don't panic-pick. Figure out who changed what before overwriting anything.
2. Ask both editors to describe their changes. Usually one set is larger; it should win, and the smaller set will be re-done manually.
3. Open both versions side by side. USourceControl lets you download any prior version to a temporary folder. Have the smaller-change author look at the larger-change version and re-apply their edits on top.
4. Commit the combined result with a message explaining what happened. Lock the file during this process to prevent a third edit compounding the problem.

Unreal Editor has a built-in blueprint diff tool (Tools → Blueprint Diff Tool) that compares two .uasset files visually, showing added, removed, and modified nodes.

This is useful for reviewing a teammate's change before accepting it, or for the "describe the changes" step of the recovery playbook above. USourceControl lets you download any historical version of a .uasset to feed into this tool.

The diff tool doesn't resolve conflicts automatically. Nothing does, for binary blueprints. But it makes the manual reconciliation much less error-prone.