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 MLVL is what links together all the areas to create a single cohesive world.

This file format needs more research There's still a fair number of unknowns left in this format.

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	SaveWorld ID	✔	✔	✔	✔
CMDL	4/8	World skybox CMDL ID	✔	✔	✔	✔

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 will show up multiple times.

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

Offset	Type	Size	Description	MP1	MP2	MP3	DKCR
0x0	u32	4	Memory Relay instance ID	✔	✖	✖	✖
0x4	u32	4	Target instance ID	✔	✖	✖	✖
0x8	u16	2	Message	✔	✖	✖	✖
0x10	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/u64	4/8	Area ID; used by layer-switching objects	✔	✔	✔	✔

Attached Areas

This part contains a small table listing what areas within the world are attached (connected) to this one. This is done by using indices into the MLVL's area table; so an index of 0 indicates the first area listed in the MLVL, for example.

Type	Size	Description	MP1	MP2	MP3	DKCR
u32	4	Attached area index count (AC)	✔	✔	✔	✖
u16[]	2 × AC	Attached area indices	✔	✔	✔	✖
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	MP1	MP2	MP3	DKCR
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	MP1	MP2	MP3	DKCR
u32	1	Dock count (DC)	✔	✔	✔	✖
Dock	DC	Docks	✔	✔	✔	✖

Dock

Type	Count	Description	MP1	MP2	MP3	DKCR
u32	1	Connecting dock count (CC)	✔	✔	✔	✖
Connecting dock	CC	Connecting docks	✔	✔	✔	✖
u32	1	Unknown (always 4; possibly dock coordinate count)	✔	✔	✔	✖
vec3	4	Dock coordinates	✔	✔	✔	✖

Connecting Dock

Type	Count	Description	MP1	MP2	MP3	DKCR
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	MP1	MP2	MP3	DKCR
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	MP1	MP2	MP3	DKCR
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	MP1	MP2	MP3	DKCR
u32	4	Unknown	✔	✖	✖	✖
AGSC	4	Audio Group file	✔	✖	✖	✖

There's one byte following this, at the end of the AGSC table.

Type	Size	Description	MP1	MP2	MP3	DKCR
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	MP1	MP2	MP3	DKCR
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	MP1	MP2	MP3	DKCR
u32	1	Layer count (LC)	✔	✔	✔	✔
string	LC	Layer names (zero-terminated)	✔	✔	✔	✔

Layer IDs

This array is only present in Prime 3 and DKCR, and is used by layer-switching objects.

Type	Size	Description	MP1	MP2	MP3	DKCR
u32	4	Layer ID count (IC)	✖	✖	✔	✔
u128	0x10 × IC	Layer ID	✖	✖	✔	✔

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	MP1	MP2	MP3	DKCR
u32	1	Area count (AC)	✔	✔	✔	✔
u32	AC	Area layer names offsets	✔	✔	✔	✔