Neverwinter Nights:Aurora Binary Model File Format

From TBotR Wiki

Introduction

The binary format of the model file contains 3 main sections, the header, the model data and the vertex or raw data.

Structure

Header
Model Data Model Geometry Header
Node 1
Node 2
...
Node N
Animation Geometry Header 1
Node 1
Node 2
...
Node N
Animation Geometry Header 2
Node 1
Node 2
...
Node N
Animation Geometry Header N
Raw Data

Header

(size 12 bytes)

The header provides us with the offset and size of the raw data.

Offset Type Description
0 UINT32 Value of 0 for binary model files
4 UINT32 Offset to the raw data/size of the model file
8 UINT32 Size of the raw data

Model Data

Geometry Header

(size 112 bytes)

All models contain at least one geometry header.

Offset Type Description
0 Pointer Pointer to a function
4 Pointer Pointer to the function to parse an ASCII model line
8 CHAR [64] Geometry Name (model or animation name)
72 UINT32 Pointer/Offset to the root node of the geometry
76 UINT32 Number of nodes in the geometry. In the case of the model geometry, if the model has a super model defined, then this value also includes the number of nodes in the super model plus one
80 Pointer Array Array of unknown data (probably runtime only)
92 Pointer Array Array of unknown data (probably runtime only)
104 UINT32 Reference count, initialized to 0. When another model references this model, then this value is incremented. When the referencing model dereferences this model the count is decremented. When this count goes to zero, the model can be deleted since it is no longer needed.
108 UINT8 Geometry Type
ValueType
1Basic geometry header (not in models)
2Model Geometry Header
5Animation Geometry Header
128If bit is set, then model is a compiled binary model loaded from disk and converted to absolute addresses
109 BYTE [3] Padding

The Model Header

(size 232 bytes)

There is only one model header per model file. This header always starts at offset 0 in the model data section or offset 12 from the start of the file.

Offset Type Description
0 Geometry Header Geometry Header
112 UINT8 Unknown value initialized to 0
113 UINT8 Unknown value initialized to 1
114 UINT8 Model Classification
ValueModel Class
1Effect
2Tile
4Character
8Door
115 UINT8 If non-zero, model should be fogged
116 UINT32 Unknown value initialized to 0
120 Pointer Array Array of pointers to all the animation geometries
132 Pointer Pointer to the parent model, always 0
136 FLOAT [3] Bounding box min, defaults to (-5.0, -5.0, -1.0)
148 FLOAT [3] Bounding box max, defaults to (5.0, 5.0, 10.0)
160 FLOAT Radius of the model, defaults to 7.0
164 FLOAT Animation scale, defaults to 1.0
168 CHAR [64] Super model name, defaults to ""

The Animation Header

(size 196 bytes)

There are zero or more animation headers per model, one header for each animation. All animations contain their own geometry information. However, this usually consists of dummy nodes containing controller information.

Offset Type Description
0 Geometry Header Geometry Header
112 FLOAT Animation length, defaults to 1.0
116 FLOAT Trans time, defaults to 0.25
120 CHAR [64] Animation root, defaults to ""
184 Animation Event Array Array of all the events associated with this animation

Animation Event Array Structure

(size 36 bytes)

Each animation can have zero or more events. Unlike other arrays that contain pointers to the structures, the animation event array is an array of the actual structure. The structure is as follows:

Offset Type Description
0 FLOAT After
4 CHAR [32] Event name

Nodes

Currently, there are nine different node types that make up a model's geometry. These nodes specify such elements as lighting, animated graphic emitters, and different types of meshes. Each node type shares a common header that supplies us with enough information to tell what type of node it is and information about controllers and children.

Node Header

(size 112 bytes)

Offset Type Description
0 Pointer Unknown function pointer
4 Pointer Function pointer to parse a line of an ASCII model file
8 Pointer Function pointer to perform post node processing
12 Pointer Unknown function pointer
16 Pointer Unknown function pointer
20 Pointer Unknown function pointer
24 UINT32 Inherit color flag
28 UINT32 Part number/Node number
32 CHAR [32] Node name
64 Pointer Pointer to the parent geometry, always 0
68 Pointer Pointer to the parent node, always 0
72 Pointer Array Array of pointers to the child nodes
84 Pointer Array Array of controller key structures
96 Pointer Array Array of controller data values
108 UINT32 Node flags/type

The Dummy Node

(size 112 bytes)

The dummy node is a default node in a geometry that only contains child nodes and controller information. It has no other data associated with it.

Offset Type Description
0 Node Header Common node header

The Light Node

(size 204 bytes)

The light node specifies light sources in the geometry model.

Offset Type Description
0 Node Header Common node header
112 FLOAT Flare radius
116 UINT32 [3] Array of unknown information
128 FLOAT [3] Flare sizes
140 FLOAT [3] Flare positions
152 FLOAT [3] Flare color shifts
164 Pointer Array Array of pointers to the flare texture names
176 UINT32 Light priority, defaults to 5
180 UINT32 Ambient only flag, defaults to 0
184 UINT32 Dynamic type, defaults to 1
188 UINT32 Affect dynamic flag, defaults to 1
192 UINT32 Shadow flag, defaults to 1
196 UINT32 Generate flare flag, defaults to 0
200 UINT32 Fading light flag, defaults to 1

The Emitter Node

(size 328 bytes)

The emitter node specifies dynamic graphical elements that are emitted from the model such as smoke or sparkles.

Offset Type Description
0 Node Header Common node header
112 FLOAT Dead Space
116 FLOAT Blast radius, defaults to 0.0
120 FLOAT Blast length, defaults to 0
124 UINT32 X grid
128 UINT32 Y grid
132 UINT32 Space type, defaults to 0
136 CHAR [32] Update
168 CHAR [32] Render
200 CHAR [32] Blend
232 CHAR [64] Texture
296 CHAR [16] Chunk name
312 UINT32 Two-sided texture flag, defaults to 0
316 UINT32 Loop flag, defaults to 0
320 UINT16 Render order, defaults to 0
322 BYTE [2] Padding
324 UINT32 Emitter flags
ValueDescription
0x0001P2P
0x0002P2P Sel
0x0004Affected by Wind
0x0008Is Tinted
0x0010Bounce
0x0020Random
0x0040Inherit
0x0080Inherit Vel
0x0100Inherit Local
0x0200Splat
0x0400Inherit Part

The Reference Node

(size 180 bytes)

Offset Type Description
0 Node Header Common node header
112 CHAR [64] Ref model
176 UINT32 Reattachable flag

The TriMesh Node

(size 624 bytes)

The trimesh node provides the basic drawing mesh used to render elements of the game.

Offset Type Description
0 Mesh Header Common mesh header

The SkinMesh Node

(size 738 bytes)

The skinmesh node provides a specialized mesh where the texture is stretched and contorted as the model moves to provide a more realistic look to skin.

Offset Type Description
0 Node Header Common node header

The AnimMesh Node

(size 680 bytes)

The animmesh nodes are used for the game's GUI.

Offset Type Description
0 Node Header Common node header

The DanglyMesh Node

(size 648 bytes)

The danglymesh node provides a model with the look of movement by allowing faces to move due to momentum even after the whole model has stopped.

Offset Type Description
0 Node Header Common node header

The AABBMesh Node

(size 628 bytes)

The aabbmesh node provides the game with the ability to test for collisions.

Offset Type Description
0 Node Header Common node header

Mesh Header

(size ??? bytes)

All nodes that contain mesh information share a common header.

Offset Type Description
0 Node Header Common node header

Arrays and Pointers in a Model File

The structure of the model is reasonably complex. Not only does it contain structures of data, but those structures reference other structures. This is accomplished using arrays and pointers.

There are two types of pointers inside of a model file, model data pointer and raw data pointer. Each of these pointers are stored as a 32 bit value. In the case of model data pointers, the pointer will contain an offset from the start of the model data to the data in question. A value of zero represents a "NULL" pointer or a pointer that doesn't reference anything. For raw data pointers, the pointer will contain an offset from the start of the raw data to the data in question. A value of 0xFFFFFFFF (unsigned) or -1 (signed) represents a "NULL" pointer or a pointer that doesn't reference anything. The reason the raw data uses a value of -1 is that an offset of zero is a valid pointer into the raw data. Excluding one special case, this isn't true for model data pointers. (Only one element in a binary model file points to the data at offset zero in the model data. However, this value is transient and isn't actually stored in the model file.)

Some of you might be wondering why I am referring to these offsets as pointers. After all, in the binary model format, they are always offsets and never actually a real pointer. That is very true for the disk image of a model. However, on 32 bit address processors (or processors such as the Alpha that can run in 32 bit address mode with sign extend), after the model is loaded from disk, all the offsets can be converted to pointers. This improves greatly the run time performance.

Arrays in models are a slightly more complicated beast. They consist of the following three elements.

Offset Type Description
0 UINT32 Pointer/Offset to the first element of the array
4 UINT32 Number of used entries in the array
8 UINT32 Number of allocated entries in the array

For binary model files, the number of used entries and number of allocated entries will always be the same. During run time or compilation time, these values will usually differ since these arrays by nature will grow as more elements are added.

Arrays can contain most anything as long as the elements are all the same type. Examples of common arrays in model files would be arrays of vertices, faces, and even pointers. In the case of pointers, these arrays are commonly used to represent a model hierarchy.

Model Routines and Node Types

Every node contains a 32-bit bit-mask that identifies which structures make up the node. Following is a list of all the flags.

Value Description
0x00000001 HasHeader
0x00000002 HasLight
0x00000004 HasEmitter
0x00000010 HasReference
0x00000020 HasMesh
0x00000040 HasSkin
0x00000080 HasAnim
0x00000100 HasDangly
0x00000200 HasAABB

Every node contains a node header. In the case of a dummy node, only a node header is required. All mesh nodes also contain a mesh structure. In the case of a trimesh node, only the node header and the mesh header is required. By looking at a combination of flags, not only do we know what structures make up the node, but we know what the node type is.

Value Description
0x00000001 Dummy
0x00000003 Light
0x00000005 Emitter
0x00000011 Reference
0x00000021 TriMesh
0x00000061 SkinMesh
0x000000A1 AnimMesh
0x00000121 DanglyMesh
0x00000221 AABBMesh

As you can see, each of the different node types contains one or more flags.

Personal tools