Source Control with Unity and Visual Studio

DISCLAIMER: Because I am going to be recommending a Microsoft product, it behooves me - for several reasons - to inform you that I currently work for Microsoft. That said, all of the opinions on this blog, my Twitter, etc., are my own.

(xposted from ifdogthen)

The Story So Far

It's unquestionable that Unity has become the go-to engine for indie developers. The ease with which you can add objects to your levels, script behaviors, and build to several different platforms makes it an obvious choice for everything from rapid prototyping to releasing a full AAA title.

When Psydra Games was ready to dive into our second game, after a short break following the release of Dark Scavenger, I was still a beginner with Unity, but its potential was already obvious. If nothing else, we could quickly get a prototype up and running of Lead Designer Alex Gold's crazy idea. The more we dove in, the clearer it was that this was definitely the engine for us.

And although Unity is for the most part a one-stop solution for game development, we were lacking in two areas:

Code Editor: While adequate for prototyping, as a long-term solution, MonoDevelop just isn't up to the standard of Unity's user-friendliness.

Version Control: This certainly isn't a failing on Unity's part, particularly for a free game development tool. Still, it's a necessity for having backups of your work, as well as collaborating with teammates.

As it turns out, both of these issues were solved with the same tool: Visual Studio.

Read more...

Visual Studio has had its free Express version for a long time, but in November, Microsoft released the so-called "Community Edition", which has almost none of the restrictions that exist in Express. This was a great day particularly for Unity users, as the new Community Edition of Visual Studio even allows for plugins, such as UnityVS, which can be very useful for debugging your games.

Many developers are still unaware of the benefits to using Visual Studio, especially its source control, so I wanted to provide a little how-to (as well as a why-to) guide for Unity and Visual Studio, working in (near) perfect harmony.

The first step, which should come as no surprise, is downloading Visual Studio (I am assuming you already have Unity).

Connecting Unity and Visual Studio

With that installed, you just need to set it as your code editor in Unity via Edit->Preferences->External Tools.

To be honest, I've had mixed results with this setting, and so by habit, I just open VS separately and open the solution directly. I've not found a great reason to constantly close and reopen VS, so opening it the same time as Unity and getting yourself set up should be a quick one-time process per development session.

That's really all there is to connecting VS with Unity. Again, UnityVS will further enhance this connection, allowing you to use the Visual Studio debugger, set breakpoints in your scripts, and many other handy features. The only important thing to note is that Unity will make edits to the solution file upon loading the project and upon adding or removing source files, which will prompt you to reload it in VS. This means that if you load up VS and your project's solution file before you load Unity, get ready to reload that solution right away, even if no changes have been made since you last loaded Unity.

Visual Studio Source Control

That brings us to the fun stuff: source control. If you are working alone, maybe you just need to backup your project and have versions to reference. If you're working on a team, source control can make all the difference in how quickly and smoothly your updates integrate with those of your colleagues. There are different settings that may apply to either scenario, so I'll include both options.

The first step in source control is the Unity set-up. By default, Unity has "hidden meta files". These meta files contain settings for the assets in your project, such as import settings and the GUIDs for those assets. This information is obviously vital to your project, and so your source control needs to be able to see them. Go to Edit->Project Settings->Editor, and under Version Control, Select "Visible Meta Files".

Also, while you're in these settings, if you set "Asset Serialization" to "Force Text", you can have multiple people working in the same scene, and merge the changes through your source control, as version control systems are often made to merge text files.

Next, you need to get set up with hosting for your source control. To use Visual Studio's Team Foundation Server, you can sign up for a free Microsoft account, providing you with version control hosting with no space or version limitations. The only limitation to the free service is a maximum of 5 users for your projects. If you are working with a larger team, you could either pay to upgrade, or work with another service (a Git source control plugin is also included with Visual Studio). Because our team fit perfectly in the 5-user limit, we went with Team Foundation Server hosting. As a bonus, TFS provides an agile task board, something else we had shopped around for a lot before settling on Visual Studio.

You'll want to create a new project through the website to contain your game. Then log into your account in Visual Studio, and under the "Team" menu, select, "Connect to Team Foundation Server...". The URL for your TFS hosting will show up in the server dropdown, which will contain your new project.

Here's where some options may change depending on your preferences and team setup.

Working with Workspaces

There are two options for workspaces in Visual Studio. One is Local (which for some reason is recommended), and the other is Server. A local workspace allows you to edit your files locally, and only connects with the server when you sync and submit files. A server workspace requires connection to the server when you check files out, and all server files are marked as read-only until they are checked out. Personally, the only way I can recommend using a local workspace is if you are working alone, and are only using the server to back up your project. I'm sure there are other scenarios, such as working from a laptop while traveling with no access to WiFi, but in general, I would stick with server workspaces for team projects.

And there are a few big reasons for that. First, because local workspaces don't connect to a server to check files out, your teammates cannot see what you are working on, which could mean duplicate work, incompatible edits, etc. Second, it means that you can't enforce exclusive checkouts, so that you don't have to worry about merging changes. And third, something I'm in favor of for everyone's awareness, it forces you to know what files you're editing, which also prevents you from editing files you didn't mean to, and submitting them to the source control.

For these reasons, I made the default workspace for our project a server workspace. To set this, go to Team->Team Project Collection Settings->Source Control

However, if you want, you can change your own workspace to be local. I changed the default because it makes it easier for everyone to get set up with the type of workspace I wanted them to use - and to be perfectly honest, if you want to "enforce" a workspace type, the less ambitiously curious members of your team will probably never dig deep enough to realize they can change it. So don't let them read this blog, because here's how you do that.

On the right side of Visual Studio, under the Team Explorer tab, click on your workspace name (probably your computer's name), and select "Manage Workspaces".

Click the "Edit..." button on the next screen, and then "Advanced >>>".  The "Location:" dropdown determines whether your workspace is local or server.

With your workspace all set up, you can start synching and submitting files. First, map the server to a location on a local drive. Then right-click and click "Get Latest", which will download the temporary files that Visual Studio Online provided to get you started.

Now you're ready to get your project online and accessed by other team members. Put your existing project into the folder you mapped in source control, and grab the "Assets" and "Project Settings" folders. You don't need the "Library" folder, nor the solution files in your source control, as they are generated/edited by Unity when you load and make changes to the project.

If you go to the Team Explorer tab on the right and select "Pending Changes", you can see all of the files ready to be submitted to the server. You can submit these files by clicking the "Check In" button, and optionally (and certainly recommended) adding a comment about what you did.

Being Tricky

Now, if you're only adding a file/folder or two, this is pretty painless. However, once your project is on the server, you'll most likely start to add several different files in several different places. Adding these one by one can get tedious, so there is a shortcut.

First, do all of your work locally; add the files you need in your local version of the project, and make whatever changes you need (sometimes manually checking out server files is required, but Unity will force overwrite asset files you edit). When all of you work is done, go to your Source Control Explorer, and right-click the "Assets" folder (do not use the root project folder, as you don't need the library folder and its metadata), and click "Compare".

A list of your changes (and possibly file updates you didn't sync yet) will show up in a new tab. From here, you can select all, right-click, and select "Reconcile". This will provide you with some options such for resolving these differences. By default, it will add any files that aren't already on the sever and download updates you don't have from the server. It will not by default, however, open for edit the files you have changed but didn't already check out. This may be a good thing, as it will show you files you may have edited by mistake, and give you the opportunity to undo those changes rather then submitting them, or you may want to change that setting to check out all files that you have edited.

Another quick thing to note about Visual Studio source control is that any files you have checked out and submit with no changes will be automatically reverted. This means that you can check out an entire folder, edit one file, and when you check everything in, only that one file will be submitted, and the rest will simply have the server checkout undone. This minimizes the number of files everyone has to sync to without you having to explicitly undo files you didn't end up editing.

I could probably go on far longer, but this already feels too long for one post. Further posts on this topic may be added upon request. For any feedback/questions/hatemail, go to my about page.