BMD (File Format)

From Wexos's Wiki
Jump to navigationJump to search

BMD (Binary MoDel) is a model format developed by Nintendo. It is used in games such as Mario Kart Double Dash!! and Super Mario Sunshine. An extension of the format was created, and name of the format was changed to BDL (Binary Display List).

BDL is an updated version of BMD, but its content is almost identical. BDL has one extra section, MDL. All sections are identified by a magic, and the fourth character in each magic represents the section version. The string "This is padding data to alignme" is used as padding bytes. It is impossible to know what characters may have been stored, because the biggest alignment in files are 0x20, meaning a maximum of 0x1F padding characters can be stored.

File Format

Header

A file starts with the following structure:

Offset Type Description
0x00 Char[4] File library magic. Always J3D2 in ASCII.
0x04 Char[4] File type magic. Either bmd3 or bdl4.
0x08 UInt32 Size of file in bytes.
0x0C UInt32 Number of sections stored in the file.

SVR

The SVR section (SubVeRsion) has an unknown usage and is always stored directly after the header. The section is not included in the section count. The structure is as follows:

Offset Type Description
0x00 Char[4] Section magic. Always SVR followed by a version in ASCII.
0x04 UInt32 Unknown, always FF FF FF FF.
0x08 UInt32 Unknown, always FF FF FF FF.
0x0C UInt32 Unknown, always FF FF FF FF.

INF

The INF section (INFormation) stores the scene hierarchy. It has the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always INF followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Unknown.
0x0A UInt16 Unknown.
0x0C UInt32 Number of packets.
0x10 UInt32 Total number of vertices in this file.
0x14 UInt32 Scene node array offset.

Scene Node

Each scene node describes one asset in the file. It stores the assets into an hierarchy of nodes, and the list is continued until a terminator node is found. Each node has the following structure:

Offset Type Description
0x00 UInt16 Node type.
ID Description
0x00 Terminator. End of hierarchy of scene nodes.
0x01 Open child. The next node is a child of this node.
0x02 Close child. The next node is not a child of this node, it is a sibling.
0x10 Joint. References a joint.
0x11 Material. References a material.
0x12 Shape. References a shape.
0x02 UInt16 Index. An index which references an asset which depends on the node type.

VTX

The VTX section (VerTeX) stores the vertex data. It begins with the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always VTX followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt32 Vertex attribute array offset.
0x0C UInt32 Position data offset.
0x10 UInt32 Normal data offset.
0x14 UInt32 Normal binormal tangent data offset.
0x18 UInt32[2] Color data offsets.
0x20 UInt32[8] UV data offsets.

Vertex Attribute

Each vertex attribute describes how the data for an attribute is stored. The NULL attribute means no more attribute follows. Each entry has the following structure:

Offset Type Description
0x00 UInt32 Attribute type.
0x04 UInt32 Component type.
0x08 UInt32 Data format.
0x0C Byte Divisor. If not a color attribute and the format is not float, this specifies the index of the decimal point.
0x0D Byte[3] Reserved.
Attributes
ID Description
0x00 Position matrix index
0x01 UV 0 matrix index
0x02 UV 1 matrix index
0x03 UV 2 matrix index
0x04 UV 3 matrix index
0x05 UV 4 matrix index
0x06 UV 5 matrix index
0x07 UV 6 matrix index
0x08 UV 7 matrix index
0x09 Position
0x0A Normal
0x0B Color 0
0x0C Color 1
0x0D UV 0
0x0E UV 1
0x0F UV 2
0x10 UV 3
0x11 UV 4
0x12 UV 5
0x13 UV 6
0x14 UV 7
0x15 Position matrix array
0x16 Normal matrix array
0x17 UV matrix array
0x18 Light matrix array
0x19 Normal binormal tangent
0xFF NULL
Position components
ID Description
0x00 XY
0x01 XYZ
Normal components
ID Description
0x00 Normal
0x01 Normal and binormal and tangent
0x02 Normal or binormal or tangent
Color components
ID Description
0x00 RGB
0x01 RGBA
UV components
ID Description
0x00 S
0x01 ST
Data formats
ID Description
0x00 Byte
0x01 SByte
0x02 UInt16
0x03 Int16
0x04 Float
Color formats
ID Description
0x00 RGB565
0x01 RGB8
0x02 RGBX8
0x03 RGBA4
0x04 RGBA6
0x05 RGBA8

EVP

The EVP section (EnVeloPe) describes the envelope of the model and stores all weight data. It has the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always EVP followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of weights.
0x0A UInt16 Unknown.
0x0C UInt32 Weight count array offset. Stores the influence count for each weight as a byte.
0x10 UInt32 Bone index offset. Stores the bone indices for each weight as a UInt16.
0x14 UInt32 Weight offset. Stores the bone weights for each weight as a float.
0x18 UInt32 Inverse bind matrix offset. Points to an array of 3x4 float matrices.

DRW

The DRW section (DRaW) is to identify the type of skinning. It has the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always DRW followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of entries.
0x0A UInt16 Unknown.
0x0C UInt32 Matrix type array offset. Points to an array of bytes. Each byte is either joint (0) or envelope (1).
0x10 UInt32 Index data offset. Points to an array of UInt16s. For matrix type joint each item is an index into a joint, for envelope each item is an index into the EVP1 section.

JNT

The JNT section (JoiNT) specify the joints, also known as bones. It starts with the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always DRW followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of joints.
0x0A UInt16 Unknown.
0x0C UInt32 Joint array offset.
0x10 UInt32 Remap table offset.
0x14 UInt32 String table offset.

Joint

Each joint has the following structure:

Offset Type Description
0x00 UInt16 Flag. xxxx xxxx xxxx xxxx xxxx xxxx AAAB BBBB:
  • A: Unknown.
ID Description
0x00 Used for joints who is parent to at least one shape.
0x01 Usually used for joints which are rigged, but sometimes joints with no rigging has this value as well.
0x02 Usually used for joints which are not rigged or parent to any shapes.
  • B: matrix type:
ID Description
0x00 Standard
0x01 Billboard
0x02 Billboard Y
0x02 Byte Do not inherit parent scale flag.
0x03 Byte Unknown.
0x04 Float[3] Scale.
0x10 Int16[3] Rotation.
0x16 UInt16 Unknown.
0x18 Float[3] Translation.
0x24 Float Sphere radius.
0x28 Float[3] Min.
0x34 Float[3] Max.

SHP

The SHP section (SHaPe) contains the shapes and the data needed to render them. It contains raw display lists which is graphics code. The section starts with the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always SHP followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of shapes.
0x0A UInt16 Unknown.
0x0C UInt32 Shape array offset.
0x10 UInt32 Remap table offset.
0x14 UInt32 String table offset.
0x18 UInt32 Attribute descriptor offset.
0x1C UInt32 Matrix index table offset. Points to an array of UInt16s which are indices into the DRW section.
0x20 UInt32 Display list offset. Points to the first display list.
0x24 UInt32 Matrix group offset. Points to the first matrix group.
0x28 UInt32 Display list packet info offset. Points to the first display list packet info.

Shape

Each shape contains data used to render it. A shape may be divided into multiple display lists, this is because the GPU only has support for rendering a display list with up to 10 different matrices. Each entry has the following structure:

Offset Type Description
0x00 Byte Display flag.
ID Description
0 Single matrix
1 Billboard
2 Billboard Y
3 Multi matrix
0x01 Byte Unknown.
0x02 UInt16 Number of packets. Specifies how many matrix groups and display list packet infos to use.
0x04 UInt16 Attribute descriptor offset, relative to the value in the header. Points to the first attribute descriptor.
0x06 UInt16 First matrix group index. Specifies the index of the first matrix group.
0x08 UInt16 First display list packet info index. Specifies the index of the first display list packet info.
0x0A UInt16 Unknown.
0x0C Float Sphere radius.
0x10 Float[3] Min.
0x1C Float[3] Max.

Attribute Descriptor

Each attribute descriptor specifies a vertex attribute which is contained in the linked display lists. It has the following structure:

Offset Type Description
0x00 UInt32 Vertex attribute. See VTX.
0x04 UInt32 Index type.

Matrix Group

The matrix group specifies the different matrices which will be loaded into memory and rendered with in a display list. Each entry has the following structure:

Offset Type Description
0x00 UInt16 Single matrix.
0x02 UInt16 Number of multi matrices.
0x04 UInt32 First multi matrix index. Index of the first matrix into the matrix index table.

If single matrix is used, a multi matrix table is set up consisting of the same single matrix. A matrix value of 0xFFFF means that no new matrix should be loaded into that slot. This means that the first matrix group never should contain 0xFFFF, as it will result in undefined data loaded into that matrix slot.

Display List Packet Info

The display list packet info specifies the size of a display list, and where it is in the file. Each entry has the following structure:

Offset Type Description
0x00 UInt32 Size of display list in bytes.
0x04 UInt32 Display list offset, relative to the value specified in the header.

MAT

The MAT section (MATerial) stores the material and TEV data. All material data is stored in arrays, and are then indexed by the entry structures. It begins with the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always MAT followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of materials.
0x0A UInt16 Unknown.
0x0C UInt32 Material entry array offset.
0x10 UInt32 Remap table offset.
0x14 UInt32 String table offset.
0x18 UInt32 Indirect data array offset.
0x1C UInt32 Cull mode array offset.
0x20 UInt32 Material color array offset. Each entry is a 32-bit color in RGBA format.
0x24 UInt32 Lighting channel count array offset. Each entry is a byte representing the count.
0x28 UInt32 Lighting channel array offset.
0x2C UInt32 Ambient color array offset. Each entry is a 32-bit color in RGBA format.
0x30 UInt32 Light color array offset. Each entry is a 32-bit color in RGBA format. Always 0, never observed in files.
0x34 UInt32 Texture coordinate generator count array offset. Each entry is a byte representing the count.
0x38 UInt32 Texture coordinate generator array offset.
0x3C UInt32 Post texture coordinate generator array offset.
0x40 UInt32 Texture matrix array offset.
0x44 UInt32 Post texture matrix array offset.
0x48 UInt32 Texture index array offset. Each entry is a UInt16 representing an index into the TEX section.
0x4C UInt32 TEV order array offset.
0x50 UInt32 TEV color array offset. Each entry is a 64-bit color in RGBA format, with signed 16-bit components.
0x54 UInt32 TEV constant color array offset. Each entry is a 32-bit color in RGBA format.
0x58 UInt32 TEV stage count array offset. Each entry is a byte representing the count.
0x5C UInt32 TEV stage array offset.
0x60 UInt32 TEV swap mode array offset.
0x64 UInt32 TEV swap table array offset.
0x68 UInt32 Fog array offset.
0x6C UInt32 Alpha compare array offset.
0x70 UInt32 Blend mode array offset.
0x74 UInt32 Z-mode array offset.
0x78 UInt32 Depth test before texturing array offset. Each entry is a byte.
0x7C UInt32 Dither array offset. Each entry is a byte.
0x80 UInt32 NBT Scale array offset.

Material Entry

Offset Type Description
0x00 Byte Unknown. Usually 1 or 4.
0x01 Byte Cull mode index.
0x02 Byte Color channel count index.
0x03 Byte Texture coordinate generator count index.
0x04 Byte TEV Stage count index.
0x05 Byte Depth test before texturing index.
0x06 Byte Z-mode index.
0x07 Byte Dither index.
0x08 UInt16[2] Material color indices.
0x0C UInt16[4] Lighting channel indices.
0x14 UInt16[2] Ambient color indices.
0x18 UInt16[8] Light color indices. Never used in files, always 0xFFFF.
0x28 UInt16[8] Texture coordinate generator indices.
0x38 UInt16[8] Post texture coordinate generator indices.
0x48 UInt16[10] Texture matrix indices.
0x5C UInt16[20] Post texture matrix indices.
0x84 UInt16[8] Texture indices.
0x94 UInt16[4] TEV constant color indices.
0x9C Byte[16] TEV constant color selections.
0xAC Byte[16] TEV constant alpha selections.
0xBC UInt16[16] TEV order indices.
0xDC UInt16[4] TEV color indices.
0xE4 UInt16[16] TEV stage indices.
0x104 UInt16[16] TEV swap mode indices.
0x124 UInt16[4] TEV swap mode table indices.
0x12C UInt16[12] Unknown.
0x144 UInt16 Fog index.
0x146 UInt16 Alpha compare index.
0x148 UInt16 Blend mode index.
0x14A UInt16 NBT scale index.

Indirect Data

The indirect data structure stores all information related to indirect texturing. Instead of being indexed by each material entry, all material instances store their own indirect data. Each entry is 0x138 bytes long and has the following structure:

Offset Type Description
0x00 Byte Has look-up.
0x01 Byte Number of indirect texture stages.
0x02 Byte[2] Padding.
0x04 Indirect TEV order[4] Indirect TEV orders.
0x14 Indirect texture matrix[3] Indirect texture matrices.
0x68 Indirect texture scale[4] Indirect texture scales.
0x78 Indirect TEV stage[16] Indirect TEV stages.

Indirect TEV Order

Offset Type Description
0x00 Byte Indirect texture coordinate.
0x01 Byte Indirect texture map.
0x02 Byte[2] Padding.

Indirect Texture Matrix

An indirect texture matrix is used for transforming the indirect UV offset. It is constructed from scale, rotation and translation. The matrix is always stored with absolutes of all values being less than one, and the largest absolute value being greater or equal to 0.5. The exponent is then used to transform the data into its real value. Each entry has the following structure:

Offset Type Description
0x00 Float[2][3] 2x3 indirect texture matrix. Indirect texture matrix with 2 rows and 3 columns.
0x18 SByte Base 2 exponent. Value which is multiplied to the matrix.
0x19 Byte[3] Padding.

Indirect Texture Scale

Offset Type Description
0x00 UInt32 Flag. AAAA AAAA BBBB BBBB xxxx xxxx xxxx xxxx:
  • A: U scale.
  • B: V scale.

Indirect TEV Stage

Offset Type Description
0x00 Byte TEV stage.
0x01 Byte Format.
0x02 Byte Bias.
0x03 Byte Indirect matrix selection.
0x04 Byte Wrap U.
0x05 Byte Wrap V.
0x06 Byte Add previous stage.
0x07 Byte Unmodified LOD.
0x08 Byte Alpha.
0x09 Byte[3] Padding.

Cull Mode

Offset Type Description
0x00 UInt32 Cull mode.

Lighting Channel

Offset Type Description
0x00 Byte Enable.
0x01 Byte Material color source.
0x02 Byte Light ID.
0x03 Byte Diffuse function.
0x04 Byte Attenuation function.
0x05 Byte Ambient color source.
0x06 Byte[2] Padding.

Texture Coordinate Generator

Offset Type Description
0x00 Byte Type.
0x01 Byte Source.
0x02 Byte Matrix source.
0x03 Byte Padding.

Texture Matrix

Offset Type Description
0x00 Byte Projection.
0x01 Byte Mapping flag. Axxx B:
  • A: texture matrix mode, either Standard (0) or Maya (1).
  • B: mapping mode.
0x02 Byte[2] Padding.
0x04 Float[3] Origin.
0x10 Float[2] Scale.
0x18 Int16 Rotation.
0x1A Byte[2] Padding.
0x1C Float[2] Translation.
0x24 Float[4][4] Projection matrix. 4x4 matrix used by certain mapping modes.

TEV Order

Offset Type Description
0x00 Byte Texture coordinate ID.
0x01 Byte Texture map ID.
0x02 Byte Color channel.
0x03 Byte Padding.

TEV Stage

Offset Type Description
0x00 Byte Unknown.
0x01 Byte Color selection A.
0x02 Byte Color selection B.
0x03 Byte Color selection C.
0x04 Byte Color selection D.
0x05 Byte Color operation.
0x06 Byte Color bias.
0x07 Byte Color scale.
0x08 Byte Clamp color.
0x09 Byte Color destination.
0x0A Byte Alpha selection A.
0x0B Byte Alpha selection B.
0x0C Byte Alpha selection C.
0x0D Byte Alpha selection D.
0x0E Byte Alpha operation.
0x0F Byte Alpha bias.
0x10 Byte Alpha scale.
0x11 Byte Clamp alpha.
0x12 Byte Alpha destination.
0x13 Byte Unknown.

TEV Swap Mode

Offset Type Description
0x00 Byte Raster selection.
0x01 Byte Texture selection.
0x02 Byte[2] Padding.

TEV Swap Table

Offset Type Description
0x00 Byte Red input.
0x01 Byte Green input.
0x02 Byte Blue input.
0x03 Byte Alpha input.

Fog

Offset Type Description
0x00 Byte Type.
0x01 Byte Enabled.
0x02 UInt16 Center.
0x04 Float Start Z.
0x08 Float End Z.
0x0C Float Near Z.
0x10 Float Far Z.
0x14 UInt32 Fog color in RGBA format.
0x18 UInt16[10] Range adjustment table. Values are stored in a fixed-point format with base 100.

Alpha Compare

Offset Type Description
0x00 Byte Compare 0.
0x01 Byte Reference 0.
0x02 Byte Operation.
0x03 Byte Compare 1.
0x04 Byte Reference 1.
0x05 Byte[3] Padding.

Blend Mode

Offset Type Description
0x00 Byte Type.
0x01 Byte Source factor.
0x02 Byte Destination factor.
0x03 Byte Operation.

Z-Mode

Offset Type Description
0x00 Byte Enable depth test.
0x01 Byte Depth test compare.
0x02 Byte Enable depth update.
0x03 Byte Padding.

NBT Scale

Offset Type Description
0x00 Byte Unknown.
0x01 Byte[3] Padding.
0x04 Float[3] Scale.

MDL

The MDL section (Material Display List) contains raw GPU instructions, which was added in BDL. It stores the same data as in the MAT section, but the data is instead stored as GPU instructions. This was presumaly added to speed up material initialization, however the MAT section was not removed. It starts with the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always MDL followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of entries.
0x0A UInt16 Unknown.
0x0C UInt32 Instruction packet array offset.
0x10 UInt32 Instruction packet info array offset.
0x14 UInt32 Matrix source descriptor array offset.
0x18 UInt32 Unknown array offset. Each entry is a byte, matching the flag in each material entry.
0x1C UInt32 Remap table offset.
0x20 UInt32 String table offset.

Instruction Packet

Offset Type Description
0x00 UInt32 Packet data offset, relative to the start of this structure.
0x04 UInt32 Size of packet data in bytes.

The packet data consists of BP and XF commands which are sent directly to the GPU.

Instruction Packet Info

The packet info contains information about each packet, and specifies where what data is into each packet. It has the following structure:

Offset Type Description
0x00 UInt16 Channel color offset.
0x02 UInt16 Channel control offset.
0x04 UInt16 Texture coordinate generator offset.
0x06 UInt16 Texture offset.
0x08 UInt16 TEV offset.
0x0A UInt16 Pixel offset.
0x0C Byte[4] Padding.

Matrix Source Descriptor

Each matrix source descriptor specifies which texture matrix each texture uses. This value matches the one in each texture coordinate generator with unused texture slots are set to identity. It remains unknown why the bitlayout of each value was chosen. Each entry has the following structure:

Offset Type Description
0x00 UInt32 xxAA AAAA BBBB BBCC CCCC DDDD DDxx xxxx:
  • A: texture 3 matrix source.
  • B: texture 2 matrix source.
  • C: texture 1 matrix source.
  • D: texture 0 matrix source.
0x04 UInt32 xxxx xxxx AAAA AABB BBBB CCCC CCDD DDDD:
  • A: texture 7 matrix source (presumably).
  • B: texture 6 matrix source (presumably).
  • C: texture 5 matrix source (presumably).
  • D: texture 4 matrix source (presumably).

TEX

The TEX section (TEXture) stores texture data. The textures are stored as BTI files. It starts with the following structure:

Offset Type Description
0x00 Char[4] Section magic. Always TEX followed by a version in ASCII.
0x04 UInt32 Section size in bytes.
0x08 UInt16 Number of textures.
0x0A UInt16 Unknown.
0x0C UInt32 BTI array offset.
0x10 UInt32 String table offset.

The header of all BTI files are stored, and then all image data follows.

Tools

The following tools can handle BMD or BDL files:

See Also