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 |
| 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 |