Setting up Plastic SCM to work with Unity

Setting up Plastic SCM to work with Unity

Wednesday, February 13, 2013 Amalia unity 0 Comments

2013/11/13 - UPDATE: If you are looking into this you're probably interested on our new Unity plugin - http://plasticscm.com/unity-plugin.html. And check this recorded webinar on the basics here.

I‘ve been reading about Unity and how to use external version control systems with it. There’re a lot of posts and questions on the Unity forum and I discovered that Unity developers are suffering simple problems and there’s no much knowledge about distributed version control systems. (DVCS).

A very funny example is that developers are using Dropbox for sharing big files, which is probably not the best way to deal with something that should be version controlled.

Tracking meta files

Inside the Unity documentation there is a page titled “Using External Control System with Unity”.

The chapter explains how all the Assets and Project settings should be added to the version control system. On the other hand, nothing from the Library directory should be added, it must remain outside the version control system.

The key topic is about not forgetting to include the “.meta” files. The “.meta” files are text files, one per every asset in the Asset directory, containing the necessary bookkeeping information required by Unity. These “.meta” files contain the internal GUID of their respective asset.

As we're going to work with Plastic SCM, an external Distributed Version Control System and not with the Asset Server, it’s necessary to tell Unity to modify the project structure slightly to make it compatible with storing assets in Plastic SCM.

This is done by selecting “Edit/Project/Settings/Editor” in the application menu and enabling External Version Control support by selecting “Metafiles” in the dropdown for Version Control.

The Unity files will have a “.meta” file extension with the first part being the full file name of the asset it is associated with. Moving and renaming assets within Unity should also update the relevant “.meta” files. However, if you move or rename assets from an external tool, make sure to apply the same operations to the relevant “.meta” too.

How can Plastic SCM help you?

We have two ways to help Unity developers, the first one is the Transparent SCM, you just have to change your code files, add new files, rename files or delete files. Plastic SCM will do all the tracking for you. Really? Sure, Plastic SCM will deal with “the dirty work”, so you can focus on the development of your Unity project.

The second one is about the meta files management, the Plastic SCM team wrote a script to find out added/changed/moved/deleted files. This script automates some of the grunt work of keeping a Unity repository in sync. The script is named “MetaReminder“. Cool, isn’t it?

“MetaReminder” will track if…:

• You’re adding the “.meta” file at the same time you’re adding the regular file or not.
• You’re moving the “.meta” file at the same time you’re moving the regular file or not.
• You are Deleting the “.meta” file at the same time you’re deleting the regular file or not (optional option).

Make sure you have installed Plastic SCM.

The workflow will be the following:

• Add your code under Plastic SCM control
• Develop your task
• Commit your changes

If the operations aren’t executed over the “.meta” file the commit operation will fail to prevent an incomplete changeset.

Trigger setup

The “MetaReminder” script is inside THIS zip file. Copy the zip file in a known location. Uncompress the code; you’ve got an executable file. You can run the script by typing the following options at the command prompt:

• Remind adding the “.meta” file for a new file:

cm mktrigger before-clientcheckin "Meta file reminder" 
"C:\path\unitymetareminder.exe

• Moreover you can enable the tracking of the delete operation:

cm mktrigger before-clientcheckin "Meta file reminder" 
"C:\path\unitymetareminder.exe --checkde"

NOTE:As this trigger is a client side trigger, make sure you copy the tool in the same path for all the clients.

NOTE 2:Under Unix environment you can use the trigger with the mono framework, this is an example: cm mktriger before-clientcheckin “Meta file reminder” “mono /home/tester/unitymetareminder.exe”

Are you getting started with Plastic SCM triggers? Find out more about Plastic SCM triggers using our online guides.

Practical Example

We’re going to create a new trigger. Please, open up a terminal windows and type, for example, the first option to remind adding the ".meta" file. You’ll see something similar to this:

c:\Users\amalia>cm mktrigger before-clientcheckin "reminder" 
"C:\plastic\MetaReminder.exe"
Trigger created on position 1

Then you can check if your trigger has been created. In order to do that, type the following command: “cm listriggers” as the figure below:

c:\Users\amalia>cm listtriggers
    1 reminder   c:\plastic\MetaReminder.exe amalia before-clientcheckin

As you can see in the figure, the trigger is created. Let’s imagine the scenario where we are adding a new file without the appropriate “.meta” file, the trigger will help us to handle the situation.

Let’s go to Plastic SCM GUI.

We’re going to “Items View”. Now, let’s add a new unity file, for example “c:\plastic_repo\scen_one.unity”. Then, let’s add the file to the repository, right click on the file and select “add to source control”. Now, Plastic SCM knows about this file, but it is not checked in the repository yet. Just right click and select “checkin” option. Here it’s what you will see:

The trigger is reminding you: “You need to checkin the scene_one.unity.meta file too”. So, we’re going to add “scene_one_unity.meta” file in our repository in “c:\plastic_repo”. Let’s go to “Items view”, you’ll see something similar to this:

Let’s go to “Pending Changes” view. It shows what we’ve modified so far:

There are two add new files. So, you can now checkin all the changes and the operation will finish correctly because you added the “meta” file at the same time as the asset file. Once the checkin is done the “Items View” will look like the following:

Please note the status of all files is now “controlled”.

I’ll be happy if you give it a try and I welcome if you send me a feedback, as well as any suggestions you may have.

Note: You can download the original "MetaReminder" here

Update: He have received a modification of the “MetaReminder” tool that automatically creates the missing “meta” file.

You can download the source code here and the binaries here.