Difference between revisions of "FMDL (File Format)"

From MK8
Jump to: navigation, search
(FMAT: Had a revelation on the meaning of attribute selectors.)
(FSHP: Information from latest experiments with generating models.)
Line 945: Line 945:
  
 
The model may have one or more '''FSHP''' sections which describe the one polygon (e.g. the road of a track). The FSHP section consists of an 0x40 byte header, which references an '''[[#FVTX|FVTX]]''' section and indices of the polygons to draw. A basic '''FSHP''' amounts to a list of indices into the corresponding '''FVTX''' indicating which points to draw triangles between. The '''FSHP''' also references an '''[[#FMAT|FMAT]]''' to describe the material of the triangles, and an '''[[#FSKL|FSKL]]''' to indicate the bone structure of the model used in animation.
 
The model may have one or more '''FSHP''' sections which describe the one polygon (e.g. the road of a track). The FSHP section consists of an 0x40 byte header, which references an '''[[#FVTX|FVTX]]''' section and indices of the polygons to draw. A basic '''FSHP''' amounts to a list of indices into the corresponding '''FVTX''' indicating which points to draw triangles between. The '''FSHP''' also references an '''[[#FMAT|FMAT]]''' to describe the material of the triangles, and an '''[[#FSKL|FSKL]]''' to indicate the bone structure of the model used in animation.
 +
 +
The triangles in an '''FSHP''' are organised by two systems; [[#LoD Model|LoD Models]] and [[#Visibility Group|Visibility Groups]]. No model in Mario Kart 8 uses both of these features non-trivially simultaneously. LoD stands for Level of Detail, which is a standard performance technique used across many 3d rendering systems. Each LoD model is a simpler version of the one before it, with extraneous triangles removed, and finer detail simplified. As the camera in the game moves away from a polygon, the simpler version of the model is rendered instead, which should look the same as the fine detailed version at a distance. A trivial polygon will only have one LoD model, which will be rendered no matter what distance the camera is. Separately, the Visibility Group system allows parts of the model to not be rendered if they are off-screen. This allows an polygon which is partially off-screen to be rendered faster, by skipping the off-screen components. A trivial polygon will only have one Visibility Group, which will always be rendered.
  
 
=== Header (FSHP) ===
 
=== Header (FSHP) ===
Line 993: Line 995:
 
| 0x17
 
| 0x17
 
| 1
 
| 1
| '''[[#Drawing Command|Drawing Command]] count'''. Number of elements in the array.
+
| '''[[#LoD Model|LoD Model]] count'''. Number of elements in the array.
 
|-
 
|-
 
| 0x18
 
| 0x18
 
| 4
 
| 4
| '''[[#Drawing Extent Tree|Drawing Extent Tree Node]] count'''.
+
| '''[[#Visibility Group Tree|Visibility Group Tree Node]] count'''.
 
|-
 
|-
 
| 0x1c
 
| 0x1c
Line 1,009: Line 1,011:
 
| 0x24
 
| 0x24
 
| 4
 
| 4
| '''[[#Drawing Command|Drawing Command]] offset'''. Offset to the first element in the array.
+
| '''[[#LoD Model|LoD Model]] offset'''. Offset to the first element in the array.
 
|-
 
|-
 
| 0x28
 
| 0x28
Line 1,021: Line 1,023:
 
| 0x30
 
| 0x30
 
| 4
 
| 4
| '''[[#Drawing Extent Tree|Drawing Extent Tree Nodes]] offset'''.
+
| '''[[#Visibility Group Tree|Visibility Group Tree Nodes]] offset'''.
 
|-
 
|-
 
| 0x34
 
| 0x34
 
| 4
 
| 4
| '''[[#Drawing Extent Tree|Drawing Extent Tree Ranges]] offset'''.
+
| '''[[#Visibility Group Tree|Visibility Group Tree Ranges]] offset'''.
 
|-
 
|-
 
| 0x38
 
| 0x38
 
| 4
 
| 4
| '''[[#Drawing Extent Tree|Drawing Extent Tree Indices]] offset'''.
+
| '''[[#Visibility Group Tree|Visibility Group Tree Indices]] offset'''.
 
|-
 
|-
 
| 0x3c
 
| 0x3c
Line 1,039: Line 1,041:
 
|}
 
|}
  
=== Drawing Command ===
+
=== LoD Model ===
  
A '''Drawing Command''' is a repeating 0x1c byte structure which are stored in a sequential array with location and size specified by the '''FSHP Header'''
+
An '''LoD Model''' is a repeating 0x1c byte structure which are stored in a sequential array with location and size specified by the '''[[#Header (FSHP)|FSHP Header]]'''. Their purpose is described at the beginning of this section.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 1,058: Line 1,060:
 
| 0x08
 
| 0x08
 
| 4
 
| 4
| '''Count''' of points drawn in all [[#Drawing Extent|Drawing Extent]]s.
+
| '''Count''' of points drawn in all [[#Visibility Group|Visibility Group]]s, thus the maximum number of points drawn at this LoD.
 
|-
 
|-
 
| 0x0c
 
| 0x0c
 
| 2
 
| 2
| '''[[#Drawing Extent|Drawing Extent]] count'''. The number of elements in the array.
+
| '''[[#Visibility Group|Visibility Group]] count'''. The number of elements in the array.
 
|-
 
|-
 
| 0x0e
 
| 0x0e
Line 1,070: Line 1,072:
 
| 0x10
 
| 0x10
 
| 4
 
| 4
| '''[[#Drawing Extent|Drawing Extent]] offset'''. Offset to the first element in the array.
+
| '''[[#Visibility Group|Visibility Group]] offset'''. Offset to the first element in the array.
 
|-
 
|-
 
| 0x14
 
| 0x14
Line 1,081: Line 1,083:
 
|-
 
|-
 
| 0x1c
 
| 0x1c
| colspan="2" {{Unknown|End of Drawing Command}}
+
| colspan="2" {{Unknown|End of LoD Model}}
 
|}
 
|}
  
=== Drawing Extent ===
+
=== Visibility Group ===
  
A '''Drawing Extent''' is a repeating 0x8 byte structure describing an offset and a count in the corresponding [[#Index Buffer|Index Buffer]]. Drawing Extents are stored in a sequential array with location and count indicated by the corresponding [[#Drawing Command|Drawing Command]]. This allows multiple separate drawing commands to be issued using the same Index Buffer. In many cases, a single extent is used which simply draws the entire Index Buffer.
+
A '''Visibility Group''' is a repeating 0x8 byte structure describing an offset and a count in the corresponding [[#Index Buffer|Index Buffer]]. Visibility Groups are stored in a sequential array with location and count indicated by the corresponding [[#LoD Model|LoD Model]]. This allows multiple visibility groups to use the same Index Buffer. In many cases, a single group is used which simply draws the entire Index Buffer.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 1,102: Line 1,104:
 
|-
 
|-
 
| 0x08
 
| 0x08
| colspan="2" {{Unknown|End of Drawing Extent}}
+
| colspan="2" {{Unknown|End of Visibility Group}}
 
|}
 
|}
  
 
=== Index Buffer ===
 
=== Index Buffer ===
  
An '''Index Buffer''' is an 0x18 byte structure which describes a list of 16 bit values which are used to index the '''FVTX''' section when drawing the polygon. Index Buffers are referenced by [[#Drawing Command|Drawing Command]]s. The format is very similar to the [[#Buffers|FVTX Buffer]] format, which may indicate they are instances of the same structure.
+
An '''Index Buffer''' is an 0x18 byte structure which describes a list of 16 bit values which are used to index the '''FVTX''' section when drawing the polygon. Index Buffers are referenced by [[#LoD Model|LoD Model]]s. The format is very similar to the [[#Buffers|FVTX Buffer]] format, which may indicate they are instances of the same structure.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 1,146: Line 1,148:
 
|}
 
|}
  
=== Drawing Extent Tree ===
+
=== Visibility Group Tree ===
  
The '''Drawing Extent Tree''' is some sort of tree structure that occurs in all FSHP sections. In all [[Mario Kart 8]] files, when the '''FSHP''' has multiple [[#Drawing Command|Drawing Command]]s, the Drawing Extent Tree is a trivial one node tree. The Drawing Extent Tree may be used to control which [[#Drawing Extent|Drawing Extent]]s need to be drawn, for example as part of a dynamic level of detail system. The true workings and purpose of the structure are however unknown.
+
The '''Visibility Group Tree''' is some sort of tree structure that occurs in all FSHP sections. In all [[Mario Kart 8]] files, when the '''FSHP''' has multiple [[#LoD Model|LoD Model]]s, the Visibility Group Tree is a trivial one node tree. The Visibility Group Tree is used to control which [[#Visibility Group|Visibility Group]]s need to be drawn as described at the beginning of this section. The workings of the structure are however unknown.
  
 
==== Nodes ====
 
==== Nodes ====
  
The '''Drawing Extent Tree Node''' is a repeating 0xc byte structure. The nodes form a binary tree. The [[#FSHP|FSHP header]] contains a pointer to node array, as well as specifying its length. The root node is the first node in this array. Each node specifies a range of Drawing Extents, with the root node always covering all nodes, and the children of each node always selecting disjoint subsets of that node's range.
+
The '''Visibility Group Tree Node''' is a repeating 0xc byte structure. The nodes form a binary tree. The [[#FSHP|FSHP header]] contains a pointer to node array, as well as specifying its length. The root node is the first node in this array. Each node specifies a range of Visibility Groups, with the root node always covering all nodes, and the children of each node always selecting disjoint subsets of that node's range.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 1,177: Line 1,179:
 
| 0x08
 
| 0x08
 
| 2
 
| 2
| '''[[#Drawing Extent|Drawing Extent]] Index''' selects a range of Drawing Extents along with the count.
+
| '''[[#Visibility Group|Visibility Group]] Index''' selects a range of Visibility Groups along with the count.
 
|-
 
|-
 
| 0x0a
 
| 0x0a
 
| 2
 
| 2
| '''[[#Drawing Extent|Drawing Extent]] Count''' selects a range of Drawing Extents along with the index.
+
| '''[[#Visibility Group|Visibility Group]] Count''' selects a range of Visibility Groups along with the index.
 
|-
 
|-
 
| 0x0c
 
| 0x0c
Line 1,189: Line 1,191:
 
==== Ranges ====
 
==== Ranges ====
  
The '''Drawing Extent Tree Range''' is a repeating 0x18 byte structure. The purpose is unknown. There are exactly as many Ranges as Nodes. The range appears to contain two 3D positions, which are not necessarily distinct.
+
The '''Visibility Group Tree Range''' is a repeating 0x18 byte structure. The meaning is unknown. There are exactly as many Ranges as Nodes. The range appears to contain two 3D positions, which are not necessarily distinct.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 1,210: Line 1,212:
 
==== Indices ====
 
==== Indices ====
  
The '''Drawing Extent Tree Index''' array is an array of 16 bit values which appear to be the index of the leaf node of the '''Drawing Extent Tree''' which contains the corresponding '''[[#Drawing Extent|Drawing Extent]]'''. Therefore this array has length equal to the number of [[#Drawing Extent|Drawing Extent]]s in the '''FSHP''' section.
+
The '''Visibility Group Tree Index''' array is an array of 16 bit values which appear to be the index of the leaf node of the '''Visibility Group Tree''' which contains the corresponding '''[[#Visibility Group|Visibility Group]]'''. Therefore this array has length equal to the number of [[#Visibility Group|Visibility Group]]s in the '''FSHP''' section.
  
 
== Parameter ==
 
== Parameter ==

Revision as of 08:03, 13 September 2014

The FMDL model format is a format for models which appears as a subfile of a BFRES file in the 0th file group. Typically a BFRES file has one FMDL but some have none and some have more than one.

Format

An FMDL file begins with an FMDL header. This is then followed by a number of sections pointed to by the header, many of which can occur multiple times. The purpose of these sections is described in the table below. Unless otherwise noted, all offsets in BFRES files are relative to themselves, not the beginning of the file which is more common in other formats.

Section Purpose
FVTX Describes an array of array of vertices which can have a number of attributes including position, normal, colour and texture coordinates.
FMAT Describes the properties of a surface necessary to draw it including texture information.
FSKL Describes a skeleton for the model which may be used in animations.
FSHP Selects triples of vertices from one FVTX section to draw triangles between. Also specifies the FMAT material and the FSKL attachment of the triangles.
Parameter Sets a named paramter for the model.

Header (FMDL)

Every FMDL begins with an 0x2c byte FMDL header.

Offset Size Description
0x00 4 "FMDL" file identifier, ASCII string.
0x04 4 File name offset (without file extension).
0x08 4 End of BFRES string table offset. Points to just after the last string in the string table.
0x0c 4 FSKL offset. Offset to the FSKL Header.
0x10 4 FVTX array offset. Offset to the first element in an array of FVTX Headers.
0x14 4 FSHP index group offset. Offset to an index group which contains named pointers to FSHP Headers.
0x18 4 FMAT index group offset. Offset to an index group which contains named pointers to FMAT Headers.
0x1c 4 Parameter index group offset. Offset to an index group which contains named pointers to parameter values. May be 0 if no parameters exist (common).
0x20 2 FVTX count: number of FVTX sections in the FVTX array.
0x22 2 FSHP count: number of FSHP sections in the the FSHP index group.
0x24 2 FMAT count: number of FMAT sections in the the FMAT index group.
0x26 2 Parameter count: number of parameters in the Parameter index group.
0x28 4 Unknown possibly something like an unused face count.
0x2c End of FMDL header

FVTX

The model may have one or more FVTX sections which describe the vertices for one polygon (e.g. the road of a track). The section describes a series of buffers and attributes. Buffers are arrays of arbitrary elements which contain the actual values of the vertices and are passed directly to the graphics card. Attributes are properties of vertices (e.g. position, texture coordinate, vertex colours) and they describe the format and layout of the elements in the buffers.

Header (FVTX)

Each FVTX section has a 0x20 byte header. These headers are stored sequentially in an array at the offset given in the FMDL header. The length of this array is also given in that header.

Offset Size Description
0x00 4 "FVTX" section identifier, ASCII string.
0x04 1 Attribute count: number of different attributes (position, normal, colour, etc) in the attribute array.
0x05 1 Buffer count: number of attribute buffers in the buffer array.
0x06 2 Section index: index into FVTX array of this entry.
0x08 4 Number of vertices. This is also the number of elements in each buffer.
0x0c 1 Unknown; values seen are between 0 and 4 (normally 0).
0x0d 3 Unknown always 0.
0x10 4 Attribute array offset. Offset to the first element in the Attribute array.
0x14 4 Attribute index group offset. Named pointers to the members of the Attribute array to allow named lookups.
0x18 4 Buffer array offset. Offset to the first element in the Buffer array.
0x1c 4 Padding, always 0.
0x20 End of FVTX header

Attributes

The attributes of each FVTX section are stored as a simple repeating 0xc byte structure. These are stored in an array with location and length specified by the FVTX header. They are also referenced by the attribute index group, presumably to allow both index and name based lookup of attributes.

Offset Size Description
0x00 4 Attribute name offset.
0x04 1 Buffer index of the buffer containing this attribute.
0x05 3 Buffer offset of the attribute in each element in the buffer.
0x08 4 Format of the attribute's data in the buffer.
0xc End of attribute

The following values have been seen for the Format field. This list is not exhaustive.

Format Data Size Description
0x00000004 2 Two 8 bit values representing numbers between 0 and 1.
0x00000007 4 Two 16 bit values representing numbers between 0 and 1.
0x0000020a 4 Four signed 8 bit values.
0x0000020b 4 Three signed 10 bit values. Divide by 511 to get decimal value. Top 2 bits are always 0b01.
0x0000080d 8 Two 32 bit floating point values.
0x0000080f 8 Four 16 bit floating point values.
0x00000811 12 Three 32 bit floating point values.

Based on the some of the shader code in /vol/content/mapobj/PackunMusic/PackunMusic.bfres the following naming convention seems to be used for attributes.

Attribute Name Friendly Name Description
_p0 position0 The position of the vertex.
_n0 normal0 The normal of the vertex as used in lighting calculations.
_t0 tangent0 The tangent of the vertex as used in advanced lighting calculations.
_b0 binormal0 The binormal of the vertex as used in advanced lighting calculations.
_w0 blendweight0 unknown
_i0 blendindex0 unknown
_u0 uv0 Texture coordinates used for texture mapping.
_u1 uv1
_u2 uv2
_u3 uv3
_c0 color0 Vertex colours used for simple shadow mapping.
_c1 color1

Buffers

The buffers of each FVTX section are stored as a repeating 0x18 byte header structure which references the actual data stored later in the BFRES file. The headers are stored in an array with location and length specified by the FVTX header.

Offset Size Description
0x00 4 Unknown always 0.
0x04 4 Size of the buffer in bytes.
0x08 4 Unknown always 0.
0x0c 2 Stride: the size of each element in the buffer.
0x0e 2 Unknown always 1.
0x10 4 Unknown always 0.
0x14 4 Data offset.
0x18 End of buffer

FMAT

The model may have one or more FMAT sections which describe surface properties of a polygon such as textures. Every polygon is rendered using a vertex shader and a pixel shader. These are pieces of code which run on the graphics card. Like any code, these have parameters which is principally what the FMAT section controls. There are many different ways for the FMAT section to set variables in the shader code, but it remains unknown what the reason for this is. All shader parameters are either uniform or attributes. Attribute parameters vary per vertex or pixel, whereas uniform parameters are global. The FMAT must specify values for all uniform parameters, and specifies a mapping between vertex attributes in the corresponding FVTX sections and attribute parameters for both the pixel and vertex shader. In Mario Kart 8 most models reference the same pixel shader and the same vertex shader, both called Turbo_UBER. Turbo_UBER is totally generic and has hundreds of parameters to configure the rendering. The source code for Turbo_UBER seems to be available in /vol/content/mapobj/PackunMusic/PackunMusic.bfres.

Header (FMAT)

Every FMAT begins with an 0x48 byte header structure. This references the other structures documented here to describe the material.

Offset Size Description
0x00 4 "FMAT" section identifier, ASCII string.
0x04 4 Material name offset.
0x08 4 Unknown always 1.
0x0c 2 Section Index of this material.
0x0e 2 Render Info Parameter Count. Number of elements in the Render Info Parameter index group.
0x10 1 Texture Selector Count. Number of elements in the Texture Selector array.
0x11 1 Texture Attribute Selector Count. Number of elements in the Texture Attribute Selector array. Always equal to the number of elements in the Texture Selector array.
0x12 2 Material Parameter Count. Number of elements in the Material Parameter array.
0x14 4 Material Parameter Data Size in bytes. The size of the Material Parameter Data section.
0x18 4 Unknown always 0, 1 or 2.
0x1c 4 Render Info Parameter index group offset. Offset to the index group defining render info parameters.
0x20 4 Unknown Material Structure offset. Offset to the unknown material structure.
0x24 4 Shader Control offset. Offset to the shader control structure.
0x28 4 Texture Selector offset. Offset to the first element in the Texture Selector array.
0x2c 4 Texture Attribute Selector offset. Offset to the first element in the Texture Attribute Selector array.
0x30 4 Texture Attribute Selector index group offset. Offset to an index group which references the Texture Attribute Selector array, to allow named value lookups.
0x34 4 Material Parameter array offset. Offset to the first element in the Material Parameter array.
0x38 4 Material Parameter index group offset. Offset to an index group which references the Material Parameter array, to allow named value lookups.
0x3c 4 Material Parameter Data offset. Offset to the beggining of the values for Material Parameters. The Material Parameter array references this data.
0x40 4 Shadow Parameter index group offset. May be 0 if not needed.
0x44 4 Unknown offset. Always points to 12 bytes, all 0. Offset may be 0 if not needed.
0x48 End of FMAT Header

Render Info Parameter

A Render Info Parameter is a repeating structure of at least 0x8 bytes, each of which describes the value to assign to a render info variable in the shader code. Render info variables are always uniform variables. The Render Info Parameter structures are referenced by the Render Info Parameter index group in the corresponding FMAT Header.

Offset Size Description
0x00 2 Unknown always 0 or 1.
0x02 1 Type of the variable.
0x03 1 Unknown always 0.
0x04 4 Variable Name offset.
0x08 Varies Value of the variable.
Varies End of Render Info Parameter

The Type field has values as follows.

Type Value Size Description
0x00 8 Unknown data always 0?
0x01 8 Unknown vector of 2 floats?
0x02 4 Offset to a string.

Texture Selector

A Texture Selector is a repeating 0x8 byte structure each of which references a single FTEX texture. The length and position of the Texture Selector array is specified by the corresponding FMAT Header.

Offset Size Description
0x00 4 Texture Name offset. The same as the FTEX name.
0x04 4 FTEX offset. Points to the header of the FTEX.
0x08 End of Texture Selector

Texture Attribute Selector

An Texture Attribute Selector is a repeating 0x18 byte structure each of which describes one of the inputs to the pixel shader from the selected textures. The length and position of the Texture Attribute Selector array is specified by the corresponding FMAT Header.

Offset Size Description
0x00 1 Unknown always 2.
0x01 1 Unknown always 0x00, 0x02, 0x04 or 0x12.
0x02 1 Unknown always 0x00, 0x10, 0x12 or 0x5a.
0x03 1 Unknown usually either near 0 or near 0x80. Could be flags?
0x04 1 Unknown signed integer normally close to 0.
0x05 1 Unknown typically small value.
0x06 2 Unknown probably flags.
0x08 4 Unknown always 0x80000000.
0x0c 4 Unknown always 0.
0x10 4 Attribute Name offset.
0x14 1 Index of this element.
0x15 3 Unknown always 0.
0x18 End of Texture Attribtue Selector

Based on the some of the shader code in /vol/content/mapobj/PackunMusic/PackunMusic.bfres the following naming convention seems to be used for texture attributes.

Attribute Name Friendly Name Description
_a0 albedo0 Ordinary colour textures for surface albedo.
_a1 albedo1
_a2 albedo2
_a3 albedo3
_s0 specular0 Specular highlight texture.
_n0 normal0 Normal map texture for altering surface normals.
_n1 normal1
_e0 emission0 Emissive lighting texture.
_b0 bake0 Shadow textures.
_b1 bake1

Material Parameter

A Material Parameter is a repeating 0x14 byte structure each of which describes the value to assign to a material variable in the shader code. Material variables are always uniform variables. The length and position of the Material Parameter array is controlled by the corresponding FMAT Header.

In some BFRES Files which do not have 0x03040004 after the FRES identifier, the Material Parameter structure is shorter or longer than 0x14 bytes. This seems to be consistent across entire model files. This is presumably a different verson of the FMDL format. It is rare in Mario Kart 8 (affecting only 6 models).

Offset Size Description
0x00 1 Type of the variable.
0x01 1 Size of the value in bytes.
0x02 2 Offset relative to the start of the Material Parameter Data section to the value.
0x04 4 Unknown always 0xffffffff.
0x08 4 Unknown always 0.
0x0c 2 Parameter Index into the Material Parameter array.
0x0e 2 Same value as Parameter Index again.
0x10 4 Variable Name offset.
0x14 End of Material Parameter

The Type field has values as follows.

Type Size Description
0x04 4 Signed Integer.
0x0c 4 Floating point value.
0x0d 8 Vector of 2 floats.
0x0e 12 Vector of 3 floats.
0x0f 16 Vector of 4 floats.
0x1e 24 2×3 Texutre Matrix. Encoded down columns then along rows, so the identity matrix would be encoded 1, 0, 0, 1, 0, 0.

Unknown Material Structure

A Unknown Material structure is a 0x30 byte structure with unknown purpose. A Unknown Material structure is referenced by the corresponding FMAT Header.

Offset Size Description
0x00 4 Unknown always less than 0x14.
0x04 2 Unknown always 0x0028.
0x06 2 Unknown always 0x0240, 0x0242 or 0x0243.
0x08 4 Unknown always 0x49749732 or 0x49749736.
0x0c 4 Unknown always less than 0xe.
0x10 4 Unknown floating point always less than 1.0.
0x14 2 Unknown always 0x00cc.
0x16 2 Unknown always 0x0000 or 0x0100.
0x18 4 Unknown always 0.
0x1c 2 Unknown always 0x2001.
0x1e 1 Unknown always 1 or 5.
0x1f 1 Unknown always 1 or 4.
0x20 16 Unknown always 0.
0x30 End of Unknown Material Structure

Shader Control

A Shader Control structure is a 0x1c byte structure which describe the shader to be used by a material. A Shader Control structure is referenced by the corresponding FMAT Header.

Offset Size Description
0x00 4 Shader Name 1 offset?
0x04 4 Shader Name 2 offset?
0x08 4 Unknown always 0 or 1.
0x0c 1 Vertex Shader Input Count. Number of elements in the Vertex Shader Input index group.
0x0d 1 Pixel Shader Input Count. Number of elements in the Pixel Shader Input index group.
0x0e 2 Parameter Count. Number of elements in the Parameter index group.
0x10 4 Vertex Shader Input index group offset. Offset to the index group which forms a mapping between strings, mapping an FVTX attribute to a vertex shader variable. The names are always the same in Mario Kart 8, so this mapping is just ["_p0": "_p0", "_n0": "_n0", ...]?
0x14 4 Pixel Shader Input index group offset. Offset to the index group which forms a mapping between strings, mapping an FVTX attribute to a pixel shader variable. The names are always the same in Mario Kart 8, so this mapping is just ["_p0": "_p0", "_n0": "_n0", ...]?
0x18 4 Parameter index group offset. Offset to the index group which forms a mapping between strings, mapping a uniform shader variable to a value. The values are always strings, even for numeric parameters.
0x1c End of Material Parameter

Shadow Parameter

A Shadow Parameter is a repeating 0xc byte structure, each of which describes the value to assign to a shadow variable in the shader code. Shadow variables are always uniform variables. The Shadow Parameter structures are referenced by the Shadow Parameter index group in the corresponding FMAT Header.

Offset Size Description
0x00 4 Variable Name offset.
0x04 2 Unknown always 1.
0x06 1 Type or Index?
0x07 1 Unknown always 0.
0x08 4 Value of the variable.
0xc End of Shadow Parameter

FSKL

Each model has one FSKL section which describes one or more bones. The bones form a skeleton and give a transformation to apply to any attached polygon. Every FSHP polygon is attached to at least one bone. The FSKL format is somewhat different in BFRES files with values other than 0x03040004 after the FRES identifier, which may indicate an alternative version of the format. These are rare in Mario Kart 8 and not documented here.

Header (FSKL)

The FSKL section always starts with an 0x24 byte header. The location of this header is given by the offset in the FMDL header.

Offset Size Description
0x00 4 "FSKL" section identifier, ASCII string.
0x04 2 Unknown always 0.
0x06 2 Unknown always 0x1100 or 0x1200.
0x08 2 Bone array count. Number of elements in the Bone array.
0x0a 2 Inverse Index array count. Number of elements in the Inverse Matrix array.
0x0c 2 Extra Index count. Count of the number of extra indices at the end of the Inverse Index array. These serve unknown purpose.
0x0e 2 Unknown always 0.
0x10 4 Bone index group offset. Named pointers to the members of the Bone array to allow named lookups.
0x14 4 Bone array offset. Offset to the first element in the Bone array.
0x18 4 Inverse Index array offset. Offset to the first element in the Inverse Index array. Always given even if the array is empty.
0x1c 4 Inverse Matrix array offset. Offset to the first element in the Inverse Matrix array. Always given even if the array is empty.
0x20 4 Padding, always 0.
0x24 End of FSKL header

Bone

A Bone is a repeating 0x30 byte structure which descibes a transformation to apply to a polygon. Each bone has up to four parents, which form a tree called a skeleton. To compute the final transformation of a point, apply the transformation required by the bone it is attached to, then that bone's parent recursively up until no parents remain. The Bone tree is stored as an array with offset and length specified by the FSKL header.

Offset Size Description
0x00 4 Name offset for this bone.
0x04 2 Bone index of this bone into the bone array.
0x06 8 Parent indices of up to four parents for this bone. 0xffff for no parent.
0x0e 2 Unknown always 0.
0x10 2 Flags controlling this bone. Unknown purpose.
0x12 2 Unknown always 0x1001.
0x14 12 Scale Vector 3 floats. The amount to scale the vertices by.
0x20 12 Rotation Vector 3 floats. The amount of rotation to apply to x, y and z axis in Radians.
0x2c 4 Unknown always 1.0f.
0x30 12 Translation Vector 3 floats. The amount to translate the vertices by.
0x3c 4 Padding, always 0.
0x40 End of Bone

Inverse Matrix

The FSKL may specify an Inverse Matrix for any Bone. It does this by creating an entry in the Invese Index array which is the index of the bone, and in the corresponding place in the Inverse Matrix array it places a 4×3 transformation matrix which reverses the full transformation of the bone and all its parents. Inverse Matricies are optional, it is Unknown if they are ever referenced. The position of and number of elements in the Inverse Matrix array and the Inverse Index array are given in the FSKL Header. At the end of the Inverse Index array are a number of extra indices, which have Unkonwn purpose. The number of such extra indices is also present in the FSKL Header.

FSHP

The model may have one or more FSHP sections which describe the one polygon (e.g. the road of a track). The FSHP section consists of an 0x40 byte header, which references an FVTX section and indices of the polygons to draw. A basic FSHP amounts to a list of indices into the corresponding FVTX indicating which points to draw triangles between. The FSHP also references an FMAT to describe the material of the triangles, and an FSKL to indicate the bone structure of the model used in animation.

The triangles in an FSHP are organised by two systems; LoD Models and Visibility Groups. No model in Mario Kart 8 uses both of these features non-trivially simultaneously. LoD stands for Level of Detail, which is a standard performance technique used across many 3d rendering systems. Each LoD model is a simpler version of the one before it, with extraneous triangles removed, and finer detail simplified. As the camera in the game moves away from a polygon, the simpler version of the model is rendered instead, which should look the same as the fine detailed version at a distance. A trivial polygon will only have one LoD model, which will be rendered no matter what distance the camera is. Separately, the Visibility Group system allows parts of the model to not be rendered if they are off-screen. This allows an polygon which is partially off-screen to be rendered faster, by skipping the off-screen components. A trivial polygon will only have one Visibility Group, which will always be rendered.

Header (FSHP)

Every FSHP begins with an 0x40 byte header. This references other data structures which describe the polygon.

Offset Size Description
0x00 4 "FSHP" section identifier, ASCII string.
0x04 4 Polygon name offset.
0x08 4 Unknown always 2.
0x0c 2 Section Index or FVTX Index. In every Mario Kart 8 model these numbers are the same.
0x0e 2 FMAT Index. Index of the material for this polygon.
0x10 2 FSKL Index of the bone for this polygon.
0x12 2 Section Index or FVTX Index. In every Mario Kart 8 model these numbers are the same.
0x14 2 FSKL Index Array Count. Often zero, Unknown purpose but seems to be related to FSKL.
0x16 1 Unknown: If FSKL Index Array is present this tends to be non-zero. Zero otherwise.
0x17 1 LoD Model count. Number of elements in the array.
0x18 4 Visibility Group Tree Node count.
0x1c 4 Unknown floating point.
0x20 4 FVTX offset to the vertex buffer for this polygon.
0x24 4 LoD Model offset. Offset to the first element in the array.
0x28 4 FSKL Index Array Offset. Each element of this array is a 16 bit index.
0x2c 4 Unknown always 0.
0x30 4 Visibility Group Tree Nodes offset.
0x34 4 Visibility Group Tree Ranges offset.
0x38 4 Visibility Group Tree Indices offset.
0x3c 4 Unknown always 0.
0x40 End of FSHP header

LoD Model

An LoD Model is a repeating 0x1c byte structure which are stored in a sequential array with location and size specified by the FSHP Header. Their purpose is described at the beginning of this section.

Offset Size Description
0x00 4 Unknown Always 4.
0x04 4 Unknown Always 4.
0x08 4 Count of points drawn in all Visibility Groups, thus the maximum number of points drawn at this LoD.
0x0c 2 Visibility Group count. The number of elements in the array.
0x0e 2 Unknown Always 0.
0x10 4 Visibility Group offset. Offset to the first element in the array.
0x14 4 Index Buffer offset.
0x18 4 Skip Vertices: the number of elements to skip in the corresponding FVTX buffer.
0x1c End of LoD Model

Visibility Group

A Visibility Group is a repeating 0x8 byte structure describing an offset and a count in the corresponding Index Buffer. Visibility Groups are stored in a sequential array with location and count indicated by the corresponding LoD Model. This allows multiple visibility groups to use the same Index Buffer. In many cases, a single group is used which simply draws the entire Index Buffer.

Offset Size Description
0x00 4 Offset into index buffer in bytes.
0x04 4 Count of the points to draw.
0x08 End of Visibility Group

Index Buffer

An Index Buffer is an 0x18 byte structure which describes a list of 16 bit values which are used to index the FVTX section when drawing the polygon. Index Buffers are referenced by LoD Models. The format is very similar to the FVTX Buffer format, which may indicate they are instances of the same structure.

Offset Size Description
0x00 4 Unknown Always 0.
0x04 4 Size of index data in bytes.
0x08 4 Unknown Always 0.
0x0c 2 Unknown Always 0.
0x0e 2 Unknown Always 1.
0x10 4 Unknown Always 0.
0x14 4 Index data offset.
0x18 End of Index Buffer

Visibility Group Tree

The Visibility Group Tree is some sort of tree structure that occurs in all FSHP sections. In all Mario Kart 8 files, when the FSHP has multiple LoD Models, the Visibility Group Tree is a trivial one node tree. The Visibility Group Tree is used to control which Visibility Groups need to be drawn as described at the beginning of this section. The workings of the structure are however unknown.

Nodes

The Visibility Group Tree Node is a repeating 0xc byte structure. The nodes form a binary tree. The FSHP header contains a pointer to node array, as well as specifying its length. The root node is the first node in this array. Each node specifies a range of Visibility Groups, with the root node always covering all nodes, and the children of each node always selecting disjoint subsets of that node's range.

Offset Size Description
0x00 2 Left Child index. The current node's index if it has no left child.
0x02 2 Right Child index. The current node's index if it has no right child.
0x04 2 Unknown always the same as Left Child index.
0x06 2 Next Sibling index. For left children, always the current node's parent's right child (the current node's index if it has no right child).
0x08 2 Visibility Group Index selects a range of Visibility Groups along with the count.
0x0a 2 Visibility Group Count selects a range of Visibility Groups along with the index.
0x0c End of Node

Ranges

The Visibility Group Tree Range is a repeating 0x18 byte structure. The meaning is unknown. There are exactly as many Ranges as Nodes. The range appears to contain two 3D positions, which are not necessarily distinct.

Offset Size Description
0x00 12 Unknown 3D position (x,y,z float).
0x0c 12 Unknown 3D position (x,y,z float).
0x18 End of Range

Indices

The Visibility Group Tree Index array is an array of 16 bit values which appear to be the index of the leaf node of the Visibility Group Tree which contains the corresponding Visibility Group. Therefore this array has length equal to the number of Visibility Groups in the FSHP section.

Parameter

A Parameter is an 0xc byte structure which describes the value of some model parameter. It is only used in a handful of Mario Kart 8 models to set the value of "ParticleLimit". A Parameter structure is referenced by the Parameter index group in the FMDL Header.

Offset Size Description
0x00 4 Variable Name offset.
0x04 2 Unknown always 1.
0x06 2 Unknown always 0.
0x08 4 Value of the variable (floating point).
0xc End of Parameter