Resource System

This is the design document for the resource system. It's currently a work in progress, but it should be followed for future work on the resource system.

Overview of the Resource System

The resource system is our own internal platform-independent way to read files from disk that are platform-independent game data. This includes things like textures, sound effects, and game object models. While it would be straightforward to only focus on platform-independent path handling, we require a certain amount of information to be associated with resources, and some resources even contain game logic, such as maps. Resources can also be downloaded and/or installed automatically at the direction of a game server or the user. Therefore, we need a complete resource-handling system capable of much more advanced work while hiding underlying platform details from the rest of the game.

We have tResourceManager. In my view, it handles retrieving files from the cache/downloading, and will handle timing out cached resources and deleting them. It transparently handles bundled resources, installed resources, and cached resources, so none of the other components need care about it.

To help tResourceManager do it's work, we have tXmlResource. Currently there's nothing in tXmlResource, it's a placeholder. What it *should* contain, however, is the ability to read tags that are standard across all resources, such as the parent <Resource> tag. It should also understand tags that reference external files and, imo, provide methods for opening filetypes that are common amongst many components. This includes textures and models, as far as I'm concerned. So the code path to loading files into memory passes through tXmlResource. For an initial implementation, we can just put the actual code into tXmlResource, later we can work out a fancy way to register mimetype handlers to allow components to hook in their own special formats.

tResourceManager, then, will scan all resource directories creating its own internal list of tXmlResources, and it will use that list to do its work. Same for installing, when tResourceManager is called upon to install a resource, it will be given the current location of the resource, load it into a tXmlResource, and then do what it needs to do to install it.

Components will create their own classes as needed that inherit tXmlResource. Then they'll register that class with tResourceManager. When it's time for a component to request a resource, it will ask tResourceManager for an instance of that resource and tResourceManager will provide it, either by creating a new one, or by dynamic_casting the one from its list, or whatever else we dream up.

So the rest of the game, then, will only access resources through tResourceManager. No component will create new instances of a resource, all will always get points from tResourceManager. tResourceManager will always retain ownership of the resource instances, so components will not delete them, ever.

Design Goals

The design goals of the system are as follows.

• Low overhead for implementing new resource types
• Low overhead for using resources from outside code
• Scripts should be able to use the same interface to implement and use resources
• Insure integrity of resources
• Platform independence for all other code that uses resources (i.e. isolate platform-dependent code to the fewest possible places within the resource system)
• Separation from the game itself, to be provided as a shared object for other programs to use in a support role

Organization in the Source Tree

Ok, resources need their own directory. Right now, each directory under src represents a layer and they all stack on top of each other. I'd like to move it to where each represents a component, and they may be stacked, maybe not. Anyway, the resource system doesn't belong in tools, it needs access to stuff tools don't have access to.

Organization of Resources in the Source Tree

Todo: Write this

Organization of Resources in an installation

Todo: write this

Detailed Overview of Resource System

Todo: write this. Should be a detailed discussion of how all of the components of the resource system work together, referring to sections below for specific attributes and behaviors of the different components.

Components of the Resource System

tResourceManager

This is the top-level interface. All outside code will retrieve resources from tResourceManager. tResourceManager will automatically provide these features:

• Automatic download and installation of resources - this is an on-demand service provided. When a game server specifies a resource the client should use, tResourceManager will download and install that resource and make it available to the code that requires it on the client side. The game server itself should also automatically download and install resources in the same fashion from the repository specified in its configuration files.
• Cache management - just like a web browser, tResourceManager should expire resources in the cache and manage the disk space used by the cache.
• Generate lists of resources - this is an on-demand service as well. Its primary purpose is to provide information needed to build UI elements for the user. Use cases include moviepack selectors, resource browsers, and map rotators.

Features provided that generally require user action of some sort:

• Resource creation - Used by resource authoring programs, like a map editor.
• Resource packaging - Used by resource developers to create distributions of their resources
• More (I seem to have forgotten some of this momentarily)

tResource

tResource is the base class for all xml resources. It is also used as a standalone class by tResourceManager to perform all of the functions needed during the day of managing resources. All resources should inherit this class.

tXmlResource provides a generic way to handle all resources using standard tags that exist in all xml files. It also provides a base class for components to use to implement their own special resources.

An internal registry will exist eventually that components will use to tell the resource system about their own special resources, so that when they query tResourceManager for their own special resources, tResourceManager can provide.

These two aspects combine to make it easy to add new resources, both in new code and potentially in scripting. All that's needed is to make your subclass of tXmlResource and register it with tResourceManager. We also get comprehensive resource management within tResourceManager via tXmlResource, and this is true for even new resource types, and we get this without sacrificing extensibility.