Unity is really great for developing Augmented Reality (AR) applications and games. It’s easy to use and powerful, but once your project gets bigger, or you’re working with a large team, it’s likely you’ll stumble upon some shortcomings or problems regarding collaboration on the project. This blogpost should guide you through the most common stumbling blocks and enable you and your team to smoothly sail through the development process of a typical Unity project.
Version Control System
The first and obvious thing to do is using a version control system (VCS) with your Unity project. Unity Technologies themselves used to provide an integrated VCS called Asset Server, which is now discontinued and regarded a legacy product. With the successor Unity Collaborate still in beta it is best to use an external VCS. While Unity comes with an integration for Perforce and PlasticSCM, it works well with a lot of external version control systems too.
We’d recommend to use Git! Git is a VCS that is fully distributed, meaning every member of your team can work independent and faster. There’s a lot of places like Github or Bitbucket where one can host projects (private or public). Additionally, a lot of Git clients exist that make working with Git really easy, even for non-developers. Examples include TortoiseGit, SourceTree, or SmartGit.
Now there are a few important points when using Unity with Git: A lot of the files and folders of a Unity project are generated automatically! In practice only the “Assets” and “ProjectSettings” folders need to be versioned with Git. The rest of the folders and files should be ignored by Git (this includes the build folder since it can get very large and shouldn’t be stored with the VCS). It can be done with a .gitignore-file, an example .gitignore file can look like this:
# =============== # # Unity generated # # =============== # [Tt]emp/ [Oo]bj/ [Bb]uild /[Ll]ibrary/ sysinfo.txt *.stackdump # ============================================= # # Visual Studio / MonoDevelop / Rider generated # # ============================================= # [Ee]xported[Oo]bj/ .vs/ /*.userprefs /*.csproj /*.pidb /*.suo /*.sln* /*.user /*.unityproj /*.booproj /.idea*/ # ============ # # OS generated # # ============ # .DS_Store* ._* .Spotlight-V100 .Trashes [Tt]humbs.db [Dd]esktop.ini
Just add this file to the top level of your project hierarchy and you should be good to go.
Unity Project Settings
There are a few editor settings inside Unity which are very helpful for working with a team and a VCS on projects! Those can be found by going to Edit → Project Settings → Editor and then looking at the Inspector Window.
Here are the ones you should pay attention to:
Version Control Mode: Visible Meta Files
This enables external version control by making sure Meta Files (.meta) are visible. Whenever an asset is imported into Unity, a .meta file for that asset is generated by Unity, make sure to add the asset as well as the accompanying .meta file to Git. Failing to do so could result in missing links within Prefabs and Scenes in Unity!
Attention: Some Git clients (especially on OSX) treat .meta files as hidden and don’t include them with versioning, make sure to double check!
Serialization: Force Text
This option saves scene files in a text based format which can help with version control merges. More on that later.
With big projects it may makes sense to keep separate copies of the same project with different build targets, especially if they contain lots of assets. The reason for this is that converting between build targets (for example between PC formats and iOS) can take a lot of time with such projects.
Prefabs & Scenes
Here’s the main thing with Unity team projects: Changes to a Unity scene or prefab by various people at the same time are hardly mergeable. It is strongly advised that only one person of the team works on one scene/prefab at a time. There are even stories of a game studio having a table with plushies (stuffed animals) in the middle of their office and every plushie was assigned to one level/scene of their game. If somebody was to edit a level she had to take the plushie to her desk, if it wasn’t there that meant somebody else was editing that particular scene and thus nobody else was allowed to touch it.
A workflow for editing prefabs could be to edit them in another scene than the one they’re used in since changes to prefabs are applied globally across scenes. There actually exists an official tool to merge scenes and prefabs which is provided by Unity and called UnityYAMLMerge, the official documentation even shows how to use it with several different Git clients.
From our experience however it doesn’t work reliably and it’s definitely better to avoid merge conflicts in the first place. In case you have a merge conflict with prefabs or scenes, it definitely pays off to have “Force Text Serialization” (see above) enabled, since a simple “git diff” (or equivalent client command) can show you exactly how the two versions are different and it’s easier to manually correct the conflict. This wouldn’t be possible with binary serialization.
Assets and Binary Files
Most version control systems used not to work well with large binary assets such as 3d models or sound files. Fortunately this isn’t that much of a problem anymore with current Git versions. It is however worth to take a closer look at Git LFS, which stands for Git Large File Storage, and is designed specifically to work well with these large binary files by replacing said assets with text pointers inside Git and storing the file contents on a remote server.
Another topic which is outside the scope of this article, but worth mentioning, is splitting large projects into several projects. Since very large projects can lead to problems with automatic builds or lightmap baking they are split up into several smaller projects, for example code libraries and asset project(s). This was the topic of several talks as well as articles, which we recommend for further reading.
While working with large teams on Unity projects often isn’t very straightforward, it is definitely possible. This article should help anybody looking for a painless team collaboration on a Unity project, don’t feel afraid to give it a go!