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

Vertex Attribute Flags

These flags are generally toggled in pairs, with each pair corresponding to a vertex attribute; if a pair is set, then vertices using this material will have the corresponding attribute. This is vital for reading geometry. Each pair is used to indicate the size of the attribute indices in the geometry data, with 3 meaning a 16-bit index and 2 meaning an 8-bit index. (This isn't actually used, though; the original game data always uses 16-bit indices.)

GX supports up to 8 texture coords per vertex, but the game doesn't seem to allow you to assign more than 7 (though this could do with some double-checking).

These are the possible attributes:

Bit pair	Attribute
0x3	Position
0xC	Normal
0x30	Color 0
0xC0	Color 1
0x300	Tex 0
0xC00	Tex 1
0x3000	Tex 2
0xC000	Tex 3
0x30000	Tex 4
0xC0000	Tex 5
0x300000	Tex 6

The top byte is structured differently; unlike the other flags, the bits in the top byte Are not set in pairs. Each individual bit indicates the presence of a different attribute. The indices in the geometry data are always 8 bits.

Bit	Attribute
0x1	Position Matrix Index
0x2	Tex0 Matrix Index
0x4	Tex1 Matrix Index
0x8	Tex2 Matrix Index
0x10	Tex3 Matrix Index
0x20	Tex4 Matrix Index
0x40	Tex5 Matrix Index
0x80	Tex6 Matrix Index

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

UV Animations

See UV Animations

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?	✔	✖