Why use asset manifest files?

Question

Sometimes you'll see people recommend that rather than using graphics/sound files/etc. like this...

// Game code
Image myImage = new Image("path/to/image.png");

... you should use a manifest file as a level of indirection instead:

// Manifest file
MY_IMAGE: path/to/image.png

// Game code
Manifest myManifest = new Manifest("path/to/manifest");
Image myImage = myManifest.getImage("MY_IMAGE");

What reasons would I have of taking this sort of approach? If I'm not using a compiled language, would there still be reasons to do this?

Answer 1

Most of the time manifest files are associated with some sort of archive file format. For instance, a JAR file in java is simply a zip file with a manifest file that lists the assets within the zip file, and where to find them. In that case the "path/to/image.png" is not a real filesystem path but is instead information on how to find the object inside a compressed archive. In addition to the disk space advantage of compression, using a file archive can improve performance because windows has a very difficult time dealing with tens of thousands of individual files in a small number of directories.

By using a manifest file of this sort you can completely abstract where a given chunk of data is coming from. Maybe your file is on a DVD, or streamed off the internet, or inside a zip file. You'll have to write some additional code to deal with these cases, but by using a manifest file your game logic doesn't have to care at all where something is loaded from.

Now, if you're using a non-compiled language this manifest file could certainly be a C# source file, but it's nice if you can easily modify what manifest file you are using at client execution time based on a registry setting or something similar. For instance, you could check during execution to see if a on-hard-drive cache exists, or if only the DVD is available. You could then switch which manifest to use depending on the available setup.

Answer 2

One reason: data driven programming.

Your code may only want to know it needs a "LightWood" texture and let the resource manager use this key to find the right path to the file. Even further, in scripts, people don't want to remember file paths. They're messy, they can be incorrect. Let the manifest work out where the file is, and let the human work out what material they need by it's name, not the file name.

<material name="wood">
  <diffuse color="1,1,1,1">environment.zip/wood_diffuse.jpg</diffuse>
  <normals>environment.zip/wood_normals.jpg</normals>
  <shader>environment.zip/wood.fx</shader>
  <specular color="1,1,1,1" power="0.5" flat="yes" />
</material>

Answer 3

As a general design pattern, manifests are useful when you want to collect all the information about a disparate set of objects into a single place. It doesn't have to be about archive/packed files, or about indirection to allow things to be moved without recompiling/updating original references. Indeed the latter can introduce more problems than it solves, so you would only do that if it solved a particular need you had.

The big advantage of manifests is that they act as an index to a large amount of data in a single compact place. As such they improve performance (because you can simply load the entire manifest from disc and keep it in memory), especially in the case where you need to iterate over multiple objects, but you don't know in advance what those objects will be. If the objects are on disc, especially if they are in multiple places, you have to touch the filesystem every time you want to iterate over files. For disc-based file systems, the time needed to touch the filesystem is prohibitive, so iterating over files in a directory is a massive cost. By pre-building a manifest of files at build time (NB: not compile time), you trade that cost for memory usage.

Archive files require the use of manifests, simply because the table-of-contents for the archive is essentially a manifest itself, so you get the behaviour for free. And if you are required to use manifests for assets in one location, it can be cleaner to insist that all assets be referenced through manifests; allowing you to abstract the actual storage location/mechanism of the assets from the references to those assets in code. That way you can have a single asset reference type in your code, and not have to make the distinction between file paths, archive file path + offset, or sub-assets.

Answer 4

In addition to the other answers, it also makes your code a little more separated from your assets. You could, for example, allow an artist to work directly with the manifest files without having to have a programmer make the change and make a new build. All it would take is changing the manifest file to point to a new image and simply running the game again.

Answer 5

Manifest files provide a layer of indirection between the resource name and its location. Ofter extra layers of indirection is just a sign of over design. However, sometimes that extra layer is just whats needed to build an elegant and efficient solution.

Here is a simple concrete example where resource name / location separation helped me. While in development my art assets are in revision control with source code. It's very convenient and allows me to iterate quickly. Usually the resource name reflects it's location. The development manifest is very straight forward.

I don't want to distribute a game with the assets scattered around. So when I'm ready to distribute it I can easily zip up my assets into a resource file and build a new manifest.

Also texture atlases are a great way to wring a bit more performance out of the graphics system. Atlases are fast but they're a pain to work with while the art is still under development. My solution is to only build the atlas at the end when I'm optimizing the game. Since I'm using manifests all I need to do is update the manifest to point to an atlas location and voilà the game is now using atlases instead of straight files.