Prerequisites:

Terminology: Mesh - a 3d model produced and animated by an artist. Inclusive of all (base) textures and UV maps. Model - a mesh that has been imported to the game and given some attributes; not necessarily 'ready to use'. Object - a game object that is ready to use. May either be a single model or several 'clicked together'. To all intents and purposes an exemplar of an entity. Entity - an instance of an Object as seen by the game.

1. Meshes are designed / animated in .x format. This exposes a number of features, notably bones that can easily be identified, the ability to manipulate (or add) a basic rig to an object. Meshes are the base renderable type.

2. Meshes are used to make Models. A Model is a mesh or set of meshes paired with some (relevant) elements of game data. It may or may not be a complete ship etc.

3. Models inherit data from a parent Model. This could be a mesh, or some other attributes. Animations will be inherited but will not play unless all named bones for the animation are present in the current level mesh. This is checked for when inheriting the animation. Any attribute that isn't present in a Model but is requested should be found in a parent if possible. Note that the Model controls the playback of animation; this prevents an inherited collision mesh from being animated if the current visible mesh can't be.

4. Models may override parent data, but only with the same type for a given attribute name. Attempting to use a different attribute name will not allow the attribute to be added. This will be logged.

5. Models tie game data to mesh data, and vice versa. Where appropriate, some game data needs to follow the model, such as turret inclination / rotation maxima and minima. These can be set on the model and will be available later. Other game data can be specified now that is relevant to the behaviour of the model, such as gear change speed, turret traversal speeds, hull damage level, etc. The values of these data items may be overridden later, but it is important that they can be specified for (or by) the designer in order to get the animations working correctly.

6. Models generate a small amount of script data; primarily in setting up watches on certain variables in order to trigger or set animation states, and in setting up the mesh on instantiation of the model (for randomised mesh set models). Ideally there should be no frame-by-frame scripting; lua is not particularly efficient for that.

7. Objects can be built in a separate tool to Models, and exist in a separate hierarchy. Any values entered for a given attribute for an Object override that given for the Model, but must be of the same type. These values are stored separately in a structure for the object itself. Object data values are paired with a calculation flag which will determine how the values are to be interpreted by the game. Possible options are Override, Average, Sum.

8. Objects can be based on a parent object as a template, but only inherit on creation, basically acting like forks of a repository. The hierarchy is therefore much looser than that for Models, but its primary purpose is organisational, rather than data-driven.

9. Objects may be built from several Models. Where a model being attached has an attribute that already exists for the object, the external tool will request a flag be set for the variable. This flag is persistent for entities built from the Object type, allowing a ship with a set of cargo bay connectors to have a 'Sum' type cargo_capacity, and for cargo_capacity to be set for each of the cargo module models.

10. Objects also generate an amount of script data, primarily around instantiation of the object - primarily this revolves around setting how the component data (gathered from the models in the object) is collated, but also in setting up any expicit data for the object.

11. Entities are built from an Object type, and behave for the purposes of this document exactly like Objects, in that models may be added to them during runtime, however the mechanisms for doing this will need to be more carefully designed. The main difference between an Entity and an Object is that an Entity will have a position in the game universe and any randomly-initialised variables (such as mesh variants etc) will have been set.

In order to allow the hierarchical definition of Models and their associated data, without building specific code-side classes for each variant, a data tree is being built. This comprises of a hierarchical node-graph of DataHolders. Each DataHolder can contain a number of DataVariables, which fall into a number of types- integer, float, Vector, Quaternion, string, blob (binary object). The structure is not intended to be used for data manipulation so operation on the DataVariables is limited to assignment and get/set methods.

Operation of the DataHolders is exposed to Lua, so scripts can access information in them if necessary. It is envisaged that data files for models be human readable Lua scripts generated by the two tools (model builder / object builder).

As mentioned it is required that certain game Entity data be watched by the models that comprise it in order to correctly respond with animation or visual effects. This is best handled by registering event handlers that will make the appropriate calls for animation. This will be achieved by a Lua function added to the Object instatiation script (ie the point where it becomes a game Entity in its own right). The function is to register for an event callback on the change of a particular variable, and on receipt of that callback to call the appropriate animation function in the script of the child model with an appropriate argument.