Materials (Metroid Prime 3)

The format for materials saw a dramatic overhaul in Metroid Prime 3. The format is seen in both the CMDL and MREA formats and is identical in both. This particular material format appears in Metroid Prime 3: Corruption and Donkey Kong Country Returns.

This file format needs more research There are a ton of unknowns in this format

Material Set Format

Materials come as part of a set; although most files will only have one set, some CMDLs will have more, as indicated by a count value in the header. The set format is merely a 32-bit count value followed by that number of materials. In Metroid Prime 3, each material set will be in its own CMDL/MREA section, but in DKCR each set will be in the same section.

Material Format

The material format starts with a 28-byte header, then after that is broken up into a bunch of subsections.

Header

Offset	Type	Size	Description	Notes
0x0	u32	4	Material size	Does not include size value
0x4	u32	4	Material flags	Only bottom 17 bits are valid
0x8	u32	4	Group index	Denotes groups of materials that share the same settings, but different textures.
0xC	u32	4	Unknown	Value is possibly unused; the material loading code seems to skip it
0x10	u32	4	Vertex attribute flags	Functionality is identical to Metroid Prime 2
0x14	u32	4	Unknown	Value is possibly unused; the material loading code seems to skip it
0x18	u32	4	Unknown
0x1C	u32	4	Unknown
0x20	End of header

Flags

Known flag values:

Bit	Hex	Description
0	0x1	Unknown
1	0x2	Unknown
2	0x4	Unknown
3	0x8	Enable alpha blending
4	0x10	Enable punchthrough alpha. The alpha channel of the texture on the CLR pass will be sampled. Bloom passes will be disabled. The alpha compare function is alpha <= 0.75.
5	0x20	Enable additive blending (probably - needs verification)
6	0x40	Unknown
7	0x80	Unknown
8	0x100	Shadow occluder mesh; meshes using this material are not rendered, but can be used to cast dynamic shadows on actors
9	0x200	Unknown
10	0x400	Unknown
11	0x800	Unknown
12	0x1000	Unknown
13	0x2000	Unknown
14	0x4000	Unknown
15	0x8000	Unknown
16	0x10000	Unknown
17+	-	Unused

Subsections

The rest of the material data is made up of a number of subsections. These subsections generally set different texture slots, as well as other parameters like Konst colors and material opacity. There's no count for the number of subsections; it needs to be read in using a while loop. The "END " section denotes the end of the material.

The order of the subsections doesn't matter. One material can only have one of each type of subsection; if there's any additional ones, they will overwrite the previous ones.

There are three subsection types (aside from END): PASS, CLR, and INT. Each of these types has a number of subtypes.

PASS

The PASS sections set up a single rendering pass, consisting of one TEV stage and potential other data to go with it (like a UV animation). One pass is 32 bytes (without the animation) and is structured as follows:

Offset	Type	Size	Description	Notes
0x0	u32	4	PASS subsection size
0x4	char[4]	4	Section subtype fourCC	See below for possible subtypes
0x8	u32	4	Pass Flags	Only bottom 5 bits are valid
0xC	TXTR	8	Texture ID
0x14	u32	4	UV Source	Only bottom 4 bits are valid
0x18	u32	4	UV Animation Size

If there's a UV anim, it is structured like this:

Offset	Type	Size	Description
0x0	u16	2	Unknown
0x2	u16	2	Unknown
0x4	u32	4	Animation Type

List of possible PASS subtypes: (note: the pass types are also processed in this order)

Type	Description	MP3	DKCR
DIFF	Lightmap	✔	✔
RIML	Rim lighting map	✖	✔
BLOL	Bloom lightmap	✔	✖
BLOD	Bloom diffuse map	✔	✖
CLR	Diffuse map	✔	✔
TRAN	Opacity map	✔	✔
INCA	Incandescence map	✔	✔
RFLV	Reflectivity map	✔	✔
RFLD	Reflection map	✔	✔
LRLD	Unknown	✔	✔
LURD	Unknown	✔	✔
BLOI	Bloom incandescence map	✔	✖
XRAY	Reflection map for X-Ray models; similar to RFLD	✔	✖
TOON	Unknown; unused	✖	✔

Flags

Known flag settings:

Bit	Hex	Description
0	0x1	Unknown
1	0x2	Unknown
2	0x4	On INCA, factors in the texture map as a bloom map as (0.25 * texture alpha)
3	0x8	Unknown
4	0x10	On TRAN, indicates that the texture map is inverted (ie. white is transparent, black is opaque).
5+	-	Unused

CLR

Offset	Type	Size	Description	Notes
0x0	char[4]	4	Section subtype fourCC	See below for possible subtypes
0x4	u32	4	Color value	32-bit RGBA value

List of possible CLR subtypes:

Type	Description	MP3	DKCR
CLR	Unknown	✔	✔
DIFB	Lightmap multiplier color	✔	✔

INT

Offset	Type	Size	Description	Notes
0x0	char[4]	4	Section subtype fourCC	See below for possible subtypes
0x4	u32	4	Value	Actually an 8-bit value; the top 24 bits are ignored

List of possible INT subtypes:

Type	Description	MP3	DKCR
OPAC	Sets the opacity of the entire material	✔	✔
BLOD	Unknown; bloom-related?	✔	✖
BLOI	Unknown; bloom-related?	✔	✖
BNIF	Unknown	✔	✖
XRBR	Unknown; X-Ray related?	✔	✖