GMDC Data Structure - Revision history

WesHowe: A Datacentric View of the GMDC

2007-01-09T02:12:38Z

A Datacentric View of the GMDC

WesHowe at 02:02, 9 January 2007

2007-01-09T02:02:23Z

Show changes

WesHowe at 01:48, 9 January 2007

2007-01-09T01:48:48Z

WesHowe at 01:44, 9 January 2007

2007-01-09T01:44:56Z

WesHowe at 01:42, 9 January 2007

2007-01-09T01:42:23Z

New page

A Datacentric View of the GMDC

There are six major divisions used in building a GMDC: Header, Elements, Linkages, Groups, Model and Subset.

The general structure of the file is the header followed by each of the other blocks. Each block begins with a count of the component parts (which have various sizes) that enable it to be read as a stream. One common technique is the use of a modified ‘pascal’ style string for names. This string has the first byte, in the range of 0 to 128, indicating the number of characters to follow, followed by that many characters.

Header:
The Header is built from standard DBPF RCOL package identifier properties. Instead of discussing the RCOL layout, we will describe it as it applies to the GMDC below:

short Language; // 1
short StringStyle; // 0xffff
long RepeatValue // 0
long IndexValue; // 1 (possibly larger if more than one GMDC)
long FileType; // 0xAC4F8687 (GMDC identifier)
char NameLen; // bytes (0 – 128) in following name
char Name[NameLen]; // ‘cGeometryDataContainer’
long BlockID; // 0xAC4F8687
long Version; // 1, 2 or 4 used
char NameLen; // bytes (0 – 128) in following name
char Name[NameLen]; // ‘cSGResource’
long ResourceID; // 0
long ResourceVersion; // 2
char NameLen; // bytes (0 – 128) in following name
char FileName[NameLen] // ex: ‘afBodyNaked_tslocator_gmdc’

Some possibilities exist in the RCOL definition for the start of the header to differ. Generally, to load a GMDC you check the values against this list for a sanity check, and then retain the Version (1, 2 or 4) and the FileName. The size of the header is 67 bytes plus the number of characters in the filename plus one.

When creating a GMDC, building the header is as simple as writing out the 67 bytes before the filename, writing out a one-byte filename length, and the writing out the filename. Most of the meshes use Version = 4 in the game files, so consistently outputting a version 4 will simplify the job.

Elements:

The Elements section is a collection of typed data arrays, the basic mesh elements, that will be referenced later when the face structure is defined.

long NumRecs; // count of total elements
long Identity; // typing value, detailed later
long RepeatCount; // count of repeats for the same type
long BlockFormat; // data element sizes (detailed below)
long SetGroup; // elements formats (detailed below)
long BlockSize; // number of bytes that follow (calculate)
char Block[BlockSize]; // these may be sets of floats or bytes
long ItemCount; // number of 2 or 4 byte elements to follow

Only one of the following two apply (per version value):

short Array2[ItemCount]; // used when version == 4
long Array4[ItemCount]; // used for versions 1 and 2

The Identity field is a value from the following list:

0x1C4AFC56 Blend Indices
0x5C4AFC5C Blend Weights
0x7C4DEE82 Target Indices
0xCB6F3A6A Morph Normal Deltas
0xCB7206A1 Colour
0xEB720693 Colour Deltas
0x3B83078B Normals List
0x5B830781 Vertices
0xBB8307AB UV Coordinates
0xDB830795 UV Coordinate Deltas
0x9BB38AFB Binormals
0x3BD70105 Skin (Bone) Weights
0xFBD70111 Bone Assignments
0x89D92BA0 Bump Map Normals
0x69D92B93 Bump Map Normal Deltas
0x5CF2CFE1 Morph Vertex Deltas
0xDCF2CFDC Morph Vertex Map
0x114113C3 (EP4) VertexID
0x114113CD (EP4) RegionMask

The BlockFormat is one of these four values:

0x00 single float (4 byte length)
0x01 paired floats (8 total bytes)
0x02 triple floats (12 bytes total)
0x04 unsigned long or bytes (4 bytes)

The SetGroups are one of the following values:

0x00 Main
0x01 Norms
0x02 UV
0x03 Secondary

Usage:
The elements are generally collects of vertices, normals, UVs, morph values, bone assignments and skin weights that are tied together by the face references to build a 3D object.

Elements appear ordered in sets. There is usually an empty set of each used Identity that comes first, followed by one or more referenced sets. The empty sets appears necessary, perhaps to allocate storage space.

A set of Identities will be built as matched arrays, that is, one of the basic size units (per BlockFormat) of each set will align with the vertex of the same index. While many elements appear only when mesh features are used, the first and each subsequent vertex will have a corresponding element in each included set. What we mean here is that the first vertex will correspond with the first normal, the first UV, the first bone assignment and so on.

The following discussion lists the main types used in Sims2 meshes in the order they are normally found (all but the first two are essentially optional, being present only when needed to support a mesh property):

Vertices (0x5B830781 [format 0x02]) – These are the main building elements, and are a set of coordinates in local 3D space for a point, normally one corner of a triangle. Each vertex has three floats of four bytes each (IEEE single-precision floating point number).

Normals (0x3B83078B [format 0x02]) – These are standard vertex normals. Like the vertices, they are three floats, but represent a vector in space, and thus are normalized (all values are smaller than 1.0).

UV Coordinates (0xBB8307AB [format 0x01]) – These are paired floats that represent the fractional distance from the upper-left corner to map the vertex into the texture map.

UV Coordinate Deltas (0xDB830795 [format 0x04]) – The purpose of these is undetermined, and may be misnamed. They are normally empty occurring only in the initial set of elements, but sometimes are found in the regular sets.

Target Indices (0x7C4DEE82 [format 0x02]) – These only appear in the empty initial set of elements. They have an ordinal relationship with the morph names, but do not appear to be needed by the loader. The contents, when present, have both vertices and vertex indices that are believed to be offsets to the Subset (Bounding Mesh) group when the corresponding morph is active. This is usually the only element that has a set of items after the Block.

Bone Assignments (0xFBD70111 [format 0x04]) – There are four bytes here. If this element is present, the first byte (lsb if read as a long) is the main bone assignment. A value of 255 (-1) means no bone is assigned, otherwise the value is the bone index (defined later). So, up to four bone assignments are available per-vertex.

Skin (Bone) Weights (0x3BD70105 [format 0x00, 0x01 or 0x02]) – This element is present if the Bone Assignments element is present. While there are four slots to assign bones, the usage is determined by the Skin Weights. A single weight section will normally always contain values of 1.0, indicating that all the influence on the skin will be obtained from the first bone assignment. A dual weight section will have two weights per vertex that should total exactly 1.0. Depending on the animation needs, this may be all weighted on one assignment or spread between two. A three weight section will support three or four bone assignments. Three is the simple one-to-one correspondence with the bone assignments, and the total weighting should add up to 1.0 (failing to total 1.0 will result in animation and other display issues). Three weights may also be made to work with four bone assignments by implying the fourth weight. This is done by adding the three weights up and subtracting the sum from 1.0. The difference is the weight to be applied to the fourth assignment. For example, spreading four assignments equally would have weights of 0.25, 0.25 and 0.25, these total 0.75 and thus leave 0.25 when subtracted, which is the weighting to be applied to the fourth assignment.

Morph Vertex Deltas (0x5CF2CFE1 [format 0x02]) -

If there are morphs present in the GMDC, then there will be at least one Morph Vertex Deltas (MVD) section, optionally a matching Morph Normal Delta (MND) plus a Morph Vertex Map (MVM). There can be up to four MVD sections per Vertex element. Each of the MVD elements is not a complete morph, but rather a data repository that holds values that are to be added to a vertex (a delta value) when a morph is triggered. How these are keyed is through the MVM element.

Morph Normal Deltas (0xCB6F3A6A [format 0x02]) -

When these are used, they are deltas to adjust the normals for a morph. If they are used, they are aligned with the MVD because the same morph map is used for both types.

Morph Vertex Map (0xDCF2CFDC [format 0x04]) -

The Morph Vertex Map is a collection of 4-byte morph name index values that map the MVD and MND to a vertex for a particular morph. The limit of 4-bytes to the format means that any one vertex can have no more than four morphs. How this map works is that in a section we haven’t reviewed yet there is a set of morph (blend) name pairs. Each of these has an implied index value based on its position on the list (starting at zero). Every legal value to be used in a morph map should have a morph name pair. The first of each 4-byte set maps an index value to the first MVD that is grouped with the vertices. The next byte maps to the second MVD, and so on, to the third and fourth sets (if used). The end result is that when a specific target value, e.g. 1, is present in the first byte, when the morph is triggered the game will add the delta values from the first MVD to the vertex coordinates to alter the mesh shape. If the ‘1’ had been in the second byte instead, the delta values used would have been from the second MVD element.

Bump Map Normals (0x89D92BA0) – These are also known as Tangent Normals, and are used to define a ray that would lie on plane tangent to the vertex. This is used for allowing bump maps to alter the apparent height of the surface. While it would have been possible for the game to calculate these at run time, by pre-calculating these values at mesh creation time the loading time is reduced.

Linkages:

The linkages section groups elements into sets. Although their position in the elements section is generally ordered by groupings, it is through this part that they are linked to the face definitions.

long Count; // count of total sets

for each Count:

long IndexCount; // number of indexes in block A

one of the following, per version

short Indices[IndexCount]; // for version == 4
long Indices[IndexCount]; // for versions 1 and 2

Repeat for Blocks B, C and D (generally unused).

The values for Indices are the applicable index value for an element block from the previous section. Generally, there will be at least two values here, Vertices and Normals, likely a third, UVs, sometimes Target Indices, and then (if used) Bone Assignments, Skin Weights, Morph Vertex Deltas(s), Morph Normal Deltas and a Morph Map, and maybe the Bump Map Normals.

The sets from this section are indexed, and may be referenced by more than one set of triangles (group), or there may be a one-to-one relationship between groups and sets, or the two may be mixed.

Groups:

This section is where the triangle sets, or groups, are defined and stored. Each group will have a link index, which indicates the sets grouping definition from the Linkages section, and each triangle consists of three vertex indices, each of which then indicates which vertex and all associated elements are to be used.

long Count; // count of total groups

For each group:

long PrimitiveType; // default = 2
long LinkIndex; // Index of set from Linkages section
char NameLen; // bytes (0 – 128) in following name
char Name[NameLen]; // group name
long FaceCt; // actually faces*3 (number of triangle points)

One of the following two, per version:

short VertexIndex[FaceCt]; // version == 4
long VertexIndex[FaceCt]; // versions 1 and 2

long Opacity; // alpha value. 0xffffffff for opaque.
long SubsetCount // versions 2 and 4 only
short SubsetIndices[SubsetCount]; // version 4 only
long SubsetIndices[SubsetCount]; // version 2 only

The SubsetIndices map the standard bone values, as defined in the CRES, to the values used in the GMDC Bone Assignment elements. The mapping works by using the Bone Assignment value as the index, and retrieving the Standard Bone Value from the array. The SubsetCount should be equal to the number of bones actually referenced in the group, or animation difficulties will be encountered.

Model:

This contains the joint definitions, expressed as sets of 7 float values known as Quaternions, the morph names and for non-IK animated meshes a model of the entire entity, consisting of only vertices and faces, which is used as a bounding mesh for the game to use to determine intersection on mouse-clicks.

long Count // number of transform blocks
float Quaternion[Count][7]; // ordered: x,y,z,w rotation; x,y,z transform
long PairCt; // number of morph name pairs

PairCount number of:

char NameLen1; // bytes (0 – 128) in following name
char Name[NameLen1]; // blend group name
char NameLen2; // bytes (0 – 128) in following name
char Name[NameLen2]; // assigned element name

long VCount; // number of vertices in Model

If VertexCount == 0, then skip the next items

long FCount; // number of faces(*3) in model
float Vertices[VCount][3]; // XYZ for each vertex

Use one of the following two items, per version:

short Faces[FCount]; // version == 4
long Faces[FCount]; // versions 1 and 2

The transform blocks are values used to translate and then rotate a point from 0,0,0 to the joint position via a Quaternion. The name pairs are the morph names. The paired index position indicates the target value (one or more of these names may be empty) that is used in the Morph Map(s).

The Model is used where there is no IK animation (essentially models that are not hair, body, clothing, face or pet meshes). It can be built by placing all the vertices from all the groups into the single Vertices array and then putting all the faces together in the Faces array, making sure to add the number of previous group vertices to each point vertex index. A more sophisticated algorithm would eliminate all duplicate vertices as it built the Vertices and Faces arrays. This is more computationally intensive at mesh creation time, but creates a smaller output file and will reduce the memory and computation time required at run time.

Subset:

Essentially, the Subset section replaces the Model portion of the Model section. It serves the same purpose, but the Subset is defined bone-by-bone, and the vertex position values have been reverse-rotated and then translated using the transform blocks from the Model section.

long SubCount; // number of subsets (one per transform)

One of each for each SubCount:

long VCount; // number of vertices for this bone

The rest of the items only if VCount is not zero:

long FCount; // number of faces(*3)
float Vertices[VCount][3]; // XYZ (transformed) for each vertex

One of the following two, per version:

short Faces[FCount]; // version == 4
long Faces[FCount]; // versions 1 and 2

This transformed bounding mesh, sorted by bone, is used in IK animated models so that the bounding mesh can be reshaped to fit the model by using the transforms that represent the bone positions at the time it is needed.

@@ Line 154: / Line 154: @@
 <code>
-	long	Count;			// count of total groups
+        long    Count;                     // count of total groups
 	For each group:
-	long	PrimitiveType;		// default = 2
+        long    PrimitiveType;             // default = 2
-	long	LinkIndex;		// Index of set from Linkages section
+        long    LinkIndex;                 // Index of set from Linkages section
-	char	NameLen;		// bytes (0 – 128) in following name
+        char    NameLen;                   // bytes (0 – 128) in following name
-	char	Name[NameLen];	// group name
+        char    Name[NameLen];             // group name
-	long	FaceCt;		// actually faces*3 (number of triangle points)
+        long    FaceCt;                    // faces*3 (number of triangle points)
 	One of the following two, per version:
-	short	VertexIndex[FaceCt];	// version == 4
+        short   VertexIndex[FaceCt];       // version == 4
-	long	VertexIndex[FaceCt];	// versions 1 and 2
+        long    VertexIndex[FaceCt];       // versions 1 and 2
-	long	Opacity;		// alpha value. 0xffffffff for opaque.
+        long    Opacity;                   // alpha value. 0xffffffff for opaque.
-         long	SubsetCount		// versions 2 and 4 only
+         long    SubsetCount;               // versions 2 and 4 only
-	short	SubsetIndices[SubsetCount];	// version 4 only
+        short   SubsetIndices[SubsetCount];// version 4 only
-	long	SubsetIndices[SubsetCount];	// version 2 only
+        long    SubsetIndices[SubsetCount];// version 2 only
 </code>
@@ Line 182: / Line 182: @@
 <code>
-	long	Count			// number of transform blocks
+        long    Count                  // number of transform blocks
-	float	Quaternion[Count][7];	// ordered: x,y,z,w rotation; x,y,z transform
+        float   Quaternion[Count][7];  // ordered: x,y,z,w rotation; x,y,z transform
-	long	PairCt;			// number of morph name pairs
+        long    PairCt;                // number of morph name pairs
-	PairCount number of:
+        PairCount number of:
-	char	NameLen1;		// bytes (0 – 128) in following name
+        char    NameLen1;              // bytes (0 – 128) in following name
-	char	Name[NameLen1];	// blend group name
+        char    Name[NameLen1];        // blend group name
-	char	NameLen2;		// bytes (0 – 128) in following name
+        char    NameLen2;              // bytes (0 – 128) in following name
-	char	Name[NameLen2];	// assigned element name
+        char    Name[NameLen2];        // assigned element name
-	long	VCount;		// number of vertices in Model
+        long    VCount;                // number of vertices in Model
-	If VertexCount == 0, then skip the next items
+        If VertexCount == 0, then skip the next items
-	long	FCount;		// number of faces(*3) in model
+        long    FCount;                // number of faces(*3) in model
-	float	Vertices[VCount][3];	// XYZ for each vertex
+        float   Vertices[VCount][3];   // XYZ for each vertex
-−
-	Use one of the following two items, per version:
-	short	Faces[FCount];	// version == 4
+        Use one of the following two items, per version:
-	long	Faces[FCount];	// versions 1 and 2
 </code>
@@ Line 214: / Line 214: @@
 <code>
-	long	SubCount;		// number of subsets (one per transform)
+        long    SubCount;               // number of subsets (one per transform)
-	One of each for each SubCount:
+        One of each for each SubCount:
-	long	VCount;		// number of vertices for this bone
+        long    VCount;                 // number of vertices for this bone
-	The rest of the items only if VCount is not zero:
+        The rest of the items only if VCount is not zero:
-	long	FCount;		// number of faces(*3)
+        long    FCount;                 // number of faces(*3)
-	float	Vertices[VCount][3];	// XYZ (transformed) for each vertex
+	float   Vertices[VCount][3];    // XYZ (transformed) for each vertex
-	One of the following two, per version:
+        One of the following two, per version:
-	short	Faces[FCount];	// version == 4
+        short   Faces[FCount];          // version == 4
-	long	Faces[FCount];	// versions 1 and 2
+        long    Faces[FCount];          // versions 1 and 2
 </code>
 This transformed bounding mesh, sorted by bone, is used in IK animated models so that the bounding mesh can be reshaped to fit the model by using the transforms that represent the bone positions at the time it is needed.

@@ Line 10: / Line 10: @@
 <code>
          short   Language;               // 1
-	short	StringStyle;		// 0xffff
+        short   StringStyle;            // 0xffff
-	long 	RepeatValue		// 0
+        long    RepeatValue;            // 0
-	long	IndexValue;		// 1  (possibly larger if more than one GMDC)
+        long    IndexValue;             // 1 (or larger if more than one GMDC)
-	long	FileType;		// 0xAC4F8687 (GMDC identifier)
+        long    FileType;               // 0xAC4F8687 (GMDC identifier)
-	char	NameLen;		// bytes (0 – 128) in following name
+        char    NameLen;                // bytes (0 – 128) in following name
-	char	Name[NameLen];	// ‘cGeometryDataContainer’
+        char    Name[NameLen];          // ‘cGeometryDataContainer’
-	long	BlockID;		// 0xAC4F8687
+        long    BlockID;                // 0xAC4F8687
-	long	Version;		// 1, 2 or 4 used
+        long    Version;                // 1, 2 or 4 used
-	char	NameLen;		// bytes (0 – 128) in following name
+        char    NameLen;                // bytes (0 – 128) in following name
-	char	Name[NameLen];	// ‘cSGResource’
+        char    Name[NameLen];          // ‘cSGResource’
-	long	ResourceID;		// 0
+        long    ResourceID;             // 0
-	long	ResourceVersion;	// 2
+        long    ResourceVersion;        // 2
-	char	NameLen;		// bytes (0 – 128) in following name
+        char    NameLen;                // bytes (0 – 128) in following name
-	char	FileName[NameLen]	// ex: ‘afBodyNaked_tslocator_gmdc’
+        char    FileName[NameLen];      // ex: ‘afBodyNaked_tslocator_gmdc’
 </code>