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 | Temple Key World Index | ✖ | ✔ | ✔ | ✖ |
| bool | 1 | Has Time Attack (if false, the next 5 values aren't present) | ✖ | ✖ | ✖ | ✔ |
| string | 1 | Level Number (such as 1-2, 2-2, etc; unknown use) | ✖ | ✖ | ✖ | ✔ |
| float | 4 | Time Attack Bronze Time | ✖ | ✖ | ✖ | ✔ |
| float | 4 | Time Attack Silver Time | ✖ | ✖ | ✖ | ✔ |
| float | 4 | Time Attack Gold Time | ✖ | ✖ | ✖ | ✔ |
| float | 4 | Time Attack Shiny Gold Time | ✖ | ✖ | ✖ | ✔ |
| 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 | Active | ✔ | ✖ | ✖ | ✖ |
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; always 1? | ✔ | ✖ | ✖ | ✖ |
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 | ✔ | ✔ | ✔ | ✖ |
Dependency List
This section is only present in Prime 1 and 2. It starts with what's essentially 2 embedded DGRP files: a 32-bit count value followed by a list of resources used by the area. There are two of these tables, and the first is always empty in release versions.
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 (DC) | ✔ | ✔ | ✔ | ✖ |
| Connecting dock | DC | Connecting docks | ✔ | ✔ | ✔ | ✖ |
| u32 | 1 | Dock coordinate count (CC) | ✔ | ✔ | ✔ | ✖ |
| vec3 | CC | Dock coordinates | ✔ | ✔ | ✔ | ✖ |
Connecting Dock
| Type | Count | Description | MP1 | MP2 | MP3 | DKCR |
|---|---|---|---|---|---|---|
| u32 | 1 | Area index | ✔ | ✔ | ✔ | ✖ |
| u32 | 1 | Dock index | ✔ | ✔ | ✔ | ✖ |
REL Module List
This section is only present in Echoes. It contains a list of .rel files used by the area. Like the dependencies, it is followed by an array of offsets to distinguish which .rels are used by which layers. There are two offsets per layer; the reason for this is currently unknown, but the second offset is essentially an end index.
| Type | Count | Description | MP1 | MP2 | MP3 | DKCR |
|---|---|---|---|---|---|---|
| u32 | 1 | .rel count (RC) | ✖ | ✔ | ✖ | ✖ |
| string | RC | .rel filenames (all zero-terminated) | ✖ | ✔ | ✖ | ✖ |
| u32 | 1 | .rel offset count (OC) | ✖ | ✔ | ✖ | ✖ |
| u32 | OC | .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 | MP1 | MP2 | MP3 | DKCR |
|---|---|---|---|---|---|---|
| MAPW | 4/8 | World map | ✔ | ✔ | ✔ | ✖ |
Script Layer
In the MP1 demo, this script layer is used to store all docks across the entire world. In all other builds/games, this layer is always empty and unused. Unknown whether there's a way to actually use it (all attempts so far result in a crash).
| Type | Size | Description | MP1 | MP2 | MP3 | DKCR |
|---|---|---|---|---|---|---|
| u8 | 1 | Unknown; always 0 | ✔ | ✔ | ✔ | ✖ |
| u32 | 4 | Instance Count; 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 | Group ID | ✔ | ✖ | ✖ | ✖ |
| AGSC | 4 | Audio Group file | ✔ | ✖ | ✖ | ✖ |
There's a string following this, at the end of the AGSC table.
| Type | Size | Description | MP1 | MP2 | MP3 | DKCR |
|---|---|---|---|---|---|---|
| string | 1 | Unknown; always empty | ✔ | ✖ | ✖ | ✖ |
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 | ✔ | ✔ | ✔ | ✔ |