MLVL (File Format)

Revision as of 07:39, 14 August 2016 by >Aruki (→‎Script Layer)

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

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

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