Santos
28th Mar 10, 10:30 AM
Relic MODEL file format [WIP]
v1.0
NOTE: This is going to be quite a long story so I'm not going to write everything all at once.
The purpose of this thread is to document Relic's MODEL file format used in Dawn of War 2. MODEL files contain basic elements required to display models in game: materials, meshes, skeleton and markers. I should point out that the description below is based on my own understanding of the format and might be wrong in few places. However since I actually managed to write a working model exporter based on this data, it can be safely assumed that it's almost entirely correct (if not 100% right).
To figure out the format I used some common reverse engineering techniques. This included analyzing certain values in every MODEL file shipped with the game (this was done however pre Chaos Rising). This means I can say with certain level of confidence that some values are fixed and can be safely ignored even though I may not know their purpose.
Below is a short explanation of the way MODEL format is described in this document:
MODEL files use the common format known as Relic Chunky.
TODO: Add Relic Chunky file format description (unless someone already have done this?)
Data types:
BOOL - 8-bit integer, true (1) or false (0)
BYTE - 8-bit integer (signed or unsigned)
SHORT - 16-bit integer (signed or unsigned)
LONG - 32-bit integer (signed or unsigned)
FLOAT - 32-bit single precision floating-point number (signed)
STRING - character string preceded by it's length (32-bit unsigned integer)
MATRIX - matrix of floats (4x3, 48 bytes total), defines position and rotation in 3D space
DATA - raw data (bytes)
Control structures:
IF (condition) THEN
---- (do something)
FOR (count) DO
---- (do something)
Overall structure:
-FOLDMODL [1]
--FOLDMTRL [0-N]
---DATAINFO [1]
---DATAVAR [0-N]
--FOLDMESH [0-N]
---FOLDMGRP [1]
----FOLDMESH [0-N]
-----FOLDIMDG [1]
------FOLDMESH [0-N]
-------FOLDIMOD [1]
--------DATADATA [1]
--------FOLDMESH [0-N]
---------FOLDTRIM [1]
----------DATADATA [1]
----------DATABVOL [1-N]
----DATANODE [0-N]
--DATAMRKS [1]
--FOLDSKEL [1]
---DATAINFO [1]
---DATABONE [0-N]
--FOLDMSBP [1]
---DATAMSD [1]
---DATAMSD [1-N]
---DATACNBP [1-N]
--DATADTBP [1]
Number of dashes (-) denote chunk's level (with single dash being the root). Number in brackets tells how many times given chunk can appear (value of N means 'any number of times').
Materials
Materials define how model will be rendered in game. Every material must point to a shader file (INFO chunk). Optionally it can also provide input values for various shader variables. These can be textures or some other numeric parameters. Multiple materials can be defined inside MODEL file. Every material should be defined in it's own MTRL chunk under MODL root folder.
MTRL (type: Folder, version: 1, flag: 0, name: [Material Name])
-------------------------------------------------------------
Notes:
- chunk's name is the name of the entire material
INFO (type: Data, version: 1, flag: -1, name: 'Material Info')
----------------------------------------------------------
STRING shader_name
Notes:
- shader_name points to a file in 'shaders' directory under archive root (only file name, no extension)
0VAR (type: Folder, version: 1, flag: -1, name: 'Material Variable')
---------------------------------------------------------------
STRING variable_name
LONG variable_type
LONG variable_value_size
DATA variable_value
Notes:
- 0 in chunk's ID is a byte with value of 0 (0x00) not a zero character (which has value of 48)
- variable_value has size (number of bytes) equal to variable_value_size
- variable_type can be one of the following:
0 - Integer (single 4-byte integer value)
1 - Float (single 4-byte float value)
3 - Vector2 (vector of 2 floats, 8 bytes)
4 - Vector3 (vector of 3 floats, 12 bytes)
5 - Vector4 (vector of 4 floats, 16 bytes)
8 - Matrix4x4 (matrix of 16 floats, 64 bytes)
9 - Texture (texture name, relative to archive root directory, ends with 0)
10 - Boolean (1-byte integer, 0 or 1)
Meshes
TODO...
Bones
Bones are stored inside SKEL folder. First child chunk of SKEL is called INFO and contains total number of bones in the skeleton. BONE chunk represents a single bone. Number of BONE chunks is equal to the value stored in INFO chunk.
SKEL (type: Data, version: 3, flag: 0)
------------------------------------
INFO (type: Data, version: 1, flag: -1)
-------------------------------------
LONG number_of_bones_in_the_skeleton
BONE (type: Data, version: 7, flag: 1)
-------------------------------------
LONG bone_parent_id
LONG unknown1
MATRIX bone_transform_matrix
LONG unknown2
LONG unknown3
Notes:
- bone_parent_id is an index of bone previously added to the skeleton. Bones are created in order they appear in the file. First bone created has index 0, second 1 etc. Skeleton root has bone_parent_id set to -1
- unknown1 is always -1 (FF FF FF FF)
- for bones without parent, transforms are stored in world coordinates. If bone has a parent, transforms are stored in parent coordinates.
- unknown2 and unknown3 are always 0
Markers
Markers are named points defined in 3D space. Marker can be linked to any bone in the skeleton. All markers are stored inside one data chunk with MRKS id.
MRKS (type: Data, version: 1, flag: -1)
--------------------------------------
LONG number_of_markers
FOR (number_of_markers) DO
----STRING marker_name
----STRING parent_bone_name
----MATRIX transform_matrix
----LONG number_of_marker_parameters
----FOR (number_of_marker_parameters) DO
--------STRING marker_parameter_key
--------LONG unknown
--------STRING marker_parameter_value
Notes:
- parent_bone_name length should be 0 if bone has no parent
- unknown has always value of 11
- marker_parameter_value is always a string even if parameter value is of numeric type
Parameters: (possible values in brackets)
- marker_field_of_fire = ('0')
- marker_destruction_level = ('0', '2', '3', '4')
- marker_type = ('synckill', 'spawn point', 'entrance', 'combat slot')
- marker_subtype = ('vehicle', 'human')
Model States
TODO...
Data Templates
This chunk is described in Motion Tree file format reference (TODO)
In model files this chunk should contain only following items:
State Machine: 'damage_state'
- states: 'healthy', 'light_damage', 'heavy_damage', 'wreck'
- default state: 'healthy'
Variable: 'health'
- value: 1.0
- min: 0.0
- max: 1.0
Both items are optional if model has attached motion tree file which defines them too.
to be continued...
v1.0
NOTE: This is going to be quite a long story so I'm not going to write everything all at once.
The purpose of this thread is to document Relic's MODEL file format used in Dawn of War 2. MODEL files contain basic elements required to display models in game: materials, meshes, skeleton and markers. I should point out that the description below is based on my own understanding of the format and might be wrong in few places. However since I actually managed to write a working model exporter based on this data, it can be safely assumed that it's almost entirely correct (if not 100% right).
To figure out the format I used some common reverse engineering techniques. This included analyzing certain values in every MODEL file shipped with the game (this was done however pre Chaos Rising). This means I can say with certain level of confidence that some values are fixed and can be safely ignored even though I may not know their purpose.
Below is a short explanation of the way MODEL format is described in this document:
MODEL files use the common format known as Relic Chunky.
TODO: Add Relic Chunky file format description (unless someone already have done this?)
Data types:
BOOL - 8-bit integer, true (1) or false (0)
BYTE - 8-bit integer (signed or unsigned)
SHORT - 16-bit integer (signed or unsigned)
LONG - 32-bit integer (signed or unsigned)
FLOAT - 32-bit single precision floating-point number (signed)
STRING - character string preceded by it's length (32-bit unsigned integer)
MATRIX - matrix of floats (4x3, 48 bytes total), defines position and rotation in 3D space
DATA - raw data (bytes)
Control structures:
IF (condition) THEN
---- (do something)
FOR (count) DO
---- (do something)
Overall structure:
-FOLDMODL [1]
--FOLDMTRL [0-N]
---DATAINFO [1]
---DATAVAR [0-N]
--FOLDMESH [0-N]
---FOLDMGRP [1]
----FOLDMESH [0-N]
-----FOLDIMDG [1]
------FOLDMESH [0-N]
-------FOLDIMOD [1]
--------DATADATA [1]
--------FOLDMESH [0-N]
---------FOLDTRIM [1]
----------DATADATA [1]
----------DATABVOL [1-N]
----DATANODE [0-N]
--DATAMRKS [1]
--FOLDSKEL [1]
---DATAINFO [1]
---DATABONE [0-N]
--FOLDMSBP [1]
---DATAMSD [1]
---DATAMSD [1-N]
---DATACNBP [1-N]
--DATADTBP [1]
Number of dashes (-) denote chunk's level (with single dash being the root). Number in brackets tells how many times given chunk can appear (value of N means 'any number of times').
Materials
Materials define how model will be rendered in game. Every material must point to a shader file (INFO chunk). Optionally it can also provide input values for various shader variables. These can be textures or some other numeric parameters. Multiple materials can be defined inside MODEL file. Every material should be defined in it's own MTRL chunk under MODL root folder.
MTRL (type: Folder, version: 1, flag: 0, name: [Material Name])
-------------------------------------------------------------
Notes:
- chunk's name is the name of the entire material
INFO (type: Data, version: 1, flag: -1, name: 'Material Info')
----------------------------------------------------------
STRING shader_name
Notes:
- shader_name points to a file in 'shaders' directory under archive root (only file name, no extension)
0VAR (type: Folder, version: 1, flag: -1, name: 'Material Variable')
---------------------------------------------------------------
STRING variable_name
LONG variable_type
LONG variable_value_size
DATA variable_value
Notes:
- 0 in chunk's ID is a byte with value of 0 (0x00) not a zero character (which has value of 48)
- variable_value has size (number of bytes) equal to variable_value_size
- variable_type can be one of the following:
0 - Integer (single 4-byte integer value)
1 - Float (single 4-byte float value)
3 - Vector2 (vector of 2 floats, 8 bytes)
4 - Vector3 (vector of 3 floats, 12 bytes)
5 - Vector4 (vector of 4 floats, 16 bytes)
8 - Matrix4x4 (matrix of 16 floats, 64 bytes)
9 - Texture (texture name, relative to archive root directory, ends with 0)
10 - Boolean (1-byte integer, 0 or 1)
Meshes
TODO...
Bones
Bones are stored inside SKEL folder. First child chunk of SKEL is called INFO and contains total number of bones in the skeleton. BONE chunk represents a single bone. Number of BONE chunks is equal to the value stored in INFO chunk.
SKEL (type: Data, version: 3, flag: 0)
------------------------------------
INFO (type: Data, version: 1, flag: -1)
-------------------------------------
LONG number_of_bones_in_the_skeleton
BONE (type: Data, version: 7, flag: 1)
-------------------------------------
LONG bone_parent_id
LONG unknown1
MATRIX bone_transform_matrix
LONG unknown2
LONG unknown3
Notes:
- bone_parent_id is an index of bone previously added to the skeleton. Bones are created in order they appear in the file. First bone created has index 0, second 1 etc. Skeleton root has bone_parent_id set to -1
- unknown1 is always -1 (FF FF FF FF)
- for bones without parent, transforms are stored in world coordinates. If bone has a parent, transforms are stored in parent coordinates.
- unknown2 and unknown3 are always 0
Markers
Markers are named points defined in 3D space. Marker can be linked to any bone in the skeleton. All markers are stored inside one data chunk with MRKS id.
MRKS (type: Data, version: 1, flag: -1)
--------------------------------------
LONG number_of_markers
FOR (number_of_markers) DO
----STRING marker_name
----STRING parent_bone_name
----MATRIX transform_matrix
----LONG number_of_marker_parameters
----FOR (number_of_marker_parameters) DO
--------STRING marker_parameter_key
--------LONG unknown
--------STRING marker_parameter_value
Notes:
- parent_bone_name length should be 0 if bone has no parent
- unknown has always value of 11
- marker_parameter_value is always a string even if parameter value is of numeric type
Parameters: (possible values in brackets)
- marker_field_of_fire = ('0')
- marker_destruction_level = ('0', '2', '3', '4')
- marker_type = ('synckill', 'spawn point', 'entrance', 'combat slot')
- marker_subtype = ('vehicle', 'human')
Model States
TODO...
Data Templates
This chunk is described in Motion Tree file format reference (TODO)
In model files this chunk should contain only following items:
State Machine: 'damage_state'
- states: 'healthy', 'light_damage', 'heavy_damage', 'wreck'
- default state: 'healthy'
Variable: 'health'
- value: 1.0
- min: 0.0
- max: 1.0
Both items are optional if model has attached motion tree file which defines them too.
to be continued...