Cache Server

Unity has a completely automatic asset pipeline. Whenever a source asset like a .psd or an .fbx file is modified, Unity will detect the change and automatically reimport it. The imported data from the file is subsequently stored by Unity in its own internal format.

This arrangement is designed to make the workflow as efficient and flexible as possible for an individual user. However, when working in a team, you will find that other users might keep making changes to assets, all of which must be imported. Furthermore, assets must be reimported when you switch between desktop and mobile build target platforms. The switch can therefore take a long time for large projects.

The time it takes to import assets can be drastically reduced by caching the imported asset data on the Cache Server.

Each asset import is cached based on

• The asset file itself
• The import settings
• Asset importer version
• The current platform.

If any of the above change, the asset gets reimported, otherwise it gets downloaded from the Cache Server.

When you enable the cache server in the preferences, you can even share asset imports across multiple projects (ie, the work of importing is done on one machine and the results are shared with others).

Note that once the cache server is set up, this process is completely automatic, which means there are no additional workflow requirements. It will simply reduce the time it takes to import projects without getting in your way.

How to set up a Cache Server (user)

Setting up the Cache Server couldn’t be easier. All you need to do is click Use Cache Server in the preferences and tell the local machine’s Unity Editor where the Cache Server is.

This can be found in Unity->Preferences on the Mac or Edit->Preferences on the PC.

If you are hosting the Cache Server on your local machine, specify localhost for the server address. However, due to hard drive size limitations, it is recommended you host the Cache Server on separate machine.

How to set up a Cache Server (admin)

Admins need to set up the Cache Server machine that will host the cached assets.

You need to:

• Purchase Cache Server (part of Unity Pro) in the Online Store.
• Download the Cache Server. Go to the Collaboration page and click on the button to Download the Cache Server.
• Unzip the file, after which you should see something like this:

• Depending on your operating system, run the appropriate command script.
• You will see a terminal window, indicating that the Cache Server is running in the background

The Cache Server needs to be on a reliable machine with very large storage (much larger than the size of the project itself, as there will be multiple versions of imported resources stored). If the hard disk becomes full the Cache Server could perform slowly.

Installing the Cache Server as a service

The provided .sh and .cmd scripts should be set-up as a service on the server. The cache server can be safely killed and restarted at any time, since it uses atomic file operations.

Cache Server Configuration

If you simply start by double clicking the script, it will launch the legacy Cache Server on port 8125 and the new Cache Server on port 8126. It will also create “cache” and “cache5.0” directories next to the script, and keep data in there. The cache directories are allowed to grow to up to 50 GB by default. You can configure the size and the location of the data using command line options, like this:

./RunOSX.command --path ~/mycachePath --size 2000000000

or

./RunOSX.command --path ~/mycachePath --port 8199 -nolegacy

You can configure the cache server by using the following command line options:

--port lets you specify the server port, it only applies to the new cache server, the default value is 8126.

--path lets you specify the path of the cache location, it only applies to the new cache server, the default value is ./cache5.0.

--legacypath lets you specify the path of the cache location, it only applies to the legacy cache server, the default value is ./cache.

--size lets you specify the maximum cache size in bytes for both cache servers. Files that have not been used recently will automatically be discarded when the cache size is exceeded.

--nolegacy if specify it will NOT start the legacy cache server, otherwise the legacy cache server is started on port 8125.

Requirements for the machine hosting the Cache Server

For best performance there must be enough RAM to hold an entire imported project folder. In addition, it is best to have a machine with a fast hard drive and fast Ethernet connection. The hard drive should also have sufficient free space. On the other hand, the Cache Server has very low CPU usage.

One of the main distinctions between the Cache Server and version control is that its cached data can always be rebuilt locally. It is simply a tool for improving performance. For this reason it doesn’t make sense to use a Cache Server over the Internet. If you have a distributed team, you should place a separate cache server in each location.

The cache server should run on a Linux or Mac OS X machine. The Windows file system is not particularly well optimized for how the Asset Cache Server stores data and problems with file locking on Windows can cause issues that don’t occur on Linux or Mac OS X.

Cache Server FAQ

Will the size of my Cache Server database grow indefinitely as more and more resources get imported and stored?

The Cache Server removes assets that have not been used for a period of time automatically (of course if those assets are needed again, they will be re-created during next usage).

Does the cache server work only with the asset server?

The cache server is designed to be transparent to source/version control systems and so you are not restricted to using Unity’s asset server.

What changes will cause the imported file to get regenerated?

When Unity is about to import an asset, it generates an MD5 hash of all source data.

For a texture this consists of:

• The source asset: “myTexture.psd” file
• The meta file: “myTexture.psd.meta” (Stores all importer settings)
• The internal version number of the texture importer
• A hash of version numbers of all AssetPostprocessors

If that hash is different from what is stored on the Cache Server, the asset will be reimported, otherwise the cached version will be downloaded. The client Unity editor will only pull assets from the server as they are needed - assets don’t get pushed to each project as they change.

How do I work with Asset dependencies?

The Cache Server does not handle dependencies. Unity’s asset pipeline does not deal with the concept of dependencies. It is built in such a way as to avoid dependencies between assets. AssetPostprocessors are a common technique used to customize the Asset importer to fit your needs. For example, you might want to add MeshColliders to some GameObjects in an fbx file based on their name or tag.

It is also easy to use AssetPostprocessors to introduce dependencies. For example you might use data from a text file next to the asset to add additional components to the imported game objects. This is not supported in the Cache Server. If you want to use the Cache Server, you will have to remove dependency on other assets in the project folder. Since the Cache Server doesn’t know anything about the dependency in your postprocessor, it will not know that anything has changed thus use an old cached version of the asset.

In practice there are plenty of ways you can do asset postprocessing to work well with the cache server. You can use:

• The Path of the imported asset
• Any import settings of the asset
• The source asset itself or any data generated from it passed to you in the asset postprocessor.

Are there any issues when working with materials?

Modifying materials that already exist might cause trouble. When using the Cache Server, Unity validates that the references to materials are maintained. But since no postprocessing calls will be invoked, the contents of the material can not be changed when a model is imported through the Cache Server. Thus you might get different results when importing with or without Cache Server. It is best to never modify materials that already exist on disk.

Are there any asset types which will not be cached by the server?

There are a few kinds of asset data which the server doesn’t cache. There isn’t really anything to be gained by caching script files and so the server will ignore them. Also, native files used by 3D modelling software (Maya, 3D Max, etc) are converted to FBX using the application itself. Currently, the asset server caches neither the native file nor the intermediate FBX file generated in the import process. However, it is possible to benefit from the server by exporting files as FBX from the modelling software and adding those to the Unity project.