Mastering Unity Project Folder Structure. Level 0 – Folders required for version control systems

Mastering Unity Project Folder Structure. Level 0 - VCS
In this series of posts I’ll spot some light on Unity Project folder structure. What folders and files are required for version control systems, what are reserved folders names and their usage and as a bonus how do we organize resources and other files in our Unity projects at Nravo.


Disclaimer. Before gamedev I used to be an Android developer and I really liked predefined and consistent folder structure across all projects, so I was a bit confused when we started first Unity game.


Mastering Level 0. Folders required for version control systems.

Test Unity Project Folder StructureLets create new Unity project called “testproject”, import “Standard Assets (Mobile)” package, create new Test.cs script attached to camera and check our folder structure.


You’ll find that there are quite a lot of files and folders, good news that only two folders should be kept under source control: Assets and ProjectSettings. Other are generated from this two.



Here is a quick overview of all files and folders.


Assembly-CSharp-vs.csproj and Assembly-CSharp.csproj – Visual Studio (with -vs suffix) and MonoDevelop project files generated for your C# scripts.


Assembly-UnityScript-vs.unityproj and Assembly-UnityScript.unityproj – the same project files but for JavaScript scripts.


testproject.sln and testproject-csharp.sln – solution files for IDEs, first one includes all C#, JavaScript and Boo projects, while the second one – only C# projects and is designed to be opened in Visual Studio, because VS doesn’t know to handle JavaScript and Boo projects.


testproject.userprefs and testproject-csharp.userprefs – configuration files where MonoDevelop stores current opened files, breakpoints, watches etc.



All files listed above except .userprefs are re-generated each time you select Assets → Sync MonoDevelop Project in Unity Editor menu.


Read why there are so many project files generated from Unity documentation.


After syncing project MonoDevelop will open testproject.sln with all projects but if you don’t have JavaScript code you can open testproject-csharp.sln to have twice less project files and no errors related to JS.

Unity Project Folder Structure. Tip 1


Assets – folder where all game resources are stored, including scripts, textures, sound, custom editors etc. Definitely the most important folder in your project.


ProjectSettings – in this folder Unity stores all project settings like Physics, Tags, Player settings etc. In other words everything you setup from Edit → Project Settings set of menus goes into this folder.

Unity Project Folder Structure. Project Settings



Library – local cache for imported assets, when using external version control system should be completely ignored.


obj and Temp – folders for temporary files generated during build, first one used by MonoDevelop, second – by Unity.



Version Control System setup

There are several options how we can keep track of versions. Traditionally Unity encourages developers to use Unity Asset Server. Our team tried to use it for one month after what we agreed that Asset Server can’t handle everything we need, it doesn’t have branches, locks, it’s paid (requires Team Licence, +500$) and looks more like simplified SVN. So we have decided to switch to GIT.


Here is a short setup guide for Unity 4.3:

  1. Enable External option in Unity → Preferences → Packages → Repository
  2. Switch to Hidden Meta Files in Editor → Project Settings → Editor → Version Control Mode
  3. Switch to Force Text in Editor → Project Settings → Editor → Asset Serialization Mode
  4. Save scene and project from File menu


Now you are ready to use your favorite version control system. Don’t forget to add everything except Assets and ProjectSettings folders to your ignore list. Here is .gitignore we use in our project:


For more detailed instructions how to setup version control checkout this posts:


In the second post I’ll describe what predefined folder does Unity use and what for.


More posts from Mastering Unity Project Folder Structure series:

  • Matt Parkins

    Good article.

    Why hidden meta files though?

  • Thiago Ruiz

    I’ve set the option to Hidden Meta Files, but unity still have all the Meta files, git shows that they are still in need of being staged. Should I add *.meta to the .gitignore?

    • Burton Posey

      I know you asked this a long time ago and I’m sure you have your answer, but just in case anyone comes across this…

      You should never add *.meta to the ignore for any version control. These files are how Unity knows something has changed and how it links to other assets in the project.

      A good example of how not syncing meta files goes bad is this. Person A submits a prefab that has a reference to script. Person A submits the prefab and the script without any meta files. The way a prefab stores it’s relationships is with a unique ID (it is listed in the meta files, an ASCII file you can open in notepad or any other text editor, as a GUID). If you don’t submit this, the other people on version control will get these files and make up their own IDs. The prefab knows what is attached to it by referencing GIUDs. So in our example, the prefab will have an ID reference to the script as it was on Person A’s computer, but since Person A didn’t submit a meta file with the script, the ID is going to change as each user makes it up on their own machine because it needs a meta file to have a GUID. Now, every user has a different GUID and resolving the issue can be a chore.

      Just wanted to share in the off chance someone goes looking for help with version control and Unity and doesn’t yet know the role that meta files play in the process.