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.

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.

Version
These are the known version numbers:

Memory Relay
This structure only appears in Prime 1. It describes an outgoing connection from a Memory Relay to another script instance. Any Memory Relays connected to multiple objects will appear in the array multiple times.

Area
This structure defines a single area and describes its position in the world and how it connects to other areas.

Area Dependencies
This is a data chunk appearing in the area definition in Metroid Prime 1 and 2 that lists all assets needed to load the area. It's extremely important that this list be optimized and complete, as all assets listed here will be perpetually kept in memory as long as the area itself is in memory; the list also specifies the order that assets are loaded in, so it must be grouped by load order to roughly match the PAK file for optimized load times. Assets that are missing will still be dynamically loaded after the area itself is loaded, but this will cause the game to freeze up until the load is finished. There are a few exceptions that are excluded from this list in the original game files (and should be excluded in custom MLVLs as well to avoid out-of-memory crashes):


 * Some AGSC files are not included in MP2. The game has specific DGRP files which include the "global" sound effects for that type of world. Any files inside that DGRP are excluded from the list. These are:
 * Single-player worlds: AudioGrp/audio_groups_single_player_DGRP.DGRP
 * Multiplayer worlds: AudioGrp/audio_groups_multi_player_DGRP.DGRP
 * Frontend: AudioGrp/audio_groups_front_end_DGRP.DGRP
 * SCAN files and their dependencies are not included in the list in MP1. These are loaded dynamically after the area itself is finished loading, presumably so that scan dependencies are not kept in memory when the scan isn't actually in use. In MP2, SCANs are actually included in the list but their dependencies aren't. Make sure to update the dependency list inside the SCAN file if you change them - the game may crash when scanning otherwise.
 * Script instances with an AnimationParameters property only include the dependencies from their ANCS which are used by their character index. This includes:
 * Any dependencies in the CharacterSet for that character
 * Any ANIMs (and EVNTs, for MP1) used by that character's animations
 * Any valid AGSC dependencies in any animation events used by that character, including events with a character index of -1.
 * Any Particle Script dependencies in any animation events used by that character, not including events with a character index of -1.
 * Any dependencies of all Meta-Transitions in the ANCS. This includes transitions not used by that character!
 * The skybox model and its dependencies are not included.

The dependency list is split by layer; after the dependencies itself, an array of offsets into the dependency list is provided that allows the game to only load assets for layers that are currently active. The last offset points to all common resources used by the area that aren't layer-specific. With that in mind, every layer needs to have a full list of its required assets even if they're also used by other layers. There's no harm in including an asset multiple times, as if an asset is already in memory then it'll simply be skipped over.

This data chunk still exists in Prime 3 and DKCR, but it's been moved inside the MREA format.

Area Module Dependencies
This is a data chunk appearing in the area definitions that describes all REL modules that must be linked in for this area to run. These are tied to script objects. The list is split per-layer so that only modules being used by the active layer are linked in; modules will appear once in the list for each layer that uses it. After the REL list, there is an array of offsets that points to the starting index in the list for each script layer, similar to the regular area dependencies list. For an unknown reason, the offsets list contains two offsets per layer. The first one refers to the layer's start index while the second one is usually empty, which effectively makes it an end index.

Audio Group
This structure is only present in Prime 1 and describes an AGSC file being used in this world.

Area Layer Flags
This is a small structure that determines which areas are active by default. It contains a layer count and then a 64-bit flag, with each bit corresponding to a particular layer; if the bit is set, then the layer will be active on a new save file. The low-order bits correspond to the lower layer indices. Bits for layers that don't exist are defaulted to on.

Note that due to the size of these flags as well as a few other pieces of data in other formats, the maximum number of layers that can be contained in a single area is 64.