MLVL (File Format)

The MLVL format defines worlds in the Metroid Prime trilogy and Donkey Kong Country Returns. While the MREA format defines individual areas, the world is what defines what links together all the areas to create a single cohesive world.

Format

The format largely defines properties related to each area in general and how they link together, as well as things that apply to the world on a global scale across all areas, such as the skybox.

Remember that all resource IDs are 32 bits in Prime 1/2, and 64 bits in Prime 3/DKCR.

Header

Type	Size	Description	MP1	MP2	MP3	DKCR
u32	4	Magic; always 0xDEAFBABE	✔	✔	✔	✔
u32	4	Version; see below	✔	✔	✔	✔
STRG	4/8	World name	✔	✔	✔	✔
STRG	4	Dark World Name	✖	✔	✖	✖
u32	4	Unknown	✖	✔	✔	✖
bool	1	Sets whether the next five values exist	✖	✖	✖	✔
string	1	Level number (such as 1-2, 2-2, etc)	✖	✖	✖	✔
float	4	Unknown	✖	✖	✖	✔
float	4	Unknown	✖	✖	✖	✔
float	4	Unknown	✖	✖	✖	✔
float	4	Unknown	✖	✖	✖	✔
SAVW	4/8	World save settings	✔	✔	✔	✔
CMDL	4/8	World skybox model	✔	✔	✔	✔

Version

These are the known version numbers:

ID	Game
0xD	Metroid Prime Demo
0x11	Metroid Prime
0x14	Metroid Prime 2 Demo
0x17	Metroid Prime 2
0x19	Metroid Prime 3
0x1B	Donkey Kong Country Returns

Memory Relays

This section is only present in Prime 1. It contains a list of all Memory Relay objects used in the world and what objects they're connected to. If a Memory Relay is connected to multiple objects, it might show up multiple times.

The section starts with a 32-bit count value, then each relay is structured as:

Offset	Type	Size	Description
0x0	u32	4	Memory Relay instance ID
0x4	u32	4	Target instance ID
0x8	u32	2	Message
0x9	u8	1	Unknown (always 0)

Areas

This section defines every area in the world and how they connect to other areas.

Type	Size	Description	MP1	MP2	MP3	DKCR
u32	4	Area count	✔	✔	✔	✔
u32	4	Unknown	✔	✖	✖	✖

Area Header

Type	Size	Description	MP1	MP2	MP3	DKCR
STRG	4/8	Area name	✔	✔	✔	✔
float[12]	0x30	Transform matrix	✔	✔	✔	✔
float[6]	0x18	Bounding box	✔	✔	✔	✔
MREA	4/8	Area MREA	✔	✔	✔	✔
u32	4/8	Area ID; used by layer-switching objects	✔	✔	✔	✔
u32	4	Attached area ID count (AC)	✔	✔	✔	✖
u32[]	4 × AC	Attached area indices (this is an index into the MLVL's area list)	✔	✔	✔	✖
u32	4	Unknown; always 0	✔	✔	✖	✖

Dependency List

This section is only present in Prime 1 and 2. It starts with what's essentially an embedded DGRP file: a 32-bit count value followed by a list of resources used by the area.

Following that is a small array. The purpose of this array is to distinguish which resources are used by which layers, to avoid wasting time loading resources used by objects that aren't active. It's an array of offsets into the dependency table, each one marking the start of that layer's dependency list.

Offset	Type	Size	Description
0x0	u32	4	Layer count (LC)
0x4	u32[]	4 × LC	Layer dependency offsets

Docks

This section is only present in the Prime trilogy.

Type	Count	Description
u32	1	Dock count (DC)
Dock	DC	Docks
u32	1	Unknown (always 4; possibly dock coordinate count)
vec3	4	Dock coordinates

Dock

Type	Count	Description
u32	1	Connecting dock count (CC)
Connecting dock	CC	Connecting docks

Connecting Dock

Type	Count	Description
u32	1	Area index
u32	1	Dock index

.rel List

This section is only present in Echoes. It contains a list of .rel files used by the area. Like the dependency list, this is split up by layer, and is followed by an offset that indicates which .rel files are used by which layers.

Type	Count	Description
u32	1	.rel count (RC)
string	RC	.rel filenames (all zero-terminated)
u32	1	Layer count (LC)
u32	LC	Layer .rel offsets

Area Footer

Type	Size	Description	MP1	MP2	MP3	DKCR
u32	4	Unknown; always 0	✖	✖	✖	✔
string	1	Internal area name (zero-terminated)	✖	✔	✔	✔

World Map

This section is only present in the Prime trilogy. It sets the MAPW file used for this world.

Type	Size	Description
MAPW	4/8	World map
u32	1	Unknown; always 0
u8	1	Unknown; always 0

Audio Groups

This section is only present in Prime 1. It contains a list of audio groups (AGSC files) used in this world. It begins with a 32-bit count value, then each audio group is defined as:

Type	Size	Description
u32	4	Unknown
AGSC	4	Audio Group file

There's two values following this, at the end of the AGSC table.

Type	Size	Description
u32	4	Unknown; always 0
u8	1	Unknown; always 0

Layer Info

The final section of the file contains some metadata related to each layer.

Layer Flags

This part attaches a set of 64-bit flags to every area, where each bit corresponds to a layer; if the bit is set, then that indicates that the corresponding layer will be enabled by default (on a new save file). Since the flags are 64 bits, that means the maximum number of layers that can be present in one area is 64.

After a 32-bit area count, the following structure is repeated for each area:

Type	Size	Description
u32	4	Area layer count
u64	8	Area layer flags

Layer Names

This is a very simple list of layer name strings. For info on how each layer is actually attached to its corresponding area, check the Layer Name Offsets section.

Type	Count	Description
u32	1	Layer count (LC)
string	LC	Layer names (zero-terminated)

Unknown Array

This array is only present in Prime 3 and DKCR.

Type	Size	Description
u32	4	Unknown count (UC)
unknown struct	0x10 × UC	Unknown struct array

Layer Name Offsets

The final layer info section provides one offset into the layer name table per area. This can be used to attach a layer's name to its corresponding data within the area.

Type	Count	Description
u32	1	Area count (AC)
u32	AC	Area layer names offsets