Unity Asset Server Overview

The Unity Asset Server is an asset and version control system with a graphical user interface integrated into Unity. It is meant to be used by team members working together on a project on different computers either in-person or remotely. The Asset Server is highly optimized for handling large binary assets in order to cope with large multi gigabyte project folders. When uploading assets, Import Settings and other meta data about each asset is uploaded to the asset server as well. Renaming and moving files is at the core of the system and well supported.

It is available only for Unity Pro, and is an additional license per client. To purchase an Asset Server Client License, please visit the Unity store at http://unity3d.com/store

New to Source Control?

If you have never used Source Control before, it can be a little unfriendly to get started with any versioning system. Source Control works by storing an entire collection of all your assets - meshes, textures, materials, scripts, and everything else - in a database on some kind of server. That server might be your home computer, the same one that you use to run Unity. It might be a different computer in your local network. It might be a remote machine colocated in a different part of the world. It could even be a virtual machine. There are a lot of options, but the location of the server doesn't matter at all. The important thing is that you can access it somehow over your network, and that it stores your game data.

In a way, the Asset Server functions as a backup of your Project Folder. You do not directly manipulate the contents of the Asset Server while you are developing. You make changes to your Project locally, then when you are done, you Commit Changes to the Project on the Server. This makes your local Project and the Asset Server Project identical.

Now, when your fellow developers make a change, the Asset Server is identical to their Project, but not yours. To synchronize your local Project, you request to Update from Server. Now, whatever changes your team members have made will be downloaded from the server to your local Project.

This is the basic workflow for using the Asset Server. In addition to this basic functionality, the Asset Server allows for rollback to previous versions of assets, detailed file comparison, merging two different scripts, resolving conflicts, and recovering deleted assets.

Setting up the Asset Server

The Asset Server requires a one time setup and configuration for each user. You can read about how to do that in the Asset Server Setup page.

The rest of this guide explains how to deploy, administrate, and regularly use the Asset Server.

Daily use of the Asset Server

This section explains the common tasks, workflow and best practices for using the Asset Server on a day-to-day basis.

Getting Started

If you are joining a team that has a lot of work stored on the Asset Server already, this is the quickest way to get up and running correctly. If you are starting your own project from scratch, you can skip down to the "Workflow Fundamentals" section.

1. Create a new Project
2. In the Create Project dialog, make sure all packages are not checked
3. The Project should be completely blank
4. From the menubar, select Server -> Update from Server
5. Enter the user and password that your Asset Server administrator provided to you
6. Wait for the update to complete
7. You are ready to go

Continue reading for detailed information on how to use the Asset Server effectively every day.

Workflow Fundamentals

When using the Asset Server with a multi-person team, it is generally good practice to Update all changed assets from the server when you begin working, and Commit your changes at the end of the day, or whenever you're done working. You should also commit changes when you have made significant progress on something, even if it is in the middle of the day. Committing your changes regularly and frequently is recommended.

Understanding the Server View

The Server View is your window into the Asset Server you're connected to. Select the Server View from the View Selector drop-down of any existing View.

The Server View interfaces with the Asset Server

This view will show you the state of the assets that exist in both your local project and the server project. There are two important things to remember here.

1) The Server View uses color-and-symbol coding to indicate what kind of state the asset is in. To see a list of what the color indicators mean, select Server->Show Legend... in the main menu. You can also view detailed information about individual assets in the Inspector by selecting them within the Server View.

The state of each asset is color-coded

2) The Server View will not show you assets that do exist on the server but do not exist on your Local Project. It will show you items that exist in your Local Project but not the server. This is important because if someone puts a new asset on the server, you will not see it until you download the directory that contains the new asset. When there are new assets available on the server, the parent directory will be marked to indicate that there are changes on the server.

Updating Assets from the Server

To download all new or changed assets from the server, make sure nothing is selected in the Server View and press the Update From Server button or select Server->Update From Server from the menubar.

If you have a folder selected, only new or changed assets in that folder (and subfolders) will be downloaded. If you have one or multiple individual assets selected, only those assets will be downloaded (if they have been updated on the server).

Committing Changes to the Server

When you have made a change to your local project and you want to store those changes on the server, you use select Server->Commit Changes... from the menubar.

If you do this while no assets are selected, all modified assets in your Project will committed to the Server. If a folder is selected, all modified assets inside it (and its subfolders) will be committed. If you have one or more individual assets selected, only those assets will be committed.

Before the assets are uploaded to the server, you will see a Commit Dialog that lists all assets on the server that will be modified. You'll also have an option to include dependencies of uploaded assets, and a text area where you can describe your changes.

The Commit dialog

You can disable the checkbox to the left of each asset in the dialog to skip committing that individual asset. Checking the Include dependencies option will add all assets that are used by the selected assets.

The text area is for entering a message describing the changes you're committing. Enter a descriptive note about the changes you've made and press the Commit button. The change message will be displayed when you compare versions or revert to an earlier version, both of which are discussed below.

Resolving conflicts

With multiple people working on the same collection of data, conflicts will inevitably arise. Remember, there is no need to panic! If a conflict exists, you will become aware of it in one of two situations: either when you are Updating your Project from the server, or when you are Committing your changes to the server.

If you run into a conflict while you are Updating from the server to your Local Project, a Conflict Resolution dialog will be shown. Here, you will be informed of each individual conflict, and be presented with different options to resolve each individual conflict. For any single conflict, you can select Skip Asset (which will not download that asset from the server), Trash My Changes (which will completely overwrite your local version of the asset) or Ignore Server Changes (which will discard the asset on the server and replace it with your local asset) for each individual conflict. Additionally, you can select Merge for text assets like scripts to merge the server version with the local version.

If you run into a conflict while you are Committing your local changes, Unity will refuse to commit your changes and inform you that a conflict exists. To resolve the conflicts, select Server->Update From Server.... Your local changes will not automatically be overwritten, so there is no need to panic. At this point you will see the Conflict Resolution dialog, and can follow the instructions in the above paragraph.

Reverting assets to an earlier revision

The Asset Server retains all uploaded versions of an asset in its database, so you can revert your local version to an earlier version at any time. To revert to an older version of an asset, select the asset in the Server View and then choose Server->Revert to Earlier Version... from the menubar. You will then see the Revert Asset dialog.

The Revert Asset dialog

Here, you can see the version number and added comments with each version of the asset. This is one reason why descriptive comments are helpful. After hitting the Revert button, your local asset will be replaced with a copy of the selected version.

Prior to reverting, if there are any differences between your local version and the selected server version, those changes will be lost when the local version is reverted.

If you only want to abandon the changes made to the local copy, you don't have to revert. You can discard those local modifications by selecting Server->Discard Changes in the main menu. This will immediately download the current version of the asset from the server to your local Project.

Comparing asset versions

If you're curious to see the differences between two particular versions you can explicitly compare them. To do this, select an asset in the Server View and then choose Server->Compare.. from the menubar. Unity will pop up a pane for choosing which versions of the asset to compare.

Comparing two different versions of an asset

Note: This feature requires that you have either have Diff/Merge or FileMerge.app installed. Diff/Merge is available for free from SourceGear at http://www.sourcegear.com/diffmerge/. FileMerge is a part of Apple's XCode development tools, which can be downloaded from http://developer.apple.com.

Deleting assets on the server

If you delete an asset through the Project View and that asset has already been committed to the Asset Server, you will notice that it will reappear the next time you hit Update. This is because assets can be accidentally deleted from the local Project, and it would not be ideal to automatically delete assets on the server to match the local Project.

You must explicitly tell the server that you want to remove the asset. This is done by selecting the asset and choosing Server->Mark For Removal from the menubar. This will mark the selected asset(s) for deletion, indicated in the Server View by adding an strike-through to the asset name. The next time you Commit Changes, the items marked for deletion will be deleted from the server.

To undo marking for deletion, use the Server->Mark For Removal menu entry again to toggle the removal state.

Assets marked for removal on the next commit are marked with green text and a strike-through

Recovering deleted assets

Marking for removal and committing to the server will in fact not delete an asset permanently. Just as any previous version of an asset can be restored using Server->Revert to Earlier Version..., removed assets can be restored through Server->Recover Deleted Assets... from the menubar.

The Recover Deleted Assets dialog

After selecting assets from the list and hitting Recover, the selected assets will be downloaded and re-added to the local project. If the folder that the asset was located in before the deletion still exists, the asset will be restored to the original location, otherwise it will be added to the root of the Assets folder in the local project.

Asset Server training complete

You should now be equipped with the knowledge you need to start using the Asset Server effectively. Get to it, and don't forget the good workflow fundamentals. Commit changes often, and don't be afraid of losing anything.