Unity scene file collaboration


Published on

Why does co-editing Unity scene files always cause conflicts? How do we solve this? We take an in-depth look into the file format and toolchain to find a solution.

Published in: Engineering

Unity scene file collaboration

  1. 1. Unity scene file collaboration Simpler than rocket surgery™ Noam Gat 19/4/2015 @noamgat
  2. 2. Hello! Noam Gat CTO @ Tacticsoft Past - JoyTunes, Omek Interactive, OGRE
  3. 3. The scene file is the place that integrates the work of all people working on a project - Programmers add logic - Artists add assets and control lighting - Level designers build levels - Game designers control balance For a team member to be able to complete a loop on their own, they often need to modify the scene file Why collaborate?
  4. 4. Whats the problem? Two team members start working on the scene at the same time, make different changes and try to commit. What is the resulting scene file? How do we get there?
  5. 5. Previous Work Some popular workarounds : - Lock scenes when working on them - Separate the scenes into several prefabs, lock prefabs when working on them Both methods work, but they come with their problems (hard to scale, need to decide prefab split, unable to use prefabs for what they were meant to be)
  6. 6. Related Unity Milestones Why were those workarounds created? Unity 1.0 - Scenes are binary, can’t merge Unity 3.0 - Textual version in Pro Unity 3.5 - Textual version in Free Unity 4.6.1 - Random IDs for documents Unity 5 - UnityYAMLMerge
  7. 7. Tools required for collaboration A. Version Control B. Conflict merging tool C. Understanding of scene file conflicts
  8. 8. Tools required for collaboration A. Version Control git, SourceTree B. Conflict merging tool P4Merge, UnityYAMLMerge C. Understanding of scene file conflicts Today =)
  9. 9. Simple test case Base Change 1 Change 2
  10. 10. Simple?
  11. 11. Simple? :(
  12. 12. Unity scene files In order to read, understand and solve conflicts, we should first understand how Unity stores scene files. The files are based on the YAML format
  13. 13. YAML --- !invoice receipt: Oz-Ware Purchase Invoice date: 2012-08-06 customer: given: Dorothy family: Gale Document separator + identifier (Multiple documents can exist in one file) Key value based storage Indentation for hierarchy
  14. 14. Unity scene YAML --- !u!1 &1280541007 GameObject: m_ObjectHideFlags: 0 m_PrefabParentObject: {fileID: 0} m_PrefabInternal: {fileID: 0} serializedVersion: 4 m_Component: - 4: {fileID: 1280541011} - 33: {fileID: 1280541010} - 65: {fileID: 1280541009} - 23: {fileID: 1280541008} m_Layer: 0 m_Name: Box1 Object type (1 = GameObject), ID Links to component types + document IDs (they are also linked back to it via m_GameObject field)
  15. 15. Unity scene properties - The file is just a flat list of Component / GameObject documents - Order of documents is irrelevant (!) - Hierarchy is maintained by two sided connections (parent points to children, child points to parent). --- !u!4 &1280541011 Transform: m_GameObject: {fileID: 1280541007} m_LocalRotation: {x: 0, y: 0, z: 0, w: 1} m_LocalPosition: {x: 2, y: 0, z: 0} m_LocalScale: {x: 1, y: 1, z: 1} m_Children: - {fileID: 1949811455} m_Father: {fileID: 0} m_RootOrder: 3
  16. 16. Understanding .unity conflicts The common tool to solve conflicts is a “3 way merge” tool, where you see the Base file, and two conflicting changesets made to it.
  17. 17. Simple test case 3-way-merge
  18. 18. Simple test case 3-way-merge Both changesets tried to insert new lines in the same position in the file BaseChange 1 Change 2
  19. 19. Simple test case 3-way-merge In this case, the solution is simple : Just put one of them after the other
  20. 20. Simple test case 3-way-merge Success! (But why is Box1 before Box2?)
  21. 21. Why does auto-merge fail? It does not know what we know : - That a “---” line with different IDs means that they are two different objects. It suspects that the lines are the same change with slightly different values. - That the order of the documents in the . scene file is irrelevant. Who should be before who in the text file?
  22. 22. Smart auto-merge A suggestion for an algorithm to smartly merge .scene files : - Break down the scene file into separate objects (based on the document identifiers) - Merge each document separately - Dump back into .scene file
  23. 23. (Inside .gitconfig) [merge] tool = unityyamlmerge [mergetool "unityyamlmerge"] trustExitCode = false cmd = ' <path to UnityYAMLMerge> ' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED" UnityYAMLMerge In Unity 5, a tool called “UnityYAMLMerge” was introduced. It can be integrated as a pre-merge step in source control tools :
  24. 24. UnityYAMLMerge (Demonstration on actual computer if possible)
  25. 25. Related Unity Milestones Why were those workarounds created? Unity 1.0 - Scenes are binary, can’t merge Unity 3.0 - Textual version in Pro Unity 3.5 - Textual version in Free Unity 4.6.1 - Random IDs for documents Unity 5 - UnityYAMLMerge
  26. 26. Not 100% automatic In some cases, conflicts are real: - Different changes are made to same components - Child ordering is not always resolved in the diff. Manual fixups may be necessary. - One changeset deletes an object, the other modifies it These are real conflicts, and need to be solved like code conflicts.
  27. 27. Summary - Unity .scene conflicts are scary if not understood - Understanding the file format allows technical conflicts to be easily resolved (UnityYAMLMerge) - Once they are solved, the real conflicts are easier to read and manage
  28. 28. Thank You! (We’re hiring! tech@tacticsoft.net ) @noamgat