# Why use asset manifest files?

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?

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.

• I can see the need for abstracting file locations in complex scenarios but just fetching files from a zip archive shouldn't require a manifest as filenames and paths are preserved in the archive. Jul 30 '10 at 0:13

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.

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.

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>