# 4. Conflicts, Prefab Isolation, and Branching **Target:** Unity 6000.5+. Part of [[Version Control]]. Pairs with [[3. UnityYAMLMerge Smart Merge]] and [[SceneManagement in Unity 6]]. ## Principle **The best merge is the one you never need.** Structure content so two people rarely edit the same YAML file. Use Smart Merge as a safety net, not as the daily plan. Unity’s own authoring guidance: [How to Author Scenes and Prefabs with Version Control](https://unity.com/blog/author-scenes-and-prefabs-with-verson-control). Broader VCS habits: [Best practices for version control systems](https://unity.com/how-to/version-control-systems). ## Conflict strategies for scenes and Prefabs ### 1. Own the file (social or lock) - Assign a **scene owner** per milestone (UI scene, Level_03, Boot). - Or use exclusive locks: Git LFS locks for binaries ([[2. Git LFS]]); UVCS Smart Locks for non-mergeables ([Smart Locks](https://docs.unity.com/en-us/unity-version-control/smart-locks)). - Announce in chat before opening a shared scene on `main`. ### 2. Split scenes (additive / multi-scene) Instead of one mega-scene: ```text Boot.unity # systems, managers — rarely touched Level_Geometry.unity # environment Level_Gameplay.unity # spawns, triggers Level_Lighting.unity # lightmaps / probes ownership UI_HUD.unity # additive UI ``` Load additively at runtime or in the Editor hierarchy. See [[SceneManagement in Unity 6]] for load APIs and patterns. Two designers can then work **Level_Geometry** vs **Level_Gameplay** without touching the same `.unity` file. ### 3. Prefab isolation (the highest leverage habit) Move anything shared out of the scene into Prefabs (and Prefab Variants): | In the scene | Prefer Prefab / data | |---|---| | Player rig, enemies, props | Prefab instances | | Repeated interactables | Prefab + variants | | Tuning numbers | ScriptableObject assets ([[Architecture and Code Patterns]]) | | UI widgets | UI Toolkit UXML/USS or Prefab panels | **Nested Prefabs:** edit the nested asset, not twenty scene instances. Scene files then store instance overrides — smaller, more intentional diffs. **Prefab Variants:** skin / difficulty / faction differences without forking the whole base Prefab YAML by hand. ### 4. Prefer data-driven content Enemy stats, wave tables, dialogue lines, economy curves — **ScriptableObjects** or other assets, not MonoBehaviour fields buried in a scene. Patterns: [[Game Programming Patterns (Review)]], architecture notes linked from the hub. ### 5. When a conflict still happens 1. **Close Unity** (or at least unlock the asset) before resolving — avoid the Editor rewriting mid-merge. 2. Run `git mergetool --tool=unityyamlmerge -- <file>` ([[3. UnityYAMLMerge Smart Merge]]). 3. If the fallback tool opens, resolve remaining semantic conflicts carefully (duplicate GameObjects, lost components). 4. Reopen Unity, let it refresh, enter Play Mode, and smoke-test the scene. 5. Watch for **Missing Script** / pink materials — often a `.meta` GUID problem, not a merge-marker problem ([[6. Pitfalls]]). ### 6. Last resorts - Take **ours** or **theirs** for the whole scene, then **re-apply** the other side’s work manually in the Editor (sometimes faster than a bad auto-merge). - Recover objects from the other branch by checking out a single Prefab path from that revision into a temporary branch/worktree. ```bash # inspect other side without switching fully git show other-branch:Assets/Scenes/Level_03.unity | less ``` ## Prefab isolation checklist (team agreement) 1. No gameplay logic Prefabs “only exist in the scene” — extract. 2. Scene hierarchy is mostly **instances + empties for organization**. 3. Lighting / NavMesh / occlusion can stay scene-owned; document who owns those rebakes. 4. Do not apply Prefab overrides casually across hundreds of instances before commit — review `git diff --stat`. 5. Rename/move Prefabs **inside Unity** so `.meta` moves with them. ## Solo / small-team branching workflow Keep the model simple. Full Git-Flow release machinery is optional for a class project or small studio; a **trunk + short features** model fits Unity well. ### Branches | Branch | Role | |---|---| | `main` (or `trunk`) | Always openable in Unity; protected if on GitHub | | `feature/<short-name>` | One task or ticket; hours to a few days | | `fix/<issue>` | Same idea for bugs | | `release/<version>` | Optional freeze line before ship / class milestone | ### Daily loop (solo or pair) ```bash git switch main git pull --ff-only git switch -c feature/navmesh-agent-tweak # ... work in Unity, save often ... git status git add -p # or carefully stage related files only git commit -m "NavMesh: slow agents on ice surfaces" git fetch origin git switch main git pull --ff-only git switch feature/navmesh-agent-tweak git rebase main # or merge main into feature if you prefer # resolve any scene conflicts with UnityYAMLMerge git switch main git merge --ff-only feature/navmesh-agent-tweak git push origin main ``` Unity-oriented rules of thumb (aligned with Unity’s VCS best-practices article): - **Commit little, commit often** — one logical change (one Prefab, one system). - **Clean messages** — future you greps `git log`. - **Never indiscriminate commit-all** — scene dirt from accidental moves is a classic merge gift. - **Get latest first** — pull/rebase before starting a scene editing session on a shared branch. - Prefer **short-lived** feature branches; long-lived branches accumulate unmergeable scene drift. ### GitHub branch protection (small team) On github.com → Settings → Branches: - Require pull request before merge to `main` (even for two people). - Optional: require one review. - Disallow force-push to `main`. PRs are where you catch “Library sneaked in” and “meta missing” before they hit trunk. ### Paperwork / GDD beside code If you version design docs with the game, keep them outside `Assets/` (for example `Docs/`) so Unity does not import them. Light touchpoint: [[Level Up! (Review)]] for design vocabulary — the VCS point is simply “treat GDD like code: small commits, clear owners,” not a full docs workflow. ## Worked micro-example: avoiding a scene fight **Bad:** Both teammates edit `Game.unity` to place different props. **Better:** 1. Artist creates `Assets/Prefabs/Environment/Crate.prefab`. 2. Designer A instances crates in `Level_Geometry.unity`. 3. Designer B edits `Crate.prefab` materials (or a Variant) — scene untouched. 4. Programmer moves interact logic to a component on the Prefab + SO config. Diffs stay localized; Smart Merge remains unused. ## Next [[5. Clients and UVCS Comparison]] — Desktop vs CLI vs IDE, and when Plastic/UVCS wins.