Retro Modding Wiki - User contributions [en]

MLVL (File Format)

2019-08-10T16:13:53Z

Aruki: /* Area Dependencies */

The '''MLVL format''' defines worlds in the Metroid Prime trilogy and Donkey Kong Country Returns. While the [[MREA (File Format)|MREA format]] defines individual areas, the MLVL is what links together all the areas to create a single cohesive world.

{{research|minor|There's a couple unknown values in this format, but they all seem to have constant values.}}

__TOC__

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| u32
| 1
| '''Magic'''
| Always <code>0xDEAFBABE</code>
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Version'''
| [[#Version|See below]]
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''World Name ID'''
| [[STRG (File Format)|STRG]] file for the world name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Dark World Name ID'''
| [[STRG (File Format)|STRG]] file for the Dark World name.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Temple Key World Index'''
| Controls which temple key icons appear on the map screen. Appears in Prime 3 but always 0.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| bool
| 1
| '''Has Time Attack'''
| Indicates whether this world has a Time Attack mode. '''If false, the next five values are not present.'''
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Level Number'''
| String of the world/level number; for example, "1-1". Purpose unknown.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Bronze Time'''
| Target time for a bronze medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Silver Time'''
| Target time for a silver medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Gold Time'''
| Target time for a gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Shiny Gold Time'''
| Target time for a shiny gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| Asset ID ([[SAVW (File Format)|SAVW]])
| 1
| '''World Save Info ID'''
| Asset ID for this world's [[SAVW (File Format)|SAVW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[CMDL (File Format)|CMDL]])
| 1
| '''Default Skybox ID'''
| [[CMDL (File Format)|CMDL]] file for this world's default skybox model. This can be overridden per-area by AreaAttributes objects.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Memory Relay Count'''
| Count of all outgoing connections from Memory Relay instances in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Memory Relay|Memory Relay]]
| ''Memory Relay Count''
| '''Memory Relay Array'''
| Array describing all outgoing Memory Relay connections in this world. Memory Relays connected to multiple objects are listed multiple times.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Count of areas in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 1?
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Area|Area]]
| ''Area Count''
| '''Area Array'''
| Array defining all areas that appear in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MAPW (File Format)|MAPW]])
| 1
| '''World Map ID'''
| ID of this world's [[MAPW (File Format)|MAPW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u8
| 1
| {{unknown|Unknown}}
| This is presumably the same unknown value as at the beginning of the [[Scriptable Layers (Metroid Prime)|SCLY]] format. Always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Script Instance Count'''
| The MLVL format embeds a script layer. This script layer is used in the MP1 demo for storing Dock instances, but it's unused in all retail builds, so this is always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Audio Group Count'''
| Count of all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Audio Group|Audio Group]]
| ''Audio Group Count''
| '''Audio Group Array'''
| Array describing all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| string
| 1
| {{unknown|Unknown}}
| Always empty, so the only value that ever appears here is the terminating 0.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Will be equal to the earlier area count.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Area Layer Flags|Area Layer Flags]]
| ''Area Count''
| '''Area Layer Flags'''
| This array initializes the default active state for all script layers in each area.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer Name Count'''
| Count of layer names in the next array.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| string
| ''Layer Name Count''
| '''Layer Name Array'''
| Array of all layer names in the world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer GUID Count'''
| Count of layer GUIDs in the next array.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| [[GUID]]
| ''Layer GUID Count''
| '''Layer GUID Array'''
| Array of GUIDs for each layer. These GUIDs are responsible for storing the layer's ''Active'' state in the save file and are referenced by ScriptLayerController objects.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Area Count'''
| Identical to the previous two area counts.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| ''Area Count''
| '''Area Layer Name Offset Array'''
| Each value is an offset into the layer name array and points to where the layer names for each area begins.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of file}}
|}

=== Version ===

These are the known version numbers:

{| class="wikitable"
! 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 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.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Memory Relay Instance ID'''
| Instance ID of the sender Memory Relay.
|-
| 0x4
| u32
| '''Target Instance ID'''
| Instance ID of the receiver object.
|-
| 0x8
| u16
| '''Message'''
| Script message sent to the receiver object.
|-
| 0xA
| bool
| '''Active'''
| Whether this Memory Relay object is active by default; almost always 0.
|-
| 0xB
| colspan=3 {{unknown|End of Memory Relay connection}}
|}

=== Area ===

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Area Name ID'''
| [[STRG (File Format)|STRG]] ID for the area name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 12
| '''Area Transform'''
| Area's transform matrix. Most area data is pre-transformed, but there are a few things that need to be transformed by this matrix.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 6
| '''Area Bounding Box'''
| This is the bounding box of the area's collision mesh and is equivalent to the bounding box found in the [[MREA (File Format)|MREA]] collision section.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MREA (File Format)|MREA]])
| 1
| '''Area MREA ID'''
| ID of this area's [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID
| 1
| '''Internal Area ID'''
| Doesn't actually refer to an asset, but has the same length as an asset ID. This ID is used internally by some things to refer to this area, such as Script Layer Controllers.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Attached Area Count'''
| Count of areas attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u16
| ''Attached Area Count''
| '''Attached Area Index Array'''
| Array of area indices attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Dependencies|Area Dependencies]]
| 1
| '''Dependencies'''
| Asset dependencies in this area. See below for details. Starting in Prime 3, this section has been moved inside the [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Dock Count'''
| Count of Dock instances in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Dock|Dock]]
| ''Dock Count''
| '''Dock Array'''
| Array describing all docks in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Module Dependencies|Area Module Dependencies]]
| 1
| '''Module Dependencies'''
| REL module dependencies in this area. See below for details. The equivalent section in Prime 3 and DKCR describing RSO modules has been moved inside the [[MREA (File Format)|MREA]] format.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 0?
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Internal Area Name'''
| Internal name of this area. This name will be used ingame on the map screen if no ''Area Name ID'' is specified, prefixed with "!!".
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of area}}
|}

==== 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 Format)|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):

* [[SCAN (File Format)|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.
* [[ANCS (File Format)|ANCS]] per-character dependencies for PlayerActor script instances are not included; this allows the game to avoid keeping assets in memory for suits that the player doesn't have. The exception is the Empty Suit character (character index 5 in MP1, and index 3 in MP2), which is a low-memory-overhead character that allows for the list to include all common assets that are stored in the file per-character (such as particle effects).
* 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 (File Format)|MREA]] format.

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 0?
|-
| u32
| 1
| '''Dependency Count'''
| Count of dependencies.
|-
| [[#Dependency|Dependency]]
| ''Dependency Count''
| '''Dependency Array'''
| Array of all asset dependencies in this area.
|-
| u32
| 1
| '''Dependency Offset Count'''
| Count of dependency offsets. This will be equal to the area script layer count + 1.
|-
| u32
| ''Dependency Offset Count''
| '''Dependency Offset Array'''
| Array of offsets into the dependency array. There is one offset per script layer, with the offset referring to the index of that layer's first dependency. There is a final extra offset that points to area dependencies that are not layer-specific.
|}

===== Dependency =====

{| class="wikitable"
! Offset
! Type
! Count
! Name
|-
| 0x0
| Asset ID
| 1
| '''Dependency Asset ID'''
|-
| 0x4
| char
| 4
| '''Dependency Asset Type'''
|}

==== Dock ====

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Connecting Dock Count'''
| Count of docks connecting to this one. Typically 1 (but there are docks in Prime 3 that connect to multiple areas).
|-
| [[#Connecting Dock|Connecting Dock]]
| ''Connecting Dock Count''
| '''Connecting Dock Array'''
| Array describing all docks connected to this one.
|-
| u32
| 1
| '''Dock Coordinate Count'''
| Array of dock coordinates in the next array.
|-
| Vector3
| ''Dock Coordinate Count''
| '''Dock Coordinates'''
| Exact purpose/function of this is not known yet.
|}

===== Connecting Dock =====

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Area Index'''
| Index of the area this dock is in.
|-
| 0x4
| u32
| '''Dock Index'''
| Index of this dock within its area.
|}

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''REL Module Count'''
| Count of REL modules in the next array.
|-
| string
| ''REL Module Count''
| '''REL Module Array'''
| REL modules used by this area. Each array entry is the filename of a .REL module.
|-
| u32
| 1
| '''REL Offset Count'''
| Count of REL offsets in the next array. Should be equal to the area script layer count * 2.
|-
| u32
| ''REL Offset Count''
| '''REL Offset Array'''
| Array of offsets into the ''REL Module Array''. There are two offsets per script layer, with the first one being that layer's start index and the second one effectively being that layer's end index.
|}

=== Audio Group ===

This structure is only present in Prime 1 and describes an [[AGSC (File Format)|AGSC]] file being used in this world.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Group ID'''
| Group ID for this audio group. This is the same value that can be found in the Project chunk in the referenced [[AGSC (File Format)|AGSC]] file.
|-
| 0x4
| Asset ID ([[AGSC (File Format)|AGSC]])
| '''AGSC ID'''
| The [[AGSC (File Format)|AGSC]] file for this audio group.
|-
| 0x8
| colspan=3 {{unknown|End of audio group definition}}
|}

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

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Layer Count'''
| Count of layers in this area.
|-
| 0x4
| u64
| '''Layer Flags'''
| See above for a description of how these work.
|-
| 0x8
| colspan=3 {{unknown|End of area layer flags}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

MLVL (File Format)

2019-08-09T20:28:46Z

Aruki: /* Memory Relay */

The '''MLVL format''' defines worlds in the Metroid Prime trilogy and Donkey Kong Country Returns. While the [[MREA (File Format)|MREA format]] defines individual areas, the MLVL is what links together all the areas to create a single cohesive world.

{{research|minor|There's a couple unknown values in this format, but they all seem to have constant values.}}

__TOC__

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| u32
| 1
| '''Magic'''
| Always <code>0xDEAFBABE</code>
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Version'''
| [[#Version|See below]]
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''World Name ID'''
| [[STRG (File Format)|STRG]] file for the world name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Dark World Name ID'''
| [[STRG (File Format)|STRG]] file for the Dark World name.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Temple Key World Index'''
| Controls which temple key icons appear on the map screen. Appears in Prime 3 but always 0.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| bool
| 1
| '''Has Time Attack'''
| Indicates whether this world has a Time Attack mode. '''If false, the next five values are not present.'''
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Level Number'''
| String of the world/level number; for example, "1-1". Purpose unknown.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Bronze Time'''
| Target time for a bronze medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Silver Time'''
| Target time for a silver medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Gold Time'''
| Target time for a gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Shiny Gold Time'''
| Target time for a shiny gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| Asset ID ([[SAVW (File Format)|SAVW]])
| 1
| '''World Save Info ID'''
| Asset ID for this world's [[SAVW (File Format)|SAVW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[CMDL (File Format)|CMDL]])
| 1
| '''Default Skybox ID'''
| [[CMDL (File Format)|CMDL]] file for this world's default skybox model. This can be overridden per-area by AreaAttributes objects.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Memory Relay Count'''
| Count of all outgoing connections from Memory Relay instances in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Memory Relay|Memory Relay]]
| ''Memory Relay Count''
| '''Memory Relay Array'''
| Array describing all outgoing Memory Relay connections in this world. Memory Relays connected to multiple objects are listed multiple times.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Count of areas in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 1?
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Area|Area]]
| ''Area Count''
| '''Area Array'''
| Array defining all areas that appear in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MAPW (File Format)|MAPW]])
| 1
| '''World Map ID'''
| ID of this world's [[MAPW (File Format)|MAPW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u8
| 1
| {{unknown|Unknown}}
| This is presumably the same unknown value as at the beginning of the [[Scriptable Layers (Metroid Prime)|SCLY]] format. Always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Script Instance Count'''
| The MLVL format embeds a script layer. This script layer is used in the MP1 demo for storing Dock instances, but it's unused in all retail builds, so this is always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Audio Group Count'''
| Count of all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Audio Group|Audio Group]]
| ''Audio Group Count''
| '''Audio Group Array'''
| Array describing all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| string
| 1
| {{unknown|Unknown}}
| Always empty, so the only value that ever appears here is the terminating 0.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Will be equal to the earlier area count.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Area Layer Flags|Area Layer Flags]]
| ''Area Count''
| '''Area Layer Flags'''
| This array initializes the default active state for all script layers in each area.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer Name Count'''
| Count of layer names in the next array.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| string
| ''Layer Name Count''
| '''Layer Name Array'''
| Array of all layer names in the world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer GUID Count'''
| Count of layer GUIDs in the next array.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| [[GUID]]
| ''Layer GUID Count''
| '''Layer GUID Array'''
| Array of GUIDs for each layer. These GUIDs are responsible for storing the layer's ''Active'' state in the save file and are referenced by ScriptLayerController objects.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Area Count'''
| Identical to the previous two area counts.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| ''Area Count''
| '''Area Layer Name Offset Array'''
| Each value is an offset into the layer name array and points to where the layer names for each area begins.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of file}}
|}

=== Version ===

These are the known version numbers:

{| class="wikitable"
! 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 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.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Memory Relay Instance ID'''
| Instance ID of the sender Memory Relay.
|-
| 0x4
| u32
| '''Target Instance ID'''
| Instance ID of the receiver object.
|-
| 0x8
| u16
| '''Message'''
| Script message sent to the receiver object.
|-
| 0xA
| bool
| '''Active'''
| Whether this Memory Relay object is active by default; almost always 0.
|-
| 0xB
| colspan=3 {{unknown|End of Memory Relay connection}}
|}

=== Area ===

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Area Name ID'''
| [[STRG (File Format)|STRG]] ID for the area name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 12
| '''Area Transform'''
| Area's transform matrix. Most area data is pre-transformed, but there are a few things that need to be transformed by this matrix.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 6
| '''Area Bounding Box'''
| This is the bounding box of the area's collision mesh and is equivalent to the bounding box found in the [[MREA (File Format)|MREA]] collision section.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MREA (File Format)|MREA]])
| 1
| '''Area MREA ID'''
| ID of this area's [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID
| 1
| '''Internal Area ID'''
| Doesn't actually refer to an asset, but has the same length as an asset ID. This ID is used internally by some things to refer to this area, such as Script Layer Controllers.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Attached Area Count'''
| Count of areas attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u16
| ''Attached Area Count''
| '''Attached Area Index Array'''
| Array of area indices attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Dependencies|Area Dependencies]]
| 1
| '''Dependencies'''
| Asset dependencies in this area. See below for details. Starting in Prime 3, this section has been moved inside the [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Dock Count'''
| Count of Dock instances in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Dock|Dock]]
| ''Dock Count''
| '''Dock Array'''
| Array describing all docks in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Module Dependencies|Area Module Dependencies]]
| 1
| '''Module Dependencies'''
| REL module dependencies in this area. See below for details. The equivalent section in Prime 3 and DKCR describing RSO modules has been moved inside the [[MREA (File Format)|MREA]] format.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 0?
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Internal Area Name'''
| Internal name of this area. This name will be used ingame on the map screen if no ''Area Name ID'' is specified, prefixed with "!!".
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of area}}
|}

==== 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 Format)|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):

* [[SCAN (File Format)|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.
* [[ANCS (File Format)|ANCS]] per-character dependencies for PlayerActor script instances are not included; this allows the game to avoid keeping assets in memory for suits that the player doesn't have. The exception is the Empty Suit character (character index 5 in MP1, and index 3 in MP2), which is a low-memory-overhead character that allows for the list to include all common assets that are stored in the file per-character (such as particle effects).
* 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 (File Format)|MREA]] format.

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Dependency Count'''
| Count of dependencies.
|-
| [[#Dependency|Dependency]]
| ''Dependency Count''
| '''Dependency Array'''
| Array of all asset dependencies in this area.
|-
| u32
| 1
| '''Dependency Offset Count'''
| Count of dependency offsets. This will be equal to the area script layer count + 1.
|-
| u32
| ''Dependency Offset Count''
| '''Dependency Offset Array'''
| Array of offsets into the dependency array. There is one offset per script layer, with the offset referring to the index of that layer's first dependency. There is a final extra offset that points to area dependencies that are not layer-specific.
|}

===== Dependency =====

{| class="wikitable"
! Offset
! Type
! Count
! Name
|-
| 0x0
| Asset ID
| 1
| '''Dependency Asset ID'''
|-
| 0x4
| char
| 4
| '''Dependency Asset Type'''
|}

==== Dock ====

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Connecting Dock Count'''
| Count of docks connecting to this one. Typically 1 (but there are docks in Prime 3 that connect to multiple areas).
|-
| [[#Connecting Dock|Connecting Dock]]
| ''Connecting Dock Count''
| '''Connecting Dock Array'''
| Array describing all docks connected to this one.
|-
| u32
| 1
| '''Dock Coordinate Count'''
| Array of dock coordinates in the next array.
|-
| Vector3
| ''Dock Coordinate Count''
| '''Dock Coordinates'''
| Exact purpose/function of this is not known yet.
|}

===== Connecting Dock =====

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Area Index'''
| Index of the area this dock is in.
|-
| 0x4
| u32
| '''Dock Index'''
| Index of this dock within its area.
|}

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''REL Module Count'''
| Count of REL modules in the next array.
|-
| string
| ''REL Module Count''
| '''REL Module Array'''
| REL modules used by this area. Each array entry is the filename of a .REL module.
|-
| u32
| 1
| '''REL Offset Count'''
| Count of REL offsets in the next array. Should be equal to the area script layer count * 2.
|-
| u32
| ''REL Offset Count''
| '''REL Offset Array'''
| Array of offsets into the ''REL Module Array''. There are two offsets per script layer, with the first one being that layer's start index and the second one effectively being that layer's end index.
|}

=== Audio Group ===

This structure is only present in Prime 1 and describes an [[AGSC (File Format)|AGSC]] file being used in this world.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Group ID'''
| Group ID for this audio group. This is the same value that can be found in the Project chunk in the referenced [[AGSC (File Format)|AGSC]] file.
|-
| 0x4
| Asset ID ([[AGSC (File Format)|AGSC]])
| '''AGSC ID'''
| The [[AGSC (File Format)|AGSC]] file for this audio group.
|-
| 0x8
| colspan=3 {{unknown|End of audio group definition}}
|}

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

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Layer Count'''
| Count of layers in this area.
|-
| 0x4
| u64
| '''Layer Flags'''
| See above for a description of how these work.
|-
| 0x8
| colspan=3 {{unknown|End of area layer flags}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

Template:Mainpagelinks

2019-06-30T16:41:00Z

Aruki:

{|cellpadding="5" cellspacing="3" align="center" style="text-align:center; margin-bottom:20px; float:center; border:1px solid; box-shadow: 0 0 5px #6DBACD; border-radius:6px; border-color:#6dbacd;" ! width="45%"
|[[File:Powercannon_render3.png|200px]]
|'''Help us research and document!'''
'''Join the discussion: [https://discord.gg/6YTN7q6 Metroid Prime Hacking Discord]'''
{|align="center" style="text-align:center;"
|[[File:Morphball_wire.png|50px|link=Category:Major research needed]]
|[[File:Morphball_wirerender.png|50px|link=Category:Moderate research needed]]
|[[File:Morphball_render.png|50px|link=Category:Minor research needed]]
|-
|[[:Category:Major research needed|'''File formats that need major research''']]
|[[:Category:Moderate research needed|'''File formats that need moderate research''']]
|[[:Category:Minor research needed|'''File formats that need minor research''']]
|}
|}

[[Category:Templates]]

TXTR (Metroid Prime)

2019-04-18T09:16:22Z

Aruki: /* Image Formats */

''See [[TXTR (File Format)]] for the other revisions of this format.''

'''TXTR''' is, as the name suggests, the Retro Studios texture format. The format remains completely unchanged from Metroid Prime all the way up to Donkey Kong Country Returns.

{{todo|Could possibly use some more information on how the formats work and how to decode them, but then again the Custom Mario Kart Wiiki has this covered pretty nicely already.}}

__TOC__

== Format ==

TXTR files contain a very short 12-byte header, followed by the image data.

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Image format'''. Possible values range from 0x0 to 0xA; see below for more details.
|-
| 0x4
| 2
| '''Width'''
|-
| 0x6
| 2
| '''Height'''
|-
| 0x8
| 4
| '''Mipmap count'''
|-
| 0xC
| colspan=2 {{unknown|End of header}}
|}

=== Palettes ===

The C4 and C8 image formats contain a palette table after the header, before the image data begins.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Palette format'''. Possible values range from 0 to 2.
|-
| 0x4
| 2
| '''Width'''. always 1 in C4, 256 in C8
|-
| 0x6
| 2
| '''Height'''. always 16 in C4, 1 in C8
|-
| 0x8
| Varies
| '''Palette colors'''. 16-bit color values; 16 colors in C4, 256 in C8.
|-
| colspan=3 {{unknown|End of palette table; image data begins immediately after}}
|}

== Image Formats ==

There are 11 different image formats supported by the hardware. Rather than storing pixels in a linear left-to-right order, GameCube textures are swizzled in blocks. Blocks are 32 bytes large (except for RGBA8), with their dimensions varying depending on the BPP of the image format.

For example, suppose you have a format that stores 4x4 blocks. Pixels 1-4 of the image will make up the first row of the first block; pixels 5-8 will make up the second row; 9-12 will make up the third row; 13-16 will make up the fourth row, completing the block; and then 17-20 will begin the first row of the second block, appearing directly to the right of the first row of the first block.

{| class="wikitable"
! ID
! Name
! Bits per pixel
! Block size
! Description
|-
| 0x0
| I4
| 4
| 8x8
| 4-bit greyscale intensity values. Two pixels per byte.
|-
| 0x1
| I8
| 8
| 8x4
| 8-bit greyscale intensity values.
|-
| 0x2
| IA4
| 8
| 8x4
| 4-bit greyscale intensity values with an additional 4-bit alpha channel.
|-
| 0x3
| IA8
| 16
| 4x4
| 8-bit greyscale intensity values with an additional 8-bit alpha channel.
|-
| 0x4
| C4
| 4
| 8x8
| 4-bit palette indices.
|-
| 0x5
| C8
| 8
| 8x4
| 8-bit palette indices.
|-
| 0x6
| C14x2
| 16
| 4x4
| Another palette format. Not used by any official textures.
|-
| 0x7
| RGB565
| 16
| 4x4
| 16-bit colors without alpha.
|-
| 0x8
| RGB5A3
| 16
| 4x4
| 16-bit colors with alpha.
|-
| 0x9
| RGBA8
| 32
| 4x4
| Uncompressed 32-bit colors with alpha.
|-
| 0xA
| CMPR
| 4
| 8x8
| Compressed textures (almost the same as DXT1, but with a couple small differences)
|}

== External links ==

* [http://wiki.tockdom.com/wiki/Image_Formats Custom Mario Kart Wiki]: More detailed information on each format, and how to decode them.

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

PAK (Tropical Freeze)

2019-04-13T01:33:09Z

Aruki: /* Tools */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''PAK format''' in Donkey Kong Country: Tropical Freeze is the third version of the .pak format, with another layout overhaul, file IDs being extended from 64 bits to 128 bits (as they now use a new GUID system that is used to associate IDs with various objects across the entire game), and the addition of an extra metadata section.

__TOC__

== Format ==

The Tropical Freeze pak format contains three main header sections: [[#Resource Directory|the resource directory]], [[#Metadata|metadata]], and [[#Name Tags|name tags]].

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Description
|-
| 0x0
| [[Form Descriptor (Tropical Freeze)|Form Descriptor]]
| 1
| '''Package Form Descriptor'''
| Data type is <code>PACK</code>
|-
| 0x20
| [[Form Descriptor (Tropical Freeze)|Form Descriptor]]
| 1
| '''Table of Contents Form Descriptor'''
| Data type is <code>TOCC</code>
|-
| 0x40
| colspan=4 {{unknown|Header data sections (ADIR, META, and STRG) begin}}
|}

=== Asset Directory ===

The asset directory contains a list of every asset in the pak, associating a GUID with an offset/size in the file. Assets are sorted by their GUID in numerical order, which is often not the same order that they actually appear in the file.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''Asset Directory Chunk Descriptor'''
| Data type is <code>ADIR</code>
|-
| 0x18
| u32
| 1
| '''Asset Count'''
|
|-
| 0x1C
| [[#Asset Entry|Asset Entry]]
| ''Asset Count''
| '''Asset Directory'''
|
|-
| colspan=5 {{unknown|End of <code>ADIR</code> section}}
|}

==== Asset Entry ====

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''Asset Type'''
| This is an abbreviated fourCC that doubles as the asset's cooked file extension.
|-
| 0x4
| GUID
| 1
| '''Asset ID'''
|
|-
| 0x14
| u64
| 1
| '''Offset'''
| This is an absolute offset relative to the start of the pak file.
|-
| 0x1C
| u64
| 1
| '''Size'''
|
|-
| 0x24
| colspan=4 {{unknown|End of asset entry}}
|}

=== Metadata ===

The metadata section lists extra metadata for some asset types, which are associated with them via their file ID. The structure and contents of a <code>META</code> entry varies depending on the asset type; check that type's page on the Wiki to check the structure of its <code>META</code> entries.

Note that a lot of formats don't have any extra metadata. If there's no assets with extra metadata in the entire pak, then the <code>META</code> section won't appear in the file at all.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''Metadata Chunk Descriptor'''
| Data type is <code>META</code>
|-
| 0x18
| u32
| 1
| '''Metadata Entry Count'''
|
|-
| 0x1C
| [[#Metadata Entry|Metadata Entry]]
| ''Metadata Entry Count''
| '''Metadata Entry Table'''
|
|-
| colspan=5 {{unknown|End of <code>META</code> section}}
|}

==== Metadata Entry ====

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| GUID
| 1
| '''Asset ID'''
| This is the ID of the asset that this metadata entry is associated with
|-
| 0x10
| u32
| 1
| '''Metadata Offset'''
| Relative to the start of the <code>META</code> section.
|-
| 0x14
| colspan=4 {{unknown|End of metadata entry}}
|}

=== Name Tags===

The name tags section associates certain assets with string names. These are the "main" assets of the pak; any asset that does not have a name is a dependency of one of the ones that do.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''Name Tags Chunk Descriptor'''
| Data type is <code>STRG</code>
|-
| 0x18
| u32
| 1
| '''Name Tag Count'''
|
|-
| 0x1C
| [[#Name Tag|Name Tag]]
| ''Name Tag Count''
| '''Name Tag Table'''
|
|-
| colspan=5 {{unknown|End of <code>STRG</code> section}}
|}

==== Name Tag ====

{|class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''Asset Type'''
|
|-
| 0x4
| GUID
| 1
| '''Asset ID'''
|
|-
| 0x14
| string
| 1
| '''Asset Name'''
| Zero-terminated.
|-
| colspan=5 {{unknown|End of name tag}}
|}

== Tools ==

* [https://www.dropbox.com/s/bba2n9jzj719by4/PakTool.rar?dl=0 PakTool] by Aruki; can extract and decompress files from Tropical Freeze paks, but doesn't support repacking or recompressing them

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

PAK (Metroid Prime 3)

2019-04-13T01:32:53Z

Aruki: /* Tools */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime 3 and Donkey Kong Country Returns is a new version of the pak format with some slight changes. The most notable change is that resource IDs have been extended from 32 bits to 64 bits. The new format also aligns to 64-byte boundaries, rather than 32. Aside from that, the other changes are mainly organizational; it's still largely the same data as older versions of the format.

Note that the Metroid Prime 3 E3 prototype uses a slightly modified version of the Metroid Prime pak format, not this one. See the [[PAK (Metroid Prime)]] page for more info on that revision of the format.

{{research|1|Research needs to be done on how to order files to optimize loads. Also, the very first part of the header is mostly unknown.}}

__TOC__

== Format==

The header is split into a number of smaller chunks that are each padded to the next 64-byte offset.

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''. Always 2.}}
|-
| 0x4
| 4
| '''Header size'''
|-
| 0x8
| 16
| '''MD5 hash''' of the entire pak after the first 64 bytes.
|-
| 0x18
| colspan=2 {{unknown|End of header; pad to 64 bytes}}
|}

=== Table of Contents ===

The next part of the file, starting at 0x40, is a brief list of each section in the pak and its size. Although it uses a count value, this section always lists the same data in the same order.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Section count'''; always 3
|-
| 0x4
| 4
| '''"STRG" fourCC'''
|-
| 0x8
| 4
| '''Named Resources section size'''
|-
| 0xC
| 4
| '''"RSHD" fourCC'''
|-
| 0x10
| 4
| '''Resource Table section size'''
|-
| 0x14
| 4
| '''"DATA" fourCC'''
|-
| 0x18
| 4
| '''File data section size'''
|-
| 0x1C
| colspan=2 {{unknown|End of ToC; pad to 64 bytes}}
|}

=== Named Resources ===

This section, always starting at 0x80, lists named resources. These are the files that the game has direct access to; every other file in the pak will be a dependency of one of these.

It starts with a 32-bit count, followed by the table itself; each entry of the table is structured as follows:

{| class="wikitable"
! Type
! Size
! Description
|-
| string
| -
| '''Name'''; zero-terminated
|-
| fourCC
| 4
| '''Resource type'''
|-
| u64
| 8
| '''Resource ID'''
|}

=== Resource Table ===

The final table contains a list of every resource in the pak. Following a 32-bit count value, each resource entry is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Compression flag'''; this will either be 0 or 1, with 1 denoting a compressed file.
|-
| 0x4
| 4
| '''Resource type''' fourCC.
|-
| 0x8
| 8
| '''Resource ID'''
|-
| 0x10
| 4
| '''Size''' (note: always a multiple of 64; the end of the file is padded with 0xFF if necessary)
|-
| 0x14
| 4
| '''Offset''' (relative to the start of the DATA section)
|-
| 0x18
| colspan=2 {{unknown|End of entry}}
|}

== Compression ==

Some files within paks are compressed; in Prime 3, files are compressed with segmented LZO1X, just like Prime 2. In DKCR, on the other hand, files are compressed as a single zlib stream, like Prime 1. In either game, every compressed file is formatted the same way, starting with some metadata detailing the structure of the compressed data.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''"CMPD" fourCC'''
|-
| 0x4
| 4
| '''Compressed block count'''
|}

Each compressed block is structured as follows.

For each block, if the compressed and decompressed sizes match, that indicates the block is uncompressed.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Flag'''
|-
| 0x1
| 3
| '''Compressed size'''
|-
| 0x4
| 4
| '''Decompressed size'''
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The flag value can be set to the following possible values:

* If the block count is 1, it will be 0xA0 on block 1.
* If blocks 2/3 are compressed, they will have it set to 0xC0.
* If blocks 2/3 are uncompressed, they will have it set to 0x40.
* 0 in all other circumstances.

Files are left uncompressed if the compressed data is larger than the uncompressed data. Barring that, the following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[CHAR (File Format)|CHAR]]
* [[SAND (File Format)|SAND]]
* [[ANIM (File Format)|ANIM]]
* [[SCAN (Metroid Prime 2)|SCAN]]
* [[FONT (File Format)|FONT]]
* [[CSMP (File Format)|CSMP]]
* [[STRG (File Format)|STRG]]
* [[CAAD (File Format)|CAAD]]
* [[DCLN (File Format)|DCLN]]
* [[USRC (File Format)|USRC]]

The following formats are compressed when their uncompressed size is at least 0x80 bytes:

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[CRSC (File Format)|CRSC]]
* [[BFRC (File Format)|BFRC]]
* [[SPSC (File Format)|SPSC]]
* [[DPSC (File Format)|DPSC]]

== File Order ==

File order matters significantly and easily makes the difference between a pak loading quickly and optimally, or taking 30+ seconds on every door. While more research is required to figure out exactly how files should be ordered to optimize loading, the game generally clusters together resources that are used together, and a file's dependencies generally appear directly before the file itself. The game also often duplicates assets that are used multiple times within the same pak; there might be 10-11 copies of the same model file in order to allow the game to more easily find and load that file when it needs it.

== Tools ==

* [https://www.dropbox.com/s/bba2n9jzj719by4/PakTool.rar?dl=0 PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

PAK (Metroid Prime)

2019-04-13T01:31:46Z

Aruki: /* Tools */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int16
| '''Version Number Major'''
| Always 3
|-
| 0x2
| int16
| '''Version Number Minor'''
| Always 5
|-
| 0x4
| int32
| '''Unused'''
| Always 0
|-
| 0x8
| colspan=3 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| {{FourCC}}
| 1
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x4
| int32
| 1
| '''Asset ID'''
| Unique identifier for this asset.
|-
| 0x8
| int32
| 1
| '''Name Length'''
| Length of the name string
|-
| 0xC
| char
| ''Name Length''
| '''Name String'''
| Name of the asset. Not zero-terminated. This name usually corresponds to a hardcoded string that the game uses to look up the asset, so this generally can't be changed.
|-
| colspan=5 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int32
| '''Compression Flag'''
| Value will be either 0 or 1, with 1 denoting that the asset is compressed.
|-
| 0x4
| {{FourCC}}
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x8
| int32
| '''Asset ID'''
| Unique identifier for this asset. This ID is used by other assets to reference this one.
|-
| 0xC
| int32
| '''Size'''
| Size of the asset data in the pak. This is always 32-byte-aligned. The end of the asset is padded with 0xFF.
|-
| 0x10
| int32
| '''Offset'''
| Offset of the asset data within the pak. This is an absolute offset.
|-
| 0x14
| colspan=4 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless, as there's no benefit to the compression in this scenario).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If any other assets were missing from the list, they are loaded here. It's very important to know that contrary to the previous steps, assets that still aren't in memory at this point are loaded ''synchronously'', which means the game will hang until loading is complete; therefore, you want as few assets as possible to be left to load at this point. (You can observe this hang even in the base game - there is a small freeze towards the end of loading Artifact Temple.)
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://www.dropbox.com/s/bba2n9jzj719by4/PakTool.rar?dl=0 PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

Lights (Metroid Prime)

2019-03-27T04:30:29Z

Aruki: /* Metroid Prime 3 */

The '''lights''' section in Metroid Prime areas defines several different types of lights: local ambient, directional, spot, and custom. Every light type has the same structure in the file; however, different types are utilized in different ways by the engine.

{{research|minor|Lights are mostly figured out; the remaining unknowns are very likely unused, because the game's code never accesses them or passes them to the main light class, but it would be good to have some double-checking. There's also more unknowns in the Prime 3 lights format that probably -are- used.}}

__TOC__

==Format==

The lights section has a very brief header consisting of the magic value <code>0xBABEDEAD</code>. It's then followed by a number of '''light layers'''. Each light layer consists of a count value, then an array of lights. Each layer represents a separate set of lights; actors can choose with set they're lit with through an object property in LightParameters. The number of light layers is static, but it varies from game to game; Prime 1 and 2 can have up to two light layers, while Prime 3 can have four.

=== Metroid Prime 1/2 ===

Each light is a 0x41-byte struct. Note that the same structure is used for every light type, but not every value is used by every type; in fact, some of them aren't used by any of them.

{| class="wikitable"
! Offset
! Type
! Description
! Notes
|-
| 0x0
| long
| '''Light Type'''
|
|-
| 0x4
| float3
| '''Color'''
| There is no alpha component.
|-
| 0x10
| float3
| '''Position'''
|
|-
| 0x1C
| float3
| '''Direction'''
|
|-
| 0x28
| float
| '''Brightness'''
| Multiplied by color for local ambient, used to calculate distance attenuation coefficients for spot/custom
|-
| 0x2C
| float
| '''Spot Cutoff'''
| Used to calculate angle attenuation coefficients for spotlights
|-
| 0x30
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x34
| bool
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x35
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x39
| long
| '''Falloff Type'''
| Possible values: 0 - Constant; 1 - Linear; 2 - Quadratic
|-
| 0x3D
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x41
| colspan=3 {{unknown|End of light}}
|}

=== Metroid Prime 3 ===

Prime 3's light format is very similar, but there's a number of new fields introduced (most of which are currently unknown).

{| class="wikitable"
! Offset
! Type
! Description
! Notes
|-
| 0x0
| long
| '''Light Type'''
|
|-
| 0x4
| float4
| '''Color'''
| This color ''does'' have an alpha component, unlike Prime 1 lights.
|-
| 0x14
| float3
| '''Position'''
|
|-
| 0x20
| float3
| '''Direction'''
|
|-
| 0x2C
| float3
| '''Codirection'''
| The light's up vector
|-
| 0x38
| float
| '''Brightness'''
| Multiplied by color for local ambient, used to calculate distance attenuation coefficients for spot/custom
|-
| 0x3C
| float
| '''Spot Cutoff'''
| Used to calculate angle attenuation coefficients for spotlights
|-
| 0x40
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x44
| bool
| {{unknown|'''Unknown'''}}
|
|-
| 0x45
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x49
| u32
| '''Falloff Type'''
|
|-
| 0x4D
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x51
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x55
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x59
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x5D
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x61
| u32
| {{unknown|'''Unknown'''}}
|
|-
| 0x65
| colspan=3 {{unknown|End of light}}
|}

=== Light Types ===

The first value in each light is a type value. These are the possible values:

{| class="wikitable"
! Type
! Name
|-
| 0x0
| Local Ambient
|-
| 0x1
| Directional
|-
| 0x3
| Spot
|-
| Other
| Custom
|}

Note that although the game supports point lights, those can't be set through the MREA files; custom lights are used for omnidirectional lights.

== Light Functionality ==

=== Local Ambient ===

Ambient lights represent the brightness/color of an area in the absence of any regular lights. There's typically one of these per area; it's not known how they interact if there's more than one. For ambient lights, the color is not used directly; it's multiplied by the Multiplier value and then clamped between 0 and 1, and the result is used as the ambient color.

=== Directional ===

Directional lights are lights that have a constant direction for every vertex in the scene. Since GX doesn't have any built-in functions for handling directional lights, the way the game implements this is by taking the light's direction, inverting it, and then multiplying it by 1048576; the result is used as the light's position.

=== Spot ===

Spot lights shine in a specific direction from a specific position. Distance attenuation is calculated the same way as with custom lights. For angular attenuation, this is calculated using the spot cutoff parameter. The cutoff value from the file is halved and converted from degrees to radians, and the cosine of the result is calculated. Then the angular attenuation coefficients are calculated as:

<pre>(0.0, -CosCutoff / (1.0 - CosCutoff), 1.0 / (1.0 - CosCutoff))</pre>

=== Custom ===

While the other light types only use a couple of the value to generate lights out of what's essentially a preset setup, custom lights allow for much greater control and customization of the light properties. They're commonly used to represent omnidirectional lights; as such they're by far the most common light type in the game. For attenuation, angular attenuation is set to (1.0, 0.0, 0.0). Distance attenuation is calculated differently depending on the falloff type.

Each falloff type will set one distance attenuation coefficient, with the other two set to 0. For each type:

* 0: '''Constant''': Coefficient A is set to <code>2.0 / Brightness</code>
* 1: '''Linear''': Coefficient B is set to <code>250 / Brightness</code>
* 2: '''Quadratic''': Coefficient C is set to <code>25000 / Brightness</code>

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

Lights (Metroid Prime)

2019-03-27T04:30:18Z

Aruki: /* Custom */

The '''lights''' section in Metroid Prime areas defines several different types of lights: local ambient, directional, spot, and custom. Every light type has the same structure in the file; however, different types are utilized in different ways by the engine.

{{research|minor|Lights are mostly figured out; the remaining unknowns are very likely unused, because the game's code never accesses them or passes them to the main light class, but it would be good to have some double-checking. There's also more unknowns in the Prime 3 lights format that probably -are- used.}}

__TOC__

==Format==

The lights section has a very brief header consisting of the magic value <code>0xBABEDEAD</code>. It's then followed by a number of '''light layers'''. Each light layer consists of a count value, then an array of lights. Each layer represents a separate set of lights; actors can choose with set they're lit with through an object property in LightParameters. The number of light layers is static, but it varies from game to game; Prime 1 and 2 can have up to two light layers, while Prime 3 can have four.

=== Metroid Prime 1/2 ===

Each light is a 0x41-byte struct. Note that the same structure is used for every light type, but not every value is used by every type; in fact, some of them aren't used by any of them.

{| class="wikitable"
! Offset
! Type
! Description
! Notes
|-
| 0x0
| long
| '''Light Type'''
|
|-
| 0x4
| float3
| '''Color'''
| There is no alpha component.
|-
| 0x10
| float3
| '''Position'''
|
|-
| 0x1C
| float3
| '''Direction'''
|
|-
| 0x28
| float
| '''Brightness'''
| Multiplied by color for local ambient, used to calculate distance attenuation coefficients for spot/custom
|-
| 0x2C
| float
| '''Spot Cutoff'''
| Used to calculate angle attenuation coefficients for spotlights
|-
| 0x30
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x34
| bool
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x35
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x39
| long
| '''Falloff Type'''
| Possible values: 0 - Constant; 1 - Linear; 2 - Quadratic
|-
| 0x3D
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x41
| colspan=3 {{unknown|End of light}}
|}

=== Metroid Prime 3 ===

Prime 3's light format is very similar, but there's a number of new fields introduced (most of which are currently unknown).

{| class="wikitable"
! Offset
! Type
! Description
! Notes
|-
| 0x0
| long
| '''Light Type'''
|
|-
| 0x4
| float4
| '''Color'''
| This color ''does'' have an alpha component, unlike Prime 1 lights.
|-
| 0x14
| float3
| '''Position'''
|
|-
| 0x20
| float3
| '''Direction'''
|
|-
| 0x2C
| float3
| '''Codirection'''
| The light's up vector
|-
| 0x38
| float
| '''Brightness'''
| Multiplied by color for local ambient, used to calculate distance attenuation coefficients for spot/custom
|-
| 0x3C
| float
| '''Spot Cutoff'''
| Used to calculate angle attenuation coefficients for spotlights
|-
| 0x40
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x44
| bool
| {{unknown|'''Unknown'''}}
|
|-
| 0x45
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x49
| u32
| Falloff Type
|
|-
| 0x4D
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x51
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x55
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x59
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x5D
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x61
| u32
| {{unknown|'''Unknown'''}}
|
|-
| 0x65
| colspan=3 {{unknown|End of light}}
|}

=== Light Types ===

The first value in each light is a type value. These are the possible values:

{| class="wikitable"
! Type
! Name
|-
| 0x0
| Local Ambient
|-
| 0x1
| Directional
|-
| 0x3
| Spot
|-
| Other
| Custom
|}

Note that although the game supports point lights, those can't be set through the MREA files; custom lights are used for omnidirectional lights.

== Light Functionality ==

=== Local Ambient ===

Ambient lights represent the brightness/color of an area in the absence of any regular lights. There's typically one of these per area; it's not known how they interact if there's more than one. For ambient lights, the color is not used directly; it's multiplied by the Multiplier value and then clamped between 0 and 1, and the result is used as the ambient color.

=== Directional ===

Directional lights are lights that have a constant direction for every vertex in the scene. Since GX doesn't have any built-in functions for handling directional lights, the way the game implements this is by taking the light's direction, inverting it, and then multiplying it by 1048576; the result is used as the light's position.

=== Spot ===

Spot lights shine in a specific direction from a specific position. Distance attenuation is calculated the same way as with custom lights. For angular attenuation, this is calculated using the spot cutoff parameter. The cutoff value from the file is halved and converted from degrees to radians, and the cosine of the result is calculated. Then the angular attenuation coefficients are calculated as:

<pre>(0.0, -CosCutoff / (1.0 - CosCutoff), 1.0 / (1.0 - CosCutoff))</pre>

=== Custom ===

While the other light types only use a couple of the value to generate lights out of what's essentially a preset setup, custom lights allow for much greater control and customization of the light properties. They're commonly used to represent omnidirectional lights; as such they're by far the most common light type in the game. For attenuation, angular attenuation is set to (1.0, 0.0, 0.0). Distance attenuation is calculated differently depending on the falloff type.

Each falloff type will set one distance attenuation coefficient, with the other two set to 0. For each type:

* 0: '''Constant''': Coefficient A is set to <code>2.0 / Brightness</code>
* 1: '''Linear''': Coefficient B is set to <code>250 / Brightness</code>
* 2: '''Quadratic''': Coefficient C is set to <code>25000 / Brightness</code>

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

Lights (Metroid Prime)

2019-03-27T04:29:53Z

Aruki:

The '''lights''' section in Metroid Prime areas defines several different types of lights: local ambient, directional, spot, and custom. Every light type has the same structure in the file; however, different types are utilized in different ways by the engine.

{{research|minor|Lights are mostly figured out; the remaining unknowns are very likely unused, because the game's code never accesses them or passes them to the main light class, but it would be good to have some double-checking. There's also more unknowns in the Prime 3 lights format that probably -are- used.}}

__TOC__

==Format==

The lights section has a very brief header consisting of the magic value <code>0xBABEDEAD</code>. It's then followed by a number of '''light layers'''. Each light layer consists of a count value, then an array of lights. Each layer represents a separate set of lights; actors can choose with set they're lit with through an object property in LightParameters. The number of light layers is static, but it varies from game to game; Prime 1 and 2 can have up to two light layers, while Prime 3 can have four.

=== Metroid Prime 1/2 ===

Each light is a 0x41-byte struct. Note that the same structure is used for every light type, but not every value is used by every type; in fact, some of them aren't used by any of them.

{| class="wikitable"
! Offset
! Type
! Description
! Notes
|-
| 0x0
| long
| '''Light Type'''
|
|-
| 0x4
| float3
| '''Color'''
| There is no alpha component.
|-
| 0x10
| float3
| '''Position'''
|
|-
| 0x1C
| float3
| '''Direction'''
|
|-
| 0x28
| float
| '''Brightness'''
| Multiplied by color for local ambient, used to calculate distance attenuation coefficients for spot/custom
|-
| 0x2C
| float
| '''Spot Cutoff'''
| Used to calculate angle attenuation coefficients for spotlights
|-
| 0x30
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x34
| bool
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x35
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x39
| long
| '''Falloff Type'''
| Possible values: 0 - Constant; 1 - Linear; 2 - Quadratic
|-
| 0x3D
| float
| {{unknown|'''Unknown'''}}
| Possibly unused
|-
| 0x41
| colspan=3 {{unknown|End of light}}
|}

=== Metroid Prime 3 ===

Prime 3's light format is very similar, but there's a number of new fields introduced (most of which are currently unknown).

{| class="wikitable"
! Offset
! Type
! Description
! Notes
|-
| 0x0
| long
| '''Light Type'''
|
|-
| 0x4
| float4
| '''Color'''
| This color ''does'' have an alpha component, unlike Prime 1 lights.
|-
| 0x14
| float3
| '''Position'''
|
|-
| 0x20
| float3
| '''Direction'''
|
|-
| 0x2C
| float3
| '''Codirection'''
| The light's up vector
|-
| 0x38
| float
| '''Brightness'''
| Multiplied by color for local ambient, used to calculate distance attenuation coefficients for spot/custom
|-
| 0x3C
| float
| '''Spot Cutoff'''
| Used to calculate angle attenuation coefficients for spotlights
|-
| 0x40
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x44
| bool
| {{unknown|'''Unknown'''}}
|
|-
| 0x45
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x49
| u32
| Falloff Type
|
|-
| 0x4D
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x51
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x55
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x59
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x5D
| float
| {{unknown|'''Unknown'''}}
|
|-
| 0x61
| u32
| {{unknown|'''Unknown'''}}
|
|-
| 0x65
| colspan=3 {{unknown|End of light}}
|}

=== Light Types ===

The first value in each light is a type value. These are the possible values:

{| class="wikitable"
! Type
! Name
|-
| 0x0
| Local Ambient
|-
| 0x1
| Directional
|-
| 0x3
| Spot
|-
| Other
| Custom
|}

Note that although the game supports point lights, those can't be set through the MREA files; custom lights are used for omnidirectional lights.

== Light Functionality ==

=== Local Ambient ===

Ambient lights represent the brightness/color of an area in the absence of any regular lights. There's typically one of these per area; it's not known how they interact if there's more than one. For ambient lights, the color is not used directly; it's multiplied by the Multiplier value and then clamped between 0 and 1, and the result is used as the ambient color.

=== Directional ===

Directional lights are lights that have a constant direction for every vertex in the scene. Since GX doesn't have any built-in functions for handling directional lights, the way the game implements this is by taking the light's direction, inverting it, and then multiplying it by 1048576; the result is used as the light's position.

=== Spot ===

Spot lights shine in a specific direction from a specific position. Distance attenuation is calculated the same way as with custom lights. For angular attenuation, this is calculated using the spot cutoff parameter. The cutoff value from the file is halved and converted from degrees to radians, and the cosine of the result is calculated. Then the angular attenuation coefficients are calculated as:

<pre>(0.0, -CosCutoff / (1.0 - CosCutoff), 1.0 / (1.0 - CosCutoff))</pre>

=== Custom ===

While the other light types only use a couple of the value to generate lights out of what's essentially a preset setup, custom lights allow for much greater control and customization of the light properties. They're commonly used to represent omnidirectional lights; as such they're by far the most common light type in the game. For attenuation, angular attenuation is set to (1.0, 0.0, 0.0). Distance attenuation is calculated differently depending on the falloff type.

Each falloff type will set one distance attenuation coefficient, with the other two set to 0. For each type:

* 0: '''Constant''': Coefficient A is set to <code>2.0 / Multiplier</code>
* 1: '''Linear''': Coefficient B is set to <code>250 / Multiplier</code>
* 2: '''Quadratic''': Coefficient C is set to <code>25000 / Multiplier</code>

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

GUID

2019-02-05T07:19:58Z

Aruki:

A '''GUID''' is a 128-bit ID used to uniquely identify an object. They are used in [[Metroid Prime 3: Corruption]] and [[Donkey Kong Country Returns]] to uniquely identify a value stored in the save file. They are also commonly used in [[Donkey Kong Country: Tropical Freeze]] as identifiers for all sorts of objects.

== MP3/DKCR ==

Script objects that need to preserve data between play sessions will have a GUID listed as a property (with property ID 0x16D9A75D, which hashes to "ObjectId"). That ID is also stored in the [[SAVW (File Format)|SAVW]] file and associated with the object's instance ID. At runtime, when the object is loaded it uses the GUID to look up the value of the parameter and then updates itself accordingly. The GUIDs declared from the SAVW file are only valid within the world the SAVW file is associated with; reusing the same GUID from a different world is treated as a separate value.

GUIDs are also used by script layers to track whether the layer is active. The GUIDs associated with each layer can be found in the [[MLVL (File Format)|MLVL]] file. Layer GUIDs are different from the other IDs in that they are valid across the entire game, when referenced from any world.

GUIDs are used by the following objects:

{| class="wikitable"
! Object
! Usage
! MP3
! DKCR
|-
| Script Layer
| Tracks whether the layer is active or not.
| {{check}}
| {{check}}
|-
| CinematicCamera
| Tracks whether the cutscene has been watched before. If so, cinematic skip can be enabled. (CinematicCameras that don't have cinematic skip enabled don't have a GUID.)
| {{check}}
| {{check}}
|-
| MemoryRelay
| Tracks whether the relay is active.
| {{check}}
| {{check}}
|-
| Door
| Tracks whether the door has been opened at some point during gameplay. This is used to change the door color on the map.
| {{check}}
| {{nocheck}}
|-
| Pickup
| Tracks whether the pickup has been acquired before.
* In MP3, this is used to remove upgrades and expansions that the player has already collected from the map.
* In DKCR, this is used to grey out puzzle pieces that the player has already collected and prevent them from being collecting a second time.
| {{check}}
| {{check}}
|}

[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

SAVA (File Format)

2019-02-05T07:19:20Z

Aruki: removing some speculation

The '''SAVA format''' is the area-specific counterpart of the [[SAVW (File Format)|SAVW format]]. Although every Retro game up to DKCR seems to have some support for the format (judging by its appearance in the dol's cooked extension list going as far back as Prime 1), SAVA files are very rare; there is only one SAVA file that appears in any of the retail release builds of any of the games, which is used with the main menu in Metroid Prime 3 and Metroid Prime Trilogy. The [[Metroid Prime 3 Prototype|Metroid Prime 3 E3 prototype]] has more; Metroid.pak contains a SAVA file for each area.

The structure of a SAVA file is the same as a [[SAVW (File Format)|SAVW file]], except the data it contains applies to a particular area rather than the entire world. The <code>0xC001D00D</code> magic from SAVW is missing, along with the area count. The version is still present as the first value in the file but uses different version numbers than SAVW.

{| class="wikitable"
! Version
! Game
|-
| 0x7
| Metroid Prime 3 Prototype
|-
| 0x8
| Metroid Prime 3: Corruption
|}

[[Category:File Formats]]
[[Category:Metroid Prime 3 Prototype]]
[[Category:Metroid Prime 3: Corruption]]

SAVW (File Format)

2019-02-05T07:18:04Z

Aruki:

The '''SAVW format''' describes save data in the Metroid Prime series and Donkey Kong Country Returns. It allows any data used by the game's script data that needs to be preserved between play sessions to be saved and retrieved from the save file without the executable having to know anything about it. This is used for, for instance, saving whether a particular MemoryRelay has been activated, or whether a specific layer has been toggled on.

__TOC__

== Format ==

The format is basically just a series of arrays. The structure remains more or less the same across every game, just with arrays being added or removed. The main difference between formats is that starting in Metroid Prime 3, the engine stores references to saved variables through a combination of a 128-bit state ID and an instance ID instead of implicitly associating them via instance IDs alone. The state ID is mirrored in another file (usually on the object via a property).

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| u32
| 1
| '''Magic'''
| Always <code>0xC001D00D</code>.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Version'''
| [[#Version|See below]] for a list of possible version numbers.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Area Count'''
| Number of areas contained in this world. Always 1 in DKCR.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Cinematic Skip Count'''
| Count of skippable cinematics.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Cinematic Skip Count''
| '''Cinematic Skip Array'''
| Array describing all skippable cinematics in the world. Points to Cinematic Skip SpecialFunctions (MP1) or cameras with cinematic skip enabled (MP2+).
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Memory Relay Count'''
| Count of Memory Relay instances.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Memory Relay Count''
| '''Memory Relay Array'''
| Array describing all Memory Relays in the world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer Toggle Count'''
| Count of layers that can be toggled on/off from this world.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Layer Toggle|Layer Toggle]]
| ''Layer Toggle Count''
| '''Layer Toggle Array'''
| Array specifying every layer toggleable from this world (referenced by a ScriptLayerController). The layers specified can be in other worlds.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Door Count'''
| Count of DoorArea/Door instances.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Door Count''
| '''Door Array'''
| Array describing all DoorArea/Door instances in the world.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Scannable Object Count'''
| Count of scannable objects in the next array.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Scannable Object|Scannable Object]]
| ''Scannable Object Count''
| '''Scannable Object Array'''
| Array describing every scannable object in this world.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''System State Env Var Count'''
| Count of system state env vars modified from this world.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Environment Variable|Environment Variable]]
| ''System State Env Var Count''
| '''System State Env Var Array'''
| Array of env vars affecting the entire system.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Game State Env Var Count'''
| Count of game state env vars modified from this world.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Environment Variable|Environment Variable]]
| ''Game State Env Var Count''
| '''Game State Env Var Array'''
| Array of env vars affecting only this save slot.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Unmappable Object Count'''
| Count of unmappable objects in the world.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Unmappable Object Count''
| '''Unmappable Object Array'''
| Array describing every instance that can be removed from the map. Primarily Translator Door Location SpecialFunctions in MP2 and Pickups in MP3.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Puzzle Piece Count'''
| Count of Puzzle Piece Pickups in this world. (This value also controls the level puzzle piece count that displays on the HUD ingame.)
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Puzzle Piece Count''
| '''Puzzle Piece Array'''
| Array describing all Puzzle Piece Pickups.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| colspan=8 {{unknown|End of file}}
|}

=== Version ===

Each revision of the SAVW format has a unique version number, which corresponds to the following games:

{| class="wikitable"
! Version
! Game
|-
| 0x3
| Metroid Prime
|-
| 0x5
| Metroid Prime 2: Echoes
|-
| 0x6
| Metroid Prime 3: Corruption
|-
| 0x8
| Donkey Kong Country Returns
|}

=== Saved State Descriptor ===

In Metroid Prime 1 and 2, saved state values were referenced only via the instance ID of the object that the state is for. In Prime 3 and DKCR, a 128-bit [[GUID]] was introduced that handles references to save file data, and is stored in the file in conjunction with the instance IDs.

{| class="wikitable"
! Type
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| [[GUID]]
| '''GUID'''
| ID of this saved state.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| u32
| '''Instance ID'''
| Instance ID of the object that uses this saved state.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=7 {{unknown|End of descriptor}}
|}

=== Layer Toggle ===

{| class="wikitable"
! Type
! Name
! Notes
|-
| u32
| '''Area ID'''
| Internal area ID (not the MREA ID).
|-
| u32
| '''Layer Index'''
| Index of the layer that can be toggled.
|-
| colspan=3 {{unknown|End of layer}}
|}

=== Scannable Object ===

{| class="wikitable"
! Type
! Name
! Notes
|-
| Asset ID
| '''SCAN Asset ID'''
| Asset ID of a [[SCAN (Metroid Prime)|SCAN]] file.
|-
| u32
| '''Logbook Category'''
| Enum describing which logbook category this scan is part of. Always 0 in MP2 and MP3. See below for possible values for MP1.
|-
| colspan=3 {{unknown|End of scan}}
|}

Possible logbook category values (MP1 only):

{| class="wikitable"
! ID
! Category
|-
| 0
| Non-Logbook
|-
| 1
| Space Pirate Data
|-
| 2
| Chozo Lore
|-
| 3
| Creatures
|-
| 4
| Research
|-
| 5
| Artifacts
|}

=== Environment Variable ===

{| class="wikitable"
! Type
! Name
! Notes
|-
| string
| '''Variable Name'''
| Name of the environment variable as a zero-terminated string.
|-
| u32
| {{unknown|Unknown}}
| Always 0?
|-
| u32
| {{unknown|Unknown}}
| Always 1?
|-
| u32
| {{unknown|Unknown}}
| Always 0?
|-
| colspan=3 {{unknown|End of environment variable}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2 Demo]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3 Prototype]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

MLVL (File Format)

2019-02-05T07:16:46Z

Aruki: /* Format */

The '''MLVL format''' defines worlds in the Metroid Prime trilogy and Donkey Kong Country Returns. While the [[MREA (File Format)|MREA format]] defines individual areas, the MLVL is what links together all the areas to create a single cohesive world.

{{research|minor|There's a couple unknown values in this format, but they all seem to have constant values.}}

__TOC__

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| u32
| 1
| '''Magic'''
| Always <code>0xDEAFBABE</code>
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Version'''
| [[#Version|See below]]
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''World Name ID'''
| [[STRG (File Format)|STRG]] file for the world name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Dark World Name ID'''
| [[STRG (File Format)|STRG]] file for the Dark World name.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Temple Key World Index'''
| Controls which temple key icons appear on the map screen. Appears in Prime 3 but always 0.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| bool
| 1
| '''Has Time Attack'''
| Indicates whether this world has a Time Attack mode. '''If false, the next five values are not present.'''
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Level Number'''
| String of the world/level number; for example, "1-1". Purpose unknown.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Bronze Time'''
| Target time for a bronze medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Silver Time'''
| Target time for a silver medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Gold Time'''
| Target time for a gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Shiny Gold Time'''
| Target time for a shiny gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| Asset ID ([[SAVW (File Format)|SAVW]])
| 1
| '''World Save Info ID'''
| Asset ID for this world's [[SAVW (File Format)|SAVW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[CMDL (File Format)|CMDL]])
| 1
| '''Default Skybox ID'''
| [[CMDL (File Format)|CMDL]] file for this world's default skybox model. This can be overridden per-area by AreaAttributes objects.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Memory Relay Count'''
| Count of all outgoing connections from Memory Relay instances in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Memory Relay|Memory Relay]]
| ''Memory Relay Count''
| '''Memory Relay Array'''
| Array describing all outgoing Memory Relay connections in this world. Memory Relays connected to multiple objects are listed multiple times.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Count of areas in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 1?
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Area|Area]]
| ''Area Count''
| '''Area Array'''
| Array defining all areas that appear in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MAPW (File Format)|MAPW]])
| 1
| '''World Map ID'''
| ID of this world's [[MAPW (File Format)|MAPW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u8
| 1
| {{unknown|Unknown}}
| This is presumably the same unknown value as at the beginning of the [[Scriptable Layers (Metroid Prime)|SCLY]] format. Always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Script Instance Count'''
| The MLVL format embeds a script layer. This script layer is used in the MP1 demo for storing Dock instances, but it's unused in all retail builds, so this is always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Audio Group Count'''
| Count of all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Audio Group|Audio Group]]
| ''Audio Group Count''
| '''Audio Group Array'''
| Array describing all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| string
| 1
| {{unknown|Unknown}}
| Always empty, so the only value that ever appears here is the terminating 0.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Will be equal to the earlier area count.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Area Layer Flags|Area Layer Flags]]
| ''Area Count''
| '''Area Layer Flags'''
| This array initializes the default active state for all script layers in each area.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer Name Count'''
| Count of layer names in the next array.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| string
| ''Layer Name Count''
| '''Layer Name Array'''
| Array of all layer names in the world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer GUID Count'''
| Count of layer GUIDs in the next array.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| [[GUID]]
| ''Layer GUID Count''
| '''Layer GUID Array'''
| Array of GUIDs for each layer. These GUIDs are responsible for storing the layer's ''Active'' state in the save file and are referenced by ScriptLayerController objects.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Area Count'''
| Identical to the previous two area counts.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| ''Area Count''
| '''Area Layer Name Offset Array'''
| Each value is an offset into the layer name array and points to where the layer names for each area begins.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of file}}
|}

=== Version ===

These are the known version numbers:

{| class="wikitable"
! 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 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.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Memory Relay Instance ID'''
| Instance ID of the sender Memory Relay.
|-
| 0x4
| u32
| '''Target Instance ID'''
| Instance ID of the receiver object.
|-
| 0x8
| u16
| '''Message'''
| Script message sent to the receiver object.
|-
| 0x10
| bool
| '''Active'''
| Whether this Memory Relay object is active by default; almost always 0.
|-
| 0x11
| colspan=3 {{unknown|End of Memory Relay connection}}
|}

=== Area ===

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Area Name ID'''
| [[STRG (File Format)|STRG]] ID for the area name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 12
| '''Area Transform'''
| Area's transform matrix. Most area data is pre-transformed, but there are a few things that need to be transformed by this matrix.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 6
| '''Area Bounding Box'''
| This is the bounding box of the area's collision mesh and is equivalent to the bounding box found in the [[MREA (File Format)|MREA]] collision section.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MREA (File Format)|MREA]])
| 1
| '''Area MREA ID'''
| ID of this area's [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID
| 1
| '''Internal Area ID'''
| Doesn't actually refer to an asset, but has the same length as an asset ID. This ID is used internally by some things to refer to this area, such as Script Layer Controllers.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Attached Area Count'''
| Count of areas attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u16
| ''Attached Area Count''
| '''Attached Area Index Array'''
| Array of area indices attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Dependencies|Area Dependencies]]
| 1
| '''Dependencies'''
| Asset dependencies in this area. See below for details. Starting in Prime 3, this section has been moved inside the [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Dock Count'''
| Count of Dock instances in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Dock|Dock]]
| ''Dock Count''
| '''Dock Array'''
| Array describing all docks in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Module Dependencies|Area Module Dependencies]]
| 1
| '''Module Dependencies'''
| REL module dependencies in this area. See below for details. The equivalent section in Prime 3 and DKCR describing RSO modules has been moved inside the [[MREA (File Format)|MREA]] format.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 0?
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Internal Area Name'''
| Internal name of this area. This name will be used ingame on the map screen if no ''Area Name ID'' is specified, prefixed with "!!".
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of area}}
|}

==== 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 Format)|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):

* [[SCAN (File Format)|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.
* [[ANCS (File Format)|ANCS]] per-character dependencies for PlayerActor script instances are not included; this allows the game to avoid keeping assets in memory for suits that the player doesn't have. The exception is the Empty Suit character (character index 5 in MP1, and index 3 in MP2), which is a low-memory-overhead character that allows for the list to include all common assets that are stored in the file per-character (such as particle effects).
* 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 (File Format)|MREA]] format.

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Dependency Count'''
| Count of dependencies.
|-
| [[#Dependency|Dependency]]
| ''Dependency Count''
| '''Dependency Array'''
| Array of all asset dependencies in this area.
|-
| u32
| 1
| '''Dependency Offset Count'''
| Count of dependency offsets. This will be equal to the area script layer count + 1.
|-
| u32
| ''Dependency Offset Count''
| '''Dependency Offset Array'''
| Array of offsets into the dependency array. There is one offset per script layer, with the offset referring to the index of that layer's first dependency. There is a final extra offset that points to area dependencies that are not layer-specific.
|}

===== Dependency =====

{| class="wikitable"
! Offset
! Type
! Count
! Name
|-
| 0x0
| Asset ID
| 1
| '''Dependency Asset ID'''
|-
| 0x4
| char
| 4
| '''Dependency Asset Type'''
|}

==== Dock ====

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Connecting Dock Count'''
| Count of docks connecting to this one. Typically 1 (but there are docks in Prime 3 that connect to multiple areas).
|-
| [[#Connecting Dock|Connecting Dock]]
| ''Connecting Dock Count''
| '''Connecting Dock Array'''
| Array describing all docks connected to this one.
|-
| u32
| 1
| '''Dock Coordinate Count'''
| Array of dock coordinates in the next array.
|-
| Vector3
| ''Dock Coordinate Count''
| '''Dock Coordinates'''
| Exact purpose/function of this is not known yet.
|}

===== Connecting Dock =====

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Area Index'''
| Index of the area this dock is in.
|-
| 0x4
| u32
| '''Dock Index'''
| Index of this dock within its area.
|}

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''REL Module Count'''
| Count of REL modules in the next array.
|-
| string
| ''REL Module Count''
| '''REL Module Array'''
| REL modules used by this area. Each array entry is the filename of a .REL module.
|-
| u32
| 1
| '''REL Offset Count'''
| Count of REL offsets in the next array. Should be equal to the area script layer count * 2.
|-
| u32
| ''REL Offset Count''
| '''REL Offset Array'''
| Array of offsets into the ''REL Module Array''. There are two offsets per script layer, with the first one being that layer's start index and the second one effectively being that layer's end index.
|}

=== Audio Group ===

This structure is only present in Prime 1 and describes an [[AGSC (File Format)|AGSC]] file being used in this world.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Group ID'''
| Group ID for this audio group. This is the same value that can be found in the Project chunk in the referenced [[AGSC (File Format)|AGSC]] file.
|-
| 0x4
| Asset ID ([[AGSC (File Format)|AGSC]])
| '''AGSC ID'''
| The [[AGSC (File Format)|AGSC]] file for this audio group.
|-
| 0x8
| colspan=3 {{unknown|End of audio group definition}}
|}

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

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Layer Count'''
| Count of layers in this area.
|-
| 0x4
| u64
| '''Layer Flags'''
| See above for a description of how these work.
|-
| 0x8
| colspan=3 {{unknown|End of area layer flags}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

MLVL (File Format)

2019-02-05T07:16:24Z

Aruki: /* Format */

The '''MLVL format''' defines worlds in the Metroid Prime trilogy and Donkey Kong Country Returns. While the [[MREA (File Format)|MREA format]] defines individual areas, the MLVL is what links together all the areas to create a single cohesive world.

{{research|minor|There's a couple unknown values in this format, but they all seem to have constant values.}}

__TOC__

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| u32
| 1
| '''Magic'''
| Always <code>0xDEAFBABE</code>
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Version'''
| [[#Version|See below]]
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''World Name ID'''
| [[STRG (File Format)|STRG]] file for the world name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Dark World Name ID'''
| [[STRG (File Format)|STRG]] file for the Dark World name.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Temple Key World Index'''
| Controls which temple key icons appear on the map screen. Appears in Prime 3 but always 0.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| bool
| 1
| '''Has Time Attack'''
| Indicates whether this world has a Time Attack mode. '''If false, the next five values are not present.'''
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Level Number'''
| String of the world/level number; for example, "1-1". Purpose unknown.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Bronze Time'''
| Target time for a bronze medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Silver Time'''
| Target time for a silver medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Gold Time'''
| Target time for a gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| float
| 1
| '''Time Attack Shiny Gold Time'''
| Target time for a shiny gold medal in Time Attack.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| Asset ID ([[SAVW (File Format)|SAVW]])
| 1
| '''World Save Info ID'''
| Asset ID for this world's [[SAVW (File Format)|SAVW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[CMDL (File Format)|CMDL]])
| 1
| '''Default Skybox ID'''
| [[CMDL (File Format)|CMDL]] file for this world's default skybox model. This can be overridden per-area by AreaAttributes objects.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Memory Relay Count'''
| Count of all outgoing connections from Memory Relay instances in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Memory Relay|Memory Relay]]
| ''Memory Relay Count''
| '''Memory Relay Array'''
| Array describing all outgoing Memory Relay connections in this world. Memory Relays connected to multiple objects are listed multiple times.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Count of areas in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 1?
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Area|Area]]
| ''Area Count''
| '''Area Array'''
| Array defining all areas that appear in this world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MAPW (File Format)|MAPW]])
| 1
| '''World Map ID'''
| ID of this world's [[MAPW (File Format)|MAPW]] file.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u8
| 1
| {{unknown|Unknown}}
| This is presumably the same unknown value as at the beginning of the [[Scriptable Layers (Metroid Prime)|SCLY]] format. Always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Script Instance Count'''
| The MLVL format embeds a script layer. This script layer is used in the MP1 demo for storing Dock instances, but it's unused in all retail builds, so this is always 0.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Audio Group Count'''
| Count of all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Audio Group|Audio Group]]
| ''Audio Group Count''
| '''Audio Group Array'''
| Array describing all audio groups used in this world.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| string
| 1
| {{unknown|Unknown}}
| Always empty, so the only value that ever appears here is the terminating 0.
| {{check}}
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Area Count'''
| Will be equal to the earlier area count.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Area Layer Flags|Area Layer Flags]]
| ''Area Count''
| '''Area Layer Flags'''
| This array initializes the default active state for all script layers in each area.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer Name Count'''
| Count of layer names in the next array.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| string
| ''Layer Name Count''
| '''Layer Name Array'''
| Array of all layer names in the world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer State ID Count'''
| Count of layer state IDs in the next array.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| [[GUID]]
| ''Layer GUID Count''
| '''Layer GUID Array'''
| Array of GUIDs for each layer. These GUIDs are responsible for storing the layer's active state in the save file and are referenced by ScriptLayerController objects.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Area Count'''
| Identical to the previous two area counts.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| ''Area Count''
| '''Area Layer Name Offset Array'''
| Each value is an offset into the layer name array and points to where the layer names for each area begins.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of file}}
|}

=== Version ===

These are the known version numbers:

{| class="wikitable"
! 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 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.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Memory Relay Instance ID'''
| Instance ID of the sender Memory Relay.
|-
| 0x4
| u32
| '''Target Instance ID'''
| Instance ID of the receiver object.
|-
| 0x8
| u16
| '''Message'''
| Script message sent to the receiver object.
|-
| 0x10
| bool
| '''Active'''
| Whether this Memory Relay object is active by default; almost always 0.
|-
| 0x11
| colspan=3 {{unknown|End of Memory Relay connection}}
|}

=== Area ===

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| Asset ID ([[STRG (File Format)|STRG]])
| 1
| '''Area Name ID'''
| [[STRG (File Format)|STRG]] ID for the area name.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 12
| '''Area Transform'''
| Area's transform matrix. Most area data is pre-transformed, but there are a few things that need to be transformed by this matrix.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| float
| 6
| '''Area Bounding Box'''
| This is the bounding box of the area's collision mesh and is equivalent to the bounding box found in the [[MREA (File Format)|MREA]] collision section.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID ([[MREA (File Format)|MREA]])
| 1
| '''Area MREA ID'''
| ID of this area's [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| Asset ID
| 1
| '''Internal Area ID'''
| Doesn't actually refer to an asset, but has the same length as an asset ID. This ID is used internally by some things to refer to this area, such as Script Layer Controllers.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Attached Area Count'''
| Count of areas attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u16
| ''Attached Area Count''
| '''Attached Area Index Array'''
| Array of area indices attached to this one.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Dependencies|Area Dependencies]]
| 1
| '''Dependencies'''
| Asset dependencies in this area. See below for details. Starting in Prime 3, this section has been moved inside the [[MREA (File Format)|MREA]] file.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Dock Count'''
| Count of Dock instances in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Dock|Dock]]
| ''Dock Count''
| '''Dock Array'''
| Array describing all docks in this area.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Area Module Dependencies|Area Module Dependencies]]
| 1
| '''Module Dependencies'''
| REL module dependencies in this area. See below for details. The equivalent section in Prime 3 and DKCR describing RSO modules has been moved inside the [[MREA (File Format)|MREA]] format.
| {{nocheck}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| {{unknown|Unknown}}
| Always 0?
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| string
| 1
| '''Internal Area Name'''
| Internal name of this area. This name will be used ingame on the map screen if no ''Area Name ID'' is specified, prefixed with "!!".
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=8 {{unknown|End of area}}
|}

==== 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 Format)|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):

* [[SCAN (File Format)|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.
* [[ANCS (File Format)|ANCS]] per-character dependencies for PlayerActor script instances are not included; this allows the game to avoid keeping assets in memory for suits that the player doesn't have. The exception is the Empty Suit character (character index 5 in MP1, and index 3 in MP2), which is a low-memory-overhead character that allows for the list to include all common assets that are stored in the file per-character (such as particle effects).
* 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 (File Format)|MREA]] format.

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Dependency Count'''
| Count of dependencies.
|-
| [[#Dependency|Dependency]]
| ''Dependency Count''
| '''Dependency Array'''
| Array of all asset dependencies in this area.
|-
| u32
| 1
| '''Dependency Offset Count'''
| Count of dependency offsets. This will be equal to the area script layer count + 1.
|-
| u32
| ''Dependency Offset Count''
| '''Dependency Offset Array'''
| Array of offsets into the dependency array. There is one offset per script layer, with the offset referring to the index of that layer's first dependency. There is a final extra offset that points to area dependencies that are not layer-specific.
|}

===== Dependency =====

{| class="wikitable"
! Offset
! Type
! Count
! Name
|-
| 0x0
| Asset ID
| 1
| '''Dependency Asset ID'''
|-
| 0x4
| char
| 4
| '''Dependency Asset Type'''
|}

==== Dock ====

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Connecting Dock Count'''
| Count of docks connecting to this one. Typically 1 (but there are docks in Prime 3 that connect to multiple areas).
|-
| [[#Connecting Dock|Connecting Dock]]
| ''Connecting Dock Count''
| '''Connecting Dock Array'''
| Array describing all docks connected to this one.
|-
| u32
| 1
| '''Dock Coordinate Count'''
| Array of dock coordinates in the next array.
|-
| Vector3
| ''Dock Coordinate Count''
| '''Dock Coordinates'''
| Exact purpose/function of this is not known yet.
|}

===== Connecting Dock =====

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Area Index'''
| Index of the area this dock is in.
|-
| 0x4
| u32
| '''Dock Index'''
| Index of this dock within its area.
|}

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

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''REL Module Count'''
| Count of REL modules in the next array.
|-
| string
| ''REL Module Count''
| '''REL Module Array'''
| REL modules used by this area. Each array entry is the filename of a .REL module.
|-
| u32
| 1
| '''REL Offset Count'''
| Count of REL offsets in the next array. Should be equal to the area script layer count * 2.
|-
| u32
| ''REL Offset Count''
| '''REL Offset Array'''
| Array of offsets into the ''REL Module Array''. There are two offsets per script layer, with the first one being that layer's start index and the second one effectively being that layer's end index.
|}

=== Audio Group ===

This structure is only present in Prime 1 and describes an [[AGSC (File Format)|AGSC]] file being used in this world.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Group ID'''
| Group ID for this audio group. This is the same value that can be found in the Project chunk in the referenced [[AGSC (File Format)|AGSC]] file.
|-
| 0x4
| Asset ID ([[AGSC (File Format)|AGSC]])
| '''AGSC ID'''
| The [[AGSC (File Format)|AGSC]] file for this audio group.
|-
| 0x8
| colspan=3 {{unknown|End of audio group definition}}
|}

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

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Layer Count'''
| Count of layers in this area.
|-
| 0x4
| u64
| '''Layer Flags'''
| See above for a description of how these work.
|-
| 0x8
| colspan=3 {{unknown|End of area layer flags}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

GUID

2019-02-05T07:15:40Z

Aruki:

A '''GUID''' is a 128-bit ID used to uniquely identify an object. They are used in [[Metroid Prime 3: Corruption]] and [[Donkey Kong Country Returns]] to uniquely identify a value stored in the save file. They are also commonly used in [[Donkey Kong Country: Tropical Freeze]] as identifiers for all sorts of objects.

== MP3/DKCR ==

Script objects that need to preserve data between play sessions will have a GUID listed as a property (with property ID 0x16D9A75D). That ID is also stored in the [[SAVW (File Format)|SAVW]] file and associated with the object's instance ID. At runtime, when the object is loaded it uses the GUID to look up the value of the parameter and then updates itself accordingly. The GUIDs declared from the SAVW file are only valid within the world the SAVW file is associated with; reusing the same GUID from a different world is treated as a separate value.

GUIDs are also used by script layers to track whether the layer is active. The GUIDs associated with each layer can be found in the [[MLVL (File Format)|MLVL]] file. Layer GUIDs are different from the other IDs in that they are valid across the entire game, when referenced from any world.

GUIDs are used by the following objects:

{| class="wikitable"
! Object
! Usage
! MP3
! DKCR
|-
| Script Layer
| Tracks whether the layer is active or not.
| {{check}}
| {{check}}
|-
| CinematicCamera
| Tracks whether the cutscene has been watched before. If so, cinematic skip can be enabled. (CinematicCameras that don't have cinematic skip enabled don't have a GUID.)
| {{check}}
| {{check}}
|-
| MemoryRelay
| Tracks whether the relay is active.
| {{check}}
| {{check}}
|-
| Door
| Tracks whether the door has been opened at some point during gameplay. This is used to change the door color on the map.
| {{check}}
| {{nocheck}}
|-
| Pickup
| Tracks whether the pickup has been acquired before.
* In MP3, this is used to remove upgrades and expansions that the player has already collected from the map.
* In DKCR, this is used to grey out puzzle pieces that the player has already collected and prevent them from being collecting a second time.
| {{check}}
| {{check}}
|}

[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

Saved State ID

2019-02-05T07:13:23Z

Aruki: Aruki moved page Saved State ID to GUID

#REDIRECT [[GUID]]

GUID

2019-02-05T07:13:22Z

Aruki: Aruki moved page Saved State ID to GUID

A '''Saved State ID''' (unofficial name) is a 128-bit ID used in [[Metroid Prime 3: Corruption]] and [[Donkey Kong Country Returns]]. They're used to uniquely identify a value stored in the save file. Script objects that need to preserve data between play sessions will have one of these IDs listed as a property (with property ID 0x16D9A75D). That ID is also stored in the [[SAVW (File Format)|SAVW]] file and associated with the object's instance ID. At runtime, when the object is loaded it uses the ID to look up the value of the parameter and then updates itself accordingly. The IDs declared from the SAVW file are only valid within the world the SAVW file is associated with; reusing the same ID from a different world is treated as a separate value.

Saved State IDs are also used by script layers to track whether the layer is active. The IDs associated with each layer can be found in the [[MLVL (File Format)|MLVL]] file. Layer state IDs are different from the other IDs in that they are valid across the entire game, when referenced from any world.

Saved State IDs are used by the following objects:

{| class="wikitable"
! Object
! Usage
! MP3
! DKCR
|-
| Script Layer
| Tracks whether the layer is active or not.
| {{check}}
| {{check}}
|-
| CinematicCamera
| Tracks whether the cutscene has been watched before. If so, cinematic skip can be enabled. (CinematicCameras that don't have cinematic skip enabled don't have a state ID.)
| {{check}}
| {{check}}
|-
| MemoryRelay
| Tracks whether the relay is active.
| {{check}}
| {{check}}
|-
| Door
| Tracks whether the door has been opened at some point during gameplay. This is used to change the door color on the map.
| {{check}}
| {{nocheck}}
|-
| Pickup
| Tracks whether the pickup has been acquired before.
* In MP3, this is used to remove upgrades and expansions that the player has already collected from the map.
* In DKCR, this is used to grey out puzzle pieces that the player has already collected and prevent them from being collecting a second time.
| {{check}}
| {{check}}
|}

[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

SCAN (Metroid Prime)

2019-01-13T16:21:50Z

Aruki: /* Logbook Category */

''This article is for the SCAN format from Metroid Prime. For other revisions of this format, see [[SCAN (File Format)]].''

The '''SCAN file format''' describes scannable objects. It is a relatively simple format and has a static size.

__TOC__

== Format ==

The SCAN format is very simple; it has a header with data that contains general settings related to the scan, and then four structs defining how the scan images work. Even if a scan doesn't use four images, there are always four image structs, which means that the SCAN format has a static size; every SCAN file is 0x89 bytes (or 0xA0 bytes padded).

=== Header ===

The header is rather simple, and consists of the following:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Version'''; 3 for the demo, 5 for the final
|-
| 0x4
| 4
| '''Magic'''; always 0x0BADBEEF
|-
| 0x8
| 4
| '''[[FRME (File Format)|FRME]] ID'''
|-
| 0xC
| 4
| '''Scan text [[STRG (File Format)|STRG]] ID'''
|-
| 0x10
| 4
| '''Scan Speed Flag'''; 0 = normal fast scan, 1 = slower scan (usually found in boss fights)
|-
| 0x14
| 4
| '''Logbook Category'''; see below
|-
| 0x18
| 1
| '''Scan Icon Flag'''; 0 = orange icon, 1 = red icon
|-
| 0x19
| colspan=2 {{unknown|End of header}}
|}

==== Logbook Category ====

There are six possible values:

{| class="wikitable"
! ID
! Category
|-
| 0
| Not a logbook scan
|-
| 1
| Space Pirate Data
|-
| 2
| Chozo Lore
|-
| 3
| Creatures
|-
| 4
| Research
|-
| 5
| Artifacts
|}

=== Scan Images ===
Following the header is an array of four structs that contain settings for up to four scan images. Although there can be anywhere from 0 to 4 scan images attached to a scan, there are always four scan image entries here. Entries that aren't used have their TXTR ID set to 0xFFFFFFFF, with the rest of the settings mostly left at defaults. They follow this format:

{| class="wikitable"
! Offset
! Size
! Type
! Description
|-
| 0x0
| 4
| long
| '''[[TXTR (Metroid Prime)|TXTR]] ID'''
|-
| 0x4
| 4
| float
| '''Appearance %'''; image will appear when the scan is this% complete. Should range from 0 to 1.
|-
| 0x8
| 4
| long
| '''Image Position'''; See below.
|-
| 0xC
| 4
| long
| '''Width'''; 0 = no animation
|-
| 0x10
| 4
| long
| '''Height'''; 0 = no animation
|-
| 0x14
| 4
| float
| '''Interval'''; 0.0 = no animation
|-
| 0x18
| 4
| float
| '''Fade Duration'''; 0.0 = no fade
|-
| 0x1C
| colspan=3 {{unknown|End of entry}}
|}

==== Image Position ====

There are 20 possible values for the scan image's position; there are ten for the left side, and ten for the right:
{| class="wikitable"
! Value
! Size
! Position
! FRME_ScanHud Widget
|-
| 0x00
| 1/4
| Top-left corner
| imagepane_pane0
|-
| 0x01
| 1/4
| Upper-middle-left
| imagepane_pane1
|-
| 0x02
| 1/4
| Lower-middle-left
| imagepane_pane2
|-
| 0x03
| 1/4
| Bottom-left corner
| imagepane_pane3
|-
| 0x04
| 1/2
| Top-left corner
| imagepane_pane01
|-
| 0x05
| 1/2
| Middle-left
| imagepane_pane12
|-
| 0x06
| 1/2
| Bottom-left corner
| imagepane_pane23
|-
| 0x07
| 3/4
| Top-left corner
| imagepane_pane012
|-
| 0x08
| 3/4
| Bottom-left corner
| imagepane_pane123
|-
| 0x09
| 1
| Left side
| imagepane_pane0123
|-
| 0x0A
| 1/4
| Top-right corner
| imagepane_pane4
|-
| 0x0B
| 1/4
| Upper-middle-right
| imagepane_pane5
|-
| 0x0C
| 1/4
| Lower-middle-right
| imagepane_pane6
|-
| 0x0D
| 1/4
| Bottom-right corner
| imagepane_pane7
|-
| 0x0E
| 1/2
| Top-right corner
| imagepane_pane45
|-
| 0x0F
| 1/2
| Middle-right
| imagepane_pane56
|-
| 0x10
| 1/2
| Bottom-right corner
| imagepane_pane67
|-
| 0x11
| 3/4
| Top-right corner
| imagepane_pane456
|-
| 0x12
| 3/4
| Bottom-right corner
| imagepane_pane567
|-
| 0x13
| 1
| Right side
| imagepane_pane4567
|-
|}

<gallery mode=packed heights=200px>
File:Scan_offsets_1.png|Image positions 0x00, 0x01, and 0x02
File:Scan_offsets_3.png|Image positions for 0x04, 0x06, 0x0E, and 0x10
File:Scan_offset_101.png|Image positions for 0x03, 0x05, and 0x0F. Note that 0x03 appears only for this scan (Omega Pirate's projectiles) and no others.
File:Scan_offsets_10.png|Image positions for 0x09 and 0x13
File:Scan_position_10000.png|This unused Chozo Elder scan (hacked onto Parasite Queen) shows image positions 0x0A and 0x0D. This scan is the only one where these positions are used.
File:Scan_position_99.png|Image positions for 0x0B and 0x0C (unused)
File:Scan_offset_11.png|Image positions for 0x07 and 0x11 (unused)
File:Scan_offset_12.png|Image positions for 0x08 and 0x12 (unused)
</gallery>

==== Fly In Behavior ====

The first scan image to appear (based on the appearance percent value) will "fly in" from the side of the screen toward the center. The remaining images will "fade in" without moving. The only exception to this is when the first image to appear is a "blank" image with no associated [[TXTR (Metroid Prime)|TXTR]]. In this case, no image will fly in (i.e., all images will fade in).

==== Scan Animations ====
[[Image:AnimatedscanFinal.gif|thumb|The terminal with an animated scan image in the Map Facility.]]
An extremely small number of scans display animated images in Metroid Prime. In the final version of the game, only a terminal in the Map Facility displays an animated image. In the demo version of the game, the aforementioned terminal scan and the Parasite Queen scan both display animated images. For most SCAN files, the last 32 bits of the scan image entry are zeroed out, but for the animated scans, these 32 bits have actual values in them. Strangely, the terminal directly to the left of the animated terminal in the Map Facility also has non-zero values for these 32 bits, even though it does not display any animated images.

[[Category:File Formats]]
[[Category:Metroid Prime]]

SAVW (File Format)

2019-01-13T16:14:25Z

Aruki: /* Scannable Object */

The '''SAVW format''' describes save data in the Metroid Prime series and Donkey Kong Country Returns. It allows any data used by the game's script data that needs to be preserved between play sessions to be saved and retrieved from the save file without the executable having to know anything about it. This is used for, for instance, saving whether a particular MemoryRelay has been activated, or whether a specific layer has been toggled on.

__TOC__

== Format ==

The format is basically just a series of arrays. The structure remains more or less the same across every game, just with arrays being added or removed. The main difference between formats is that starting in Metroid Prime 3, the engine stores references to saved variables through a combination of a 128-bit state ID and an instance ID instead of implicitly associating them via instance IDs alone. The state ID is mirrored in another file (usually on the object via a property).

{| class="wikitable"
! Type
! Count
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| u32
| 1
| '''Magic'''
| Always <code>0xC001D00D</code>.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Version'''
| [[#Version|See below]] for a list of possible version numbers.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Area Count'''
| Number of areas contained in this world. Always 1 in DKCR.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Cinematic Skip Count'''
| Count of skippable cinematics.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Cinematic Skip Count''
| '''Cinematic Skip Array'''
| Array describing all skippable cinematics in the world. Points to Cinematic Skip SpecialFunctions (MP1) or cameras with cinematic skip enabled (MP2+).
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Memory Relay Count'''
| Count of Memory Relay instances.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Memory Relay Count''
| '''Memory Relay Array'''
| Array describing all Memory Relays in the world.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Layer Toggle Count'''
| Count of layers that can be toggled on/off from this world.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| [[#Layer Toggle|Layer Toggle]]
| ''Layer Toggle Count''
| '''Layer Toggle Array'''
| Array specifying every layer toggleable from this world (referenced by a ScriptLayerController). The layers specified can be in other worlds.
| {{check}}
| {{check}}
| {{nocheck}}
| {{nocheck}}
|-
| u32
| 1
| '''Door Count'''
| Count of DoorArea/Door instances.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Door Count''
| '''Door Array'''
| Array describing all DoorArea/Door instances in the world.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Scannable Object Count'''
| Count of scannable objects in the next array.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Scannable Object|Scannable Object]]
| ''Scannable Object Count''
| '''Scannable Object Array'''
| Array describing every scannable object in this world.
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''System State Env Var Count'''
| Count of system state env vars modified from this world.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Environment Variable|Environment Variable]]
| ''System State Env Var Count''
| '''System State Env Var Array'''
| Array of env vars affecting the entire system.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Game State Env Var Count'''
| Count of game state env vars modified from this world.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| [[#Environment Variable|Environment Variable]]
| ''Game State Env Var Count''
| '''Game State Env Var Array'''
| Array of env vars affecting only this save slot.
| {{nocheck}}
| {{check}}
| {{check}}
| {{check}}
|-
| u32
| 1
| '''Unmappable Object Count'''
| Count of unmappable objects in the world.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Unmappable Object Count''
| '''Unmappable Object Array'''
| Array describing every instance that can be removed from the map. Primarily Translator Door Location SpecialFunctions in MP2 and Pickups in MP3.
| {{nocheck}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| u32
| 1
| '''Puzzle Piece Count'''
| Count of Puzzle Piece Pickups in this world. (This value also controls the level puzzle piece count that displays on the HUD ingame.)
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| [[#Saved State Descriptor|Saved State Descriptor]]
| ''Puzzle Piece Count''
| '''Puzzle Piece Array'''
| Array describing all Puzzle Piece Pickups.
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| colspan=8 {{unknown|End of file}}
|}

=== Version ===

Each revision of the SAVW format has a unique version number, which corresponds to the following games:

{| class="wikitable"
! Version
! Game
|-
| 0x3
| Metroid Prime
|-
| 0x5
| Metroid Prime 2: Echoes
|-
| 0x6
| Metroid Prime 3: Corruption
|-
| 0x8
| Donkey Kong Country Returns
|}

=== Saved State Descriptor ===

In Metroid Prime 1 and 2, saved state values were referenced only via the instance ID of the object that the state is for. In Prime 3 and DKCR, a 128-bit [[Saved State ID]] was introduced that handles references to save file data, and is stored in the file in conjunction with the instance IDs.

{| class="wikitable"
! Type
! Name
! Notes
! MP1
! MP2
! MP3
! DKCR
|-
| [[Saved State ID]]
| '''Saved State ID'''
| ID of this saved state.
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| u32
| '''Instance ID'''
| Instance ID of the object that uses this saved state.
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| colspan=7 {{unknown|End of descriptor}}
|}

=== Layer Toggle ===

{| class="wikitable"
! Type
! Name
! Notes
|-
| u32
| '''Area ID'''
| Internal area ID (not the MREA ID).
|-
| u32
| '''Layer Index'''
| Index of the layer that can be toggled.
|-
| colspan=3 {{unknown|End of layer}}
|}

=== Scannable Object ===

{| class="wikitable"
! Type
! Name
! Notes
|-
| Asset ID
| '''SCAN Asset ID'''
| Asset ID of a [[SCAN (Metroid Prime)|SCAN]] file.
|-
| u32
| '''Logbook Category'''
| Enum describing which logbook category this scan is part of. Always 0 in MP2 and MP3. See below for possible values for MP1.
|-
| colspan=3 {{unknown|End of scan}}
|}

Possible logbook category values (MP1 only):

{| class="wikitable"
! ID
! Category
|-
| 0
| Non-Logbook
|-
| 1
| Space Pirate Data
|-
| 2
| Chozo Lore
|-
| 3
| Creatures
|-
| 4
| Research
|-
| 5
| Artifacts
|}

=== Environment Variable ===

{| class="wikitable"
! Type
! Name
! Notes
|-
| string
| '''Variable Name'''
| Name of the environment variable as a zero-terminated string.
|-
| u32
| {{unknown|Unknown}}
| Always 0?
|-
| u32
| {{unknown|Unknown}}
| Always 1?
|-
| u32
| {{unknown|Unknown}}
| Always 0?
|-
| colspan=3 {{unknown|End of environment variable}}
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2 Demo]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3 Prototype]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

PAK (Metroid Prime)

2018-06-14T19:54:42Z

Aruki: /* Named Resources */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int16
| '''Version Number Major'''
| Always 3
|-
| 0x2
| int16
| '''Version Number Minor'''
| Always 5
|-
| 0x4
| int32
| '''Unused'''
| Always 0
|-
| 0x8
| colspan=3 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| {{FourCC}}
| 1
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x4
| int32
| 1
| '''Asset ID'''
| Unique identifier for this asset.
|-
| 0x8
| int32
| 1
| '''Name Length'''
| Length of the name string
|-
| 0xC
| char
| ''Name Length''
| '''Name String'''
| Name of the asset. Not zero-terminated. This name usually corresponds to a hardcoded string that the game uses to look up the asset, so this generally can't be changed.
|-
| colspan=5 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int32
| '''Compression Flag'''
| Value will be either 0 or 1, with 1 denoting that the asset is compressed.
|-
| 0x4
| {{FourCC}}
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x8
| int32
| '''Asset ID'''
| Unique identifier for this asset. This ID is used by other assets to reference this one.
|-
| 0xC
| int32
| '''Size'''
| Size of the asset data in the pak. This is always 32-byte-aligned. The end of the asset is padded with 0xFF.
|-
| 0x10
| int32
| '''Offset'''
| Offset of the asset data within the pak. This is an absolute offset.
|-
| 0x14
| colspan=4 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless, as there's no benefit to the compression in this scenario).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If any other assets were missing from the list, they are loaded here. It's very important to know that contrary to the previous steps, assets that still aren't in memory at this point are loaded ''synchronously'', which means the game will hang until loading is complete; therefore, you want as few assets as possible to be left to load at this point. (You can observe this hang even in the base game - there is a small freeze towards the end of loading Artifact Temple.)
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvcGc1QjRfSTFJNk0/view?usp=sharing PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

PAK (Metroid Prime)

2018-06-14T19:54:29Z

Aruki: /* Named Resources */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int16
| '''Version Number Major'''
| Always 3
|-
| 0x2
| int16
| '''Version Number Minor'''
| Always 5
|-
| 0x4
| int32
| '''Unused'''
| Always 0
|-
| 0x8
| colspan=3 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| {{FourCC}}
| 1
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x4
| int32
| 1
| '''Asset ID'''
| Unique identifier for this asset.
|-
| 0x8
| int32
| 1
| '''Name Length'''
| Length of the name string
|-
| 0xC
| char
| ''Name Length''
| '''Name String'''
| Name of the asset. This name usually corresponds to a hardcoded string that the game uses to look up the asset, so this generally can't be changed. Not zero-terminated.
|-
| colspan=5 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int32
| '''Compression Flag'''
| Value will be either 0 or 1, with 1 denoting that the asset is compressed.
|-
| 0x4
| {{FourCC}}
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x8
| int32
| '''Asset ID'''
| Unique identifier for this asset. This ID is used by other assets to reference this one.
|-
| 0xC
| int32
| '''Size'''
| Size of the asset data in the pak. This is always 32-byte-aligned. The end of the asset is padded with 0xFF.
|-
| 0x10
| int32
| '''Offset'''
| Offset of the asset data within the pak. This is an absolute offset.
|-
| 0x14
| colspan=4 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless, as there's no benefit to the compression in this scenario).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If any other assets were missing from the list, they are loaded here. It's very important to know that contrary to the previous steps, assets that still aren't in memory at this point are loaded ''synchronously'', which means the game will hang until loading is complete; therefore, you want as few assets as possible to be left to load at this point. (You can observe this hang even in the base game - there is a small freeze towards the end of loading Artifact Temple.)
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvcGc1QjRfSTFJNk0/view?usp=sharing PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

PAK (Metroid Prime)

2018-06-14T19:53:23Z

Aruki: /* Format */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int16
| '''Version Number Major'''
| Always 3
|-
| 0x2
| int16
| '''Version Number Minor'''
| Always 5
|-
| 0x4
| int32
| '''Unused'''
| Always 0
|-
| 0x8
| colspan=3 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| {{FourCC}}
| 1
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x4
| int32
| 1
| '''Asset ID'''
| Unique identifier for this asset.
|-
| 0x8
| int32
| 1
| '''Name Length'''
| Length of the name string
|-
| 0xC
| char
| ''Name Length''
| '''Name String'''
| Name of the asset. This name usually corresponds to a hardcoded string that the game uses to look up the asset, so this generally can't be changed.
|-
| colspan=5 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| int32
| '''Compression Flag'''
| Value will be either 0 or 1, with 1 denoting that the asset is compressed.
|-
| 0x4
| {{FourCC}}
| '''Asset Type'''
| Indicates the type of asset (texture, model, area, etc) and usually doubles as the asset's cooked file extension.
|-
| 0x8
| int32
| '''Asset ID'''
| Unique identifier for this asset. This ID is used by other assets to reference this one.
|-
| 0xC
| int32
| '''Size'''
| Size of the asset data in the pak. This is always 32-byte-aligned. The end of the asset is padded with 0xFF.
|-
| 0x10
| int32
| '''Offset'''
| Offset of the asset data within the pak. This is an absolute offset.
|-
| 0x14
| colspan=4 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless, as there's no benefit to the compression in this scenario).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If any other assets were missing from the list, they are loaded here. It's very important to know that contrary to the previous steps, assets that still aren't in memory at this point are loaded ''synchronously'', which means the game will hang until loading is complete; therefore, you want as few assets as possible to be left to load at this point. (You can observe this hang even in the base game - there is a small freeze towards the end of loading Artifact Temple.)
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvcGc1QjRfSTFJNk0/view?usp=sharing PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

PAK (Metroid Prime)

2018-06-14T19:46:34Z

Aruki: /* Compression */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Version number'''. Always 0x00030005.
|-
| 0x4
| 4
| '''Unused'''; always 0
|-
| 0x8
| colspan=2 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''File type''' fourCC.
|-
| 0x4
| 4
| '''File ID'''.
|-
| 0x8
| 4
| '''Name length''' (NL)
|-
| 0xC
| NL
| '''Name'''; not zero-terminated
|-
| 0xC + NL
| colspan=2 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Compression flag'''; this will either be 0 or 1, with 1 denoting a compressed file.
|-
| 0x4
| 4
| '''File type''' fourCC.
|-
| 0x8
| 4
| '''File ID'''
|-
| 0xC
| 4
| '''Size''' (note: always a multiple of 32. The end of the file is padded with 0xFF in order to be 32-byte aligned.)
|-
| 0x10
| 4
| '''Offset'''
|-
| 0x14
| colspan=2 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless, as there's no benefit to the compression in this scenario).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If any other assets were missing from the list, they are loaded here. It's very important to know that contrary to the previous steps, assets that still aren't in memory at this point are loaded ''synchronously'', which means the game will hang until loading is complete; therefore, you want as few assets as possible to be left to load at this point. (You can observe this hang even in the base game - there is a small freeze towards the end of loading Artifact Temple.)
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvcGc1QjRfSTFJNk0/view?usp=sharing PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

PAK (Metroid Prime)

2018-06-14T19:44:23Z

Aruki: /* Optimizing Load Times */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Version number'''. Always 0x00030005.
|-
| 0x4
| 4
| '''Unused'''; always 0
|-
| 0x8
| colspan=2 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''File type''' fourCC.
|-
| 0x4
| 4
| '''File ID'''.
|-
| 0x8
| 4
| '''Name length''' (NL)
|-
| 0xC
| NL
| '''Name'''; not zero-terminated
|-
| 0xC + NL
| colspan=2 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Compression flag'''; this will either be 0 or 1, with 1 denoting a compressed file.
|-
| 0x4
| 4
| '''File type''' fourCC.
|-
| 0x8
| 4
| '''File ID'''
|-
| 0xC
| 4
| '''Size''' (note: always a multiple of 32. The end of the file is padded with 0xFF in order to be 32-byte aligned.)
|-
| 0x10
| 4
| '''Offset'''
|-
| 0x14
| colspan=2 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If any other assets were missing from the list, they are loaded here. It's very important to know that contrary to the previous steps, assets that still aren't in memory at this point are loaded ''synchronously'', which means the game will hang until loading is complete; therefore, you want as few assets as possible to be left to load at this point. (You can observe this hang even in the base game - there is a small freeze towards the end of loading Artifact Temple.)
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvcGc1QjRfSTFJNk0/view?usp=sharing PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

PAK (Metroid Prime)

2018-06-14T19:37:50Z

Aruki: /* Optimizing Load Times */

''See [[PAK (File Format)]] for the other revisions of this format.''

The '''.pak format''' in Metroid Prime and Metroid Prime 2 is a fairly simple packfile format; files are stored with a 32-bit file ID, and can optionally be compressed with zlib (Metroid Prime) or LZO1X-999 (Metroid Prime 2). The assets in a pak are split into two groups: named resources and dependencies. In general, only named resources are accessed directly by the game; the rest are dependencies of the named resources, and are accessed indirectly in the process of parsing those files.

Note that the Metroid Prime 3 E3 prototype uses this pak format as well, but has 64-bit file IDs. This is the only difference; the version number is still the same, so there isn't an easy way to check for this variation of the format.

__TOC__

== Format==

=== Header ===

The pak starts with a short 8-byte header:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Version number'''. Always 0x00030005.
|-
| 0x4
| 4
| '''Unused'''; always 0
|-
| 0x8
| colspan=2 {{unknown|End of header}}
|}

=== Named Resources ===

The named resource table lists files that the game has direct access to. On world paks, this will generally only contain the MLVL file; in other paks, this table is usually quite a bit larger. Note that in non-world paks, the names are hardcoded and are how the game knows where to find the files; if you repack, you need to make sure you keep the names the same.

This section of the file begins with a 32-bit named resource count, followed by a table.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''File type''' fourCC.
|-
| 0x4
| 4
| '''File ID'''.
|-
| 0x8
| 4
| '''Name length''' (NL)
|-
| 0xC
| NL
| '''Name'''; not zero-terminated
|-
| 0xC + NL
| colspan=2 {{unknown|End of entry}}
|}

=== Resource Table ===

This could be considered the main table of contents of the pak. This table begins with a 32-bit resource count, followed by one entry per file; each entry is 0x14 bytes large.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Compression flag'''; this will either be 0 or 1, with 1 denoting a compressed file.
|-
| 0x4
| 4
| '''File type''' fourCC.
|-
| 0x8
| 4
| '''File ID'''
|-
| 0xC
| 4
| '''Size''' (note: always a multiple of 32. The end of the file is padded with 0xFF in order to be 32-byte aligned.)
|-
| 0x10
| 4
| '''Offset'''
|-
| 0x14
| colspan=2 {{unknown|End of entry}}
|}

== Compression ==

Compressed files begin with their 32-bit decompressed size, followed by the compressed file data. Metroid Prime uses zlib, which is easily recognized from zlib's 0x78DA header at the start of the compressed data. Each file is compressed as a single zlib stream.

Metroid Prime 2 uses segmented LZO1X-999, and gets slightly more complicated. Metroid Prime 2's compressed files are split up into multiple segments of compressed data, each of which is 0x4000 bytes large when decompressed (except for the last one) and should be compressed and decompressed separately. Each segment begins with a 16-bit size value before its actual compressed data begins.

Only certain formats are compressed. The following formats are always compressed:

* [[TXTR (Metroid Prime)|TXTR]]
* [[CMDL (Metroid Prime)|CMDL]]
* [[CSKR (File Format)|CSKR]]
* [[ANCS (File Format)|ANCS]]
* [[ANIM (File Format)|ANIM]]
* [[FONT (File Format)|FONT]]

The following formats are compressed when their uncompressed size is at least 0x400 bytes (0x40 bytes in the MP3 prototype):

* [[PART (File Format)|PART]]
* [[ELSC (File Format)|ELSC]]
* [[SWHC (File Format)|SWHC]]
* [[WPSC (File Format)|WPSC]]
* [[DPSC (File Format)|DPSC]]
* [[CRSC (File Format)|CRSC]]

Additionally, in Prime 2 any files can be left uncompressed if the compressed file is larger than the uncompressed one. This is not the case in Prime 1 (although custom repacking implementations should probably do this regardless).

== Optimizing Load Times ==

When rebuilding new paks, it's extremely important that asset order be optimized in order to minimize the distance the game has to seek on the disc in order to load any given asset. A poorly optimized pak can easily have 30+ second load times on small rooms. There are three main things that are done in order to keep load times fast.

* In world paks, assets are often duplicated so they appear multiple times within the pak; if an asset is used by a lot of different areas this can help reduce seek distance, but has the downside of bloating the total file size of the pak. To ensure the best balance between the two, asset duplication was flagged on a per-area basis, as larger areas take longer to load and would benefit from the faster load speed, whereas small rooms tend to load quickly anyway even without duplicates. The flag that was used for this only existed in Retro's raw files and isn't present in the final game's cooked data. You can recreate it by analyzing the pak and noting down which rooms have duplicate assets (bearing in mind that the assets used by a room always precede that room's MREA asset). If you are working strictly from a pre-unpacked pak, you can't replicate the flag.
* Assets are generally grouped by load order - things that are used together are adjacent in the pak, and an asset's dependencies typically appear immediately preceding the asset itself. This grouping helps ensure that even when assets aren't duplicated the game will still be able to do just one large seek and then load a bunch of assets at once, instead of having to do a separate seek for each asset.
* Once you have assets stored in the pak in the right order, you need to make sure the game actually reads them in that order! The exact order that assets are loaded in is specified by the dependency list in the [[MLVL (File Format)|MLVL]] file; as such, the MLVL list should also have assets grouped in the same way and the same order and should at least roughly match the order files are positioned in the pak.

For every asset loaded, the game checks every copy of the asset in the pak and loads whichever duplicate is the shortest distance from the last read position (the end of the last asset that was loaded). When loading an area, this is the order the game loads assets in:
* First the game goes down the area dependency list in the [[MLVL (File Format)|MLVL]] file and loads every file in the list for every active layer. The game follows the exact order specified by the list.
* After loading all area dependencies, the area itself is loaded.
* Finally the game loads assets being used by the new area that are missing from the list. This primarily means [[SCAN (File Format)|SCAN]] files (in MP1), the skybox model, and assets being used by PlayerActor animsets (this avoids loading PlayerActor assets for suits that the player doesn't have). If anything else is missing from the list, they will still be loaded, but this step will cause the game to hang until the load is finished.
* Note that any assets that are already in memory will be skipped.

'''Note:''' There are some discrepancies between the order assets appear in the pak and the actual load order specified by the MLVL file. There might be some more research needed to fully explain all the quirks behind Retro's pak optimization.

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvcGc1QjRfSTFJNk0/view?usp=sharing PakTool] by Aruki

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

Materials (Metroid Prime)

2018-03-04T19:41:27Z

Aruki: /* Flags */

The format for '''materials''' is seen in both the [[CMDL (Metroid Prime)|CMDL]] and [[MREA (File Format)|MREA]] formats and is identical in both. This particular material format appears in both Metroid Prime and Metroid Prime 2 with minor differences.

{{research|minor|MP1's materials are completely understood, but MP2 introduced two new values that are both unknown.}}

__TOC__

== GX Overview ==

The materials system in Metroid Prime is heavily dependent on the GameCube and Wii's graphics system, GX. GX is a fixed-function graphics pipeline, similar to old versions of OpenGL. In GX, rendering is done through a series of steps called '''T'''exture '''E'''n'''V'''ironment Stages, or or TEV stages for short.

Lighting calculations and tex coord generation are done per-vertex and passed along to TEV; the results of the lighting calculations are saved into up to two color channels that can be used as TEV inputs (as the rasterized vertex color). Each TEV stage takes in four color inputs and four alpha inputs, from one of eight sources. Then these four input colors are combined into one output color, and the output is saved into one of four registers, which can subsequently be used as input in the next TEV stages. The final stage must always save its output into the "previous TEV stage" register; that register is used as the final pixel color that gets displayed onscreen.

== Material Set Format ==

Materials come as part of a set; often there will only be one set per file, but many CMDLs can have more than one. The set begins with a short header before the actual material data begins.

{| class="wikitable"
!Type
!Count
!Description
|-
| long
| 1
| '''Texture count''' (TC)
|-
| long
| TC
| '''Texture file IDs'''
|-
| long
| 1
| '''Material count''' (MC)
|-
| long
| MC
| '''Material end offsets''' (relative to the start of the first material)
|-
| colspan=3 | Materials begin
|}

== Material Format ==

=== General Settings ===

Each material begins with a flags value, followed by a list of texture indices:

{| class="wikitable"
!Type
!Count
!Description
|-
| long
| 1
| '''Flags'''
|-
| long
| 1
| '''Texture count''' (TC)
|-
| long
| TC
| '''Texture indices''' (these are indices into the material set texture array)
|-
| long
| 1
| '''Vertex attribute flags'''
|-
| long
| 1
| {{unknown|'''Unknown''' ''(note: only in Echoes)''}}
|-
| long
| 1
| {{unknown|'''Unknown''' ''(note: only in Echoes)''}}
|-
| long
| 1
| '''Group index'''
|-
| long
| 1
| '''Konst count''' (KC); max setting is 4. ''(note: only present if flag 0x8 is set!)''
|-
| long
| KC
| '''Konst colors''' - 32-bit RGBA colors ''(note: not present if the Konst count isn't)''
|-
| short
| 1
| '''Blend destination factor'''
|-
| short
| 1
| '''Blend source factor'''
|-
| long
| 1
| '''Reflection indirect texture slot index''' ''(note: only present if flag 0x400 is set!)''
|-
| long
| 1
| '''Color channel count''' (CC)
|-
| long
| CC
| '''Color channel flags''' ''(note: only one flag value, but you must advance 4*CC bytes instead of 4 for some reason)''
|-
| long
| 1
| '''TEV stage count'''
|}

==== Flags ====

These are simple boolean settings that can be toggled on and off on each material. These are the known flag settings:

{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| Unused, always set ''(never set in Echoes)''
|-
| 1
| 0x2
| Unused, always set
|-
| 2
| 0x4
| Unused, never set
|-
| 3
| 0x8
| Has Konst values
|-
| 4
| 0x10
| Transparent
|-
| 5
| 0x20
| Masked alpha (compare threshold is hardcoded at 0.25)
|-
| 6
| 0x40
| Enable Samus's reflection
|-
| 7
| 0x80
| Enable Z-writes
|-
| 8
| 0x100
| Enable Samus's reflection, using the eye position and projection direction from the surface header
|-
| 9
| 0x200
| Shadow occluder mesh; meshes using this material are not rendered, but can be used to cast dynamic shadows on actors
|-
| 10
| 0x400
| Enable indirect texture stage for reflections
|-
| 11
| 0x800
| Indicates a lightmap is present; no ingame effect
|-
| 12
| 0x1000
| Unused, always set ''(never set in Echoes)''
|-
| 13
| 0x2000
| Enable first UV coordinate to use short array instead of float array (used for world lightmaps)
|-
| 14
| 0x4000
| {{unknown|In MP1, unused, never set; in Echoes, unknown}}
|-
| 15
| 0x8000
| {{unknown|In MP1, unused, never set; in Echoes, unknown}}
|-
| 16-31
| 0xFFFF0000
| TEV texture flags; a bit set indicates that the corresponding TEV stage uses a texture. No ingame effect.
|}

==== Vertex Attribute Flags ====

These flags are generally toggled in pairs, with each pair corresponding to a vertex attribute; if a pair is set, then vertices using this material will have the corresponding attribute. This is vital for reading geometry. Starting in Echoes, each pair is used to indicate the size of the attribute indices in the geometry data, with 3 meaning a 16-bit index and 2 meaning an 8-bit index. (This isn't actually used, though; the original game data always uses 16-bit indices.)

GX supports up to 8 texture coords per vertex, but the game doesn't seem to allow you to assign more than 7 (though this could do with some double-checking).

These are the possible attributes:

{| class="wikitable"
! Bit pair
! Attribute
|-
| 0x3
| Position
|-
| 0xC
| Normal
|-
| 0x30
| Color 0
|-
| 0xC0
| Color 1
|-
| 0x300
| Tex 0
|-
| 0xC00
| Tex 1
|-
| 0x3000
| Tex 2
|-
| 0xC000
| Tex 3
|-
| 0x30000
| Tex 4
|-
| 0xC0000
| Tex 5
|-
| 0x300000
| Tex 6
|}

Echoes introduces some new attributes using the top byte of the flags value; unlike the other flags, these are not set in pairs. Each individual bit indicates the presence of a different attribute. The indices in the geometry data are always 8 bits.

{| class="wikitable"
! Bit
! Attribute
|-
| 0x1
| Position Matrix Index
|-
| 0x2
| Tex0 Matrix Index
|-
| 0x4
| Tex1 Matrix Index
|-
| 0x8
| Tex2 Matrix Index
|-
| 0x10
| Tex3 Matrix Index
|-
| 0x20
| Tex4 Matrix Index
|-
| 0x40
| Tex5 Matrix Index
|-
| 0x80
| Tex6 Matrix Index
|}

==== Group Index ====

The group index marks groups of materials that all have the same settings, but different textures. The game will check the value after loading the textures (but prior to the vertex attribute flags), and check whether the group index set on the material matches the material currently set up. If it does, it will skip the rest of the material setup. The value typically starts at 0 on the first material and increments by 1 on each new group with different settings.

==== Konst Colors ====

These values are only present when flag 0x8 is enabled. These allow you to set Konstant values, which can subsequently be used as inputs in TEV stages. The maximum number of Konst values you can set on one material is 4. The colors themselves are simply 32-bit RGBA values.

==== Blend Mode ====

The two blend factors set the blending mode used. The most common values you'll see are 0/1, which is used on opaque materials; transparent materials will usually have either 1/1, for additive blending, or 5/4, for alpha blending. Here's the full range of possible settings for each value:

{| class="wikitable"
! Value
! Blend factor
|-
| 0
| GX_BL_ZERO
|-
| 1
| GX_BL_ONE
|-
| 2
| GX_BL_SRCCLR / GX_BL_DSTCLR
|-
| 3
| GX_BL_INVSRCCLR / GX_BL_INVSRCCLR
|-
| 4
| GX_BL_SRCALPHA
|-
| 5
| GX_BL_INVSRCALPHA
|-
| 6
| GX_BL_DSTALPHA
|-
| 7
| GX_BL_INVDSTALPHA
|}

==== Color Channels ====

The color channels data consists of a count value indicating the number of color channels, and then one set of flags that controls the COLOR0 channel. The flags correspond to arguments passed to [http://libogc.devkitpro.org/gx_8h.html#a87d79cf2375217d06237c887ba027cc2 GX_SetChanCtrl()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0
| 0x1
| '''Enable lighting''' (enable)
|-
| 1
| 0x2
| '''Ambient color source''' (ambsrc)
|-
| 2
| 0x4
| '''Material color source''' (matsrc)
|-
| 3-10
| 0x7F8
| '''Light mask'''; always 0, filled in at runtime ([http://libogc.devkitpro.org/group__lightid.html litmask])
|-
| 11-12
| 0x1800
| '''Diffuse function''' ([http://libogc.devkitpro.org/group__difffn.html diff_fn])
|-
| 13-14
| 0x6000
| '''Attenuation function''' ([http://libogc.devkitpro.org/group__attenfunc.html attn_fn])
|}

There's only one set of flags, which operates on COLOR0. COLOR1 is reserved for dynamic shadows (terrain casting shadows on actors), so its settings can't be directly modified. Here's how the other color channel settings work.

COLOR1A1's settings vary depending on whether shadowmaps are enabled:

* No processing will be done if the count value is 0. Otherwise, the count value is ignored; the game will always set up both color channels.
* COLOR1A1's ambient color is black, and its material color is white.
* COLOR1 will use the diffuse function GX_DF_CLAMP and the attenuation function GX_AF_SPOT. It will have lighting disabled entirely if there are no lights in range

If shadowmaps are disabled:

* COLOR1 is disabled if the count value is not 2. If it is 2, then its ambient color will be black and its material color will be white.

COLOR0 is set up the same way either way:

* COLOR0 will use the flags from the material, with the light mask merged in. It will also have lighting disabled if there are no lights in range.
* If there are no lights in range, COLOR0A0 will have its material color set to match its ambient color. Otherwise, its material color will be set to white.

Finally, an important note is that the formatting of the color channel info is bugged. There is always a color channel count and a single set of flags; 8 bytes total. However, for some reason the game is expecting one set of flags per color channel. To reach the TEV stages, you need to advance (4 * count) bytes past the count value, rather than 4. A likely explanation is that there was one set of flags per channel earlier in development, and the material loading code wasn't fully updated when this was changed. It's not normally an issue because the count is always 1 in every file the game uses, but beware for experimentation/custom materials.

=== TEV Stages ===

There'll be one of these structures per TEV stage:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Color Input Flags'''
|-
| 0x4
| 4
| '''Alpha Input Flags'''
|-
| 0x8
| 4
| '''Color Combine Flags'''
|-
| 0xC
| 4
| '''Alpha Combine Flags'''
|-
| 0x10
| 1
| '''Padding'''
|-
| 0x11
| 1
| '''Konst Alpha Input''' ([http://libogc.devkitpro.org/group__tevkalphasel.html possible values])
|-
| 0x12
| 1
| '''Konst Color Input''' ([http://libogc.devkitpro.org/group__tevkcolorsel.html possible values])
|-
| 0x13
| 1
| '''Rasterized Color Input''' ([http://libogc.devkitpro.org/group__channelid.html possible values])
|-
| 0x14
| colspan=2 {{unknown|End of TEV stage}}
|}

After looping through each TEV stage, there will be one of these structures per stage:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Padding'''
|-
| 0x2
| 1
| '''Texture TEV Input'''
|-
| 0x3
| 1
| '''Tex Coord TEV Input'''
|-
| 0x4
| colspan=2 {{unknown|End of structure}}
|}

==== Color Input Flags ====

These flags set the four color inputs that are used by the TEV stage. Each color is allocated 5 bits, even though only 4 are actually used; the lower bits correspond to the lower input numbers (eg. the bottom 5 bits refer to the first input).

There are 16 possible color sources:

{| class="wikitable"
! Binary
! Hex
! Color Source
|-
| 00000
| 0x0
| Previous stage RGB
|-
| 00001
| 0x1
| Previous stage AAA
|-
| 00010
| 0x2
| Color 0 RGB
|-
| 00011
| 0x3
| Color 0 AAA
|-
| 00100
| 0x4
| Color 1 RGB
|-
| 00101
| 0x5
| Color 1 AAA
|-
| 00110
| 0x6
| Color 2 RGB
|-
| 00111
| 0x7
| Color 2 AAA
|-
| 01000
| 0x8
| Texture RGB
|-
| 01001
| 0x9
| Texture AAA
|-
| 01010
| 0xA
| Rasterized RGB
|-
| 01011
| 0xB
| Rasterized AAA
|-
| 01100
| 0xC
| One
|-
| 01101
| 0xD
| Half
|-
| 01110
| 0xE
| Konstant RGB
|-
| 01111
| 0xF
| Zero
|}

==== Alpha Input Flags ====

Similar to the color input flags, these set the four alpha inputs used by the TEV stage. Each value is allocated 5 bits, although only 3 are used. The main difference with alpha is that there are only 8 possible sources instead of 16:

{| class="wikitable"
! Binary
! Hex
! Alpha Source
|-
| 00000
| 0x0
| Previous stage alpha
|-
| 00001
| 0x1
| Color 0 alpha
|-
| 00010
| 0x2
| Color 1 alpha
|-
| 00011
| 0x3
| Color 2 alpha
|-
| 00100
| 0x4
| Texture alpha
|-
| 00101
| 0x5
| Rasterized alpha
|-
| 00110
| 0x6
| Konstant alpha
|-
| 00111
| 0x7
| Zero
|}

==== Color Combine Flags ====

These flags specify how the operation that combines the four input colors into one output color is performed.

This is the combiner function:

<pre>tevrigid = (d (tevop) ((1.0-c)*a + c*b) + tevbias) * tevscale;</pre>

The values set in the color operation flags correspond to the parameters passed to [http://libogc.devkitpro.org/gx_8h.html#a067b875ff1e3e6760d0d7d7838c6c4c2 GX_SetTevColorOp()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0-3
| 0xF
| '''Combiner operator''' ([http://libogc.devkitpro.org/group__tevop.html tevop])
|-
| 4-5
| 0x30
| '''Bias''' ([http://libogc.devkitpro.org/group__tevbias.html tevbias]); 00 does nothing; 01 adds 0.5; 10 subtracts 0.5; 11 does nothing.
|-
| 6-7
| 0xC0
| '''Scale''' ([http://libogc.devkitpro.org/group__tevscale.html tevscale]); 00 does nothing; 01 multiples by 2; 10 multiplies by 4; 11 divides by 2.
|-
| 8
| 0x100
| '''Clamp flag'''; enabling this will clamp the output color between 0 and 1.
|-
| 9-10
| 0x600
| '''Output register''' ([http://libogc.devkitpro.org/group__tevcoloutreg.html tevrigid]); can be Previous Stage or Color 0/1/2
|-
| 11+
| 0xFFFFF800
| Unused.
|}

Note that the vast majority of materials in the game, if not all of them, don't really bother with any of this; they enable clamping, set an output register, and leave everything else at their defaults of 0.

==== Alpha Combine Flags ====

This is exactly the same as the color combine flags; the only difference is it operates on alpha instead of color.

=== Texgen ===

After the TEV stages comes a sequence of flags determining how texgen is executed. Texgen is the process of taking input values and using them to generate texture coordinates (or UV coordinates), which can then be used by the TEV stages. It's important to note that any vertex attribute can be used as a texgen input; in fact, it's rather common for materials to use the vertex normal as an input to simulate reflections. That means ''the number of texture coords present on each vertex is not the same as the number of texture coords available to TEV''.

{| class="wikitable"
! Type
! Count
! Description
|-
| long
| 1
| '''Texgen count''' (TC)
|-
| long
| TC
| '''Texgen flags'''
|}

The flags correspond to arguments passed to [http://libogc.devkitpro.org/gx_8h.html#a55a426a3ff796db584302bddd829f002 GX_SetTexCoordGen2()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0-3
| 0xF
| '''Texture coord generation type''' ([http://libogc.devkitpro.org/group__texgentyp.html tgen_typ])
|-
| 4-8
| 0x1F0
| '''Texture coord source''' ([http://libogc.devkitpro.org/group__texgensrc.html tgen_src])
|-
| 9-13
| 0x3E00
| '''Texture matrix index''' ([http://libogc.devkitpro.org/group__texmtx.html mtxsrc] - add 30)
|-
| 14
| 0x4000
| '''Normalize flag''' - normalizes texture coord after it's multiplied by the texture matrix (normalize)
|-
| 15-20
| 0x1F8000
| '''Post-transform texture matrix index''' ([http://libogc.devkitpro.org/group__dttmtx.html postmtx] - add 64)
|-
| 21+
| 0xFFE00000
| Unused
|}

=== UV Animations ===

'' See [[UV Animations]]''

The UV animations section immediately follows the texgen flags. Its purpose is to generate texture matrices and post-transform matrices, which are then used to transform UV coordinates. This is commonly used to animate textures via simple UV scrolls, but it's also often used to simulate reflective surfaces that move with the camera. Materials can have multiple UV animations; in that case, each animation generates a separate texture/post-transform matrix and are loaded into GX sequentially. Texgen is used to set which matrices are used by which UV coordinates (if any).

The section starts with this short header:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Material animations section size''' (includes animation count, so will be 4 at minimum)
|-
| 0x4
| 4
| '''Animation count'''
|}

For info on how to read the animation data and how each animation mode works, see [[UV Animations]].

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

Materials (Metroid Prime)

2018-03-04T19:40:13Z

Aruki: /* Flags */

The format for '''materials''' is seen in both the [[CMDL (Metroid Prime)|CMDL]] and [[MREA (File Format)|MREA]] formats and is identical in both. This particular material format appears in both Metroid Prime and Metroid Prime 2 with minor differences.

{{research|minor|MP1's materials are completely understood, but MP2 introduced two new values that are both unknown.}}

__TOC__

== GX Overview ==

The materials system in Metroid Prime is heavily dependent on the GameCube and Wii's graphics system, GX. GX is a fixed-function graphics pipeline, similar to old versions of OpenGL. In GX, rendering is done through a series of steps called '''T'''exture '''E'''n'''V'''ironment Stages, or or TEV stages for short.

Lighting calculations and tex coord generation are done per-vertex and passed along to TEV; the results of the lighting calculations are saved into up to two color channels that can be used as TEV inputs (as the rasterized vertex color). Each TEV stage takes in four color inputs and four alpha inputs, from one of eight sources. Then these four input colors are combined into one output color, and the output is saved into one of four registers, which can subsequently be used as input in the next TEV stages. The final stage must always save its output into the "previous TEV stage" register; that register is used as the final pixel color that gets displayed onscreen.

== Material Set Format ==

Materials come as part of a set; often there will only be one set per file, but many CMDLs can have more than one. The set begins with a short header before the actual material data begins.

{| class="wikitable"
!Type
!Count
!Description
|-
| long
| 1
| '''Texture count''' (TC)
|-
| long
| TC
| '''Texture file IDs'''
|-
| long
| 1
| '''Material count''' (MC)
|-
| long
| MC
| '''Material end offsets''' (relative to the start of the first material)
|-
| colspan=3 | Materials begin
|}

== Material Format ==

=== General Settings ===

Each material begins with a flags value, followed by a list of texture indices:

{| class="wikitable"
!Type
!Count
!Description
|-
| long
| 1
| '''Flags'''
|-
| long
| 1
| '''Texture count''' (TC)
|-
| long
| TC
| '''Texture indices''' (these are indices into the material set texture array)
|-
| long
| 1
| '''Vertex attribute flags'''
|-
| long
| 1
| {{unknown|'''Unknown''' ''(note: only in Echoes)''}}
|-
| long
| 1
| {{unknown|'''Unknown''' ''(note: only in Echoes)''}}
|-
| long
| 1
| '''Group index'''
|-
| long
| 1
| '''Konst count''' (KC); max setting is 4. ''(note: only present if flag 0x8 is set!)''
|-
| long
| KC
| '''Konst colors''' - 32-bit RGBA colors ''(note: not present if the Konst count isn't)''
|-
| short
| 1
| '''Blend destination factor'''
|-
| short
| 1
| '''Blend source factor'''
|-
| long
| 1
| '''Reflection indirect texture slot index''' ''(note: only present if flag 0x400 is set!)''
|-
| long
| 1
| '''Color channel count''' (CC)
|-
| long
| CC
| '''Color channel flags''' ''(note: only one flag value, but you must advance 4*CC bytes instead of 4 for some reason)''
|-
| long
| 1
| '''TEV stage count'''
|}

==== Flags ====

These are simple boolean settings that can be toggled on and off on each material. These are the known flag settings:

{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| Unused, always set ''(never set in Echoes)''
|-
| 1
| 0x2
| Unused, always set
|-
| 2
| 0x4
| Unused, never set
|-
| 3
| 0x8
| Enable Konst values
|-
| 4
| 0x10
| Enable depth sorting for transparent materials
|-
| 5
| 0x20
| Enable masked alpha
|-
| 6
| 0x40
| Enable Samus's reflection
|-
| 7
| 0x80
| Enable depth writing
|-
| 8
| 0x100
| Enable Samus's reflection, using the eye position and projection direction from the surface header
|-
| 9
| 0x200
| Shadow occluder mesh; meshes using this material are not rendered, but can be used to cast dynamic shadows on actors
|-
| 10
| 0x400
| Enable indirect texture stage for reflections
|-
| 11
| 0x800
| Indicates a lightmap is present; no ingame effect
|-
| 12
| 0x1000
| Unused, always set ''(never set in Echoes)''
|-
| 13
| 0x2000
| Enable first UV coordinate to use short array instead of float array (used for world lightmaps)
|-
| 14
| 0x4000
| {{unknown|In MP1, unused, never set; in Echoes, unknown}}
|-
| 15
| 0x8000
| {{unknown|In MP1, unused, never set; in Echoes, unknown}}
|-
| 16-31
| 0xFFFF0000
| TEV texture flags; a bit set indicates that the corresponding TEV stage uses a texture. No ingame effect.
|}

==== Vertex Attribute Flags ====

These flags are generally toggled in pairs, with each pair corresponding to a vertex attribute; if a pair is set, then vertices using this material will have the corresponding attribute. This is vital for reading geometry. Starting in Echoes, each pair is used to indicate the size of the attribute indices in the geometry data, with 3 meaning a 16-bit index and 2 meaning an 8-bit index. (This isn't actually used, though; the original game data always uses 16-bit indices.)

GX supports up to 8 texture coords per vertex, but the game doesn't seem to allow you to assign more than 7 (though this could do with some double-checking).

These are the possible attributes:

{| class="wikitable"
! Bit pair
! Attribute
|-
| 0x3
| Position
|-
| 0xC
| Normal
|-
| 0x30
| Color 0
|-
| 0xC0
| Color 1
|-
| 0x300
| Tex 0
|-
| 0xC00
| Tex 1
|-
| 0x3000
| Tex 2
|-
| 0xC000
| Tex 3
|-
| 0x30000
| Tex 4
|-
| 0xC0000
| Tex 5
|-
| 0x300000
| Tex 6
|}

Echoes introduces some new attributes using the top byte of the flags value; unlike the other flags, these are not set in pairs. Each individual bit indicates the presence of a different attribute. The indices in the geometry data are always 8 bits.

{| class="wikitable"
! Bit
! Attribute
|-
| 0x1
| Position Matrix Index
|-
| 0x2
| Tex0 Matrix Index
|-
| 0x4
| Tex1 Matrix Index
|-
| 0x8
| Tex2 Matrix Index
|-
| 0x10
| Tex3 Matrix Index
|-
| 0x20
| Tex4 Matrix Index
|-
| 0x40
| Tex5 Matrix Index
|-
| 0x80
| Tex6 Matrix Index
|}

==== Group Index ====

The group index marks groups of materials that all have the same settings, but different textures. The game will check the value after loading the textures (but prior to the vertex attribute flags), and check whether the group index set on the material matches the material currently set up. If it does, it will skip the rest of the material setup. The value typically starts at 0 on the first material and increments by 1 on each new group with different settings.

==== Konst Colors ====

These values are only present when flag 0x8 is enabled. These allow you to set Konstant values, which can subsequently be used as inputs in TEV stages. The maximum number of Konst values you can set on one material is 4. The colors themselves are simply 32-bit RGBA values.

==== Blend Mode ====

The two blend factors set the blending mode used. The most common values you'll see are 0/1, which is used on opaque materials; transparent materials will usually have either 1/1, for additive blending, or 5/4, for alpha blending. Here's the full range of possible settings for each value:

{| class="wikitable"
! Value
! Blend factor
|-
| 0
| GX_BL_ZERO
|-
| 1
| GX_BL_ONE
|-
| 2
| GX_BL_SRCCLR / GX_BL_DSTCLR
|-
| 3
| GX_BL_INVSRCCLR / GX_BL_INVSRCCLR
|-
| 4
| GX_BL_SRCALPHA
|-
| 5
| GX_BL_INVSRCALPHA
|-
| 6
| GX_BL_DSTALPHA
|-
| 7
| GX_BL_INVDSTALPHA
|}

==== Color Channels ====

The color channels data consists of a count value indicating the number of color channels, and then one set of flags that controls the COLOR0 channel. The flags correspond to arguments passed to [http://libogc.devkitpro.org/gx_8h.html#a87d79cf2375217d06237c887ba027cc2 GX_SetChanCtrl()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0
| 0x1
| '''Enable lighting''' (enable)
|-
| 1
| 0x2
| '''Ambient color source''' (ambsrc)
|-
| 2
| 0x4
| '''Material color source''' (matsrc)
|-
| 3-10
| 0x7F8
| '''Light mask'''; always 0, filled in at runtime ([http://libogc.devkitpro.org/group__lightid.html litmask])
|-
| 11-12
| 0x1800
| '''Diffuse function''' ([http://libogc.devkitpro.org/group__difffn.html diff_fn])
|-
| 13-14
| 0x6000
| '''Attenuation function''' ([http://libogc.devkitpro.org/group__attenfunc.html attn_fn])
|}

There's only one set of flags, which operates on COLOR0. COLOR1 is reserved for dynamic shadows (terrain casting shadows on actors), so its settings can't be directly modified. Here's how the other color channel settings work.

COLOR1A1's settings vary depending on whether shadowmaps are enabled:

* No processing will be done if the count value is 0. Otherwise, the count value is ignored; the game will always set up both color channels.
* COLOR1A1's ambient color is black, and its material color is white.
* COLOR1 will use the diffuse function GX_DF_CLAMP and the attenuation function GX_AF_SPOT. It will have lighting disabled entirely if there are no lights in range

If shadowmaps are disabled:

* COLOR1 is disabled if the count value is not 2. If it is 2, then its ambient color will be black and its material color will be white.

COLOR0 is set up the same way either way:

* COLOR0 will use the flags from the material, with the light mask merged in. It will also have lighting disabled if there are no lights in range.
* If there are no lights in range, COLOR0A0 will have its material color set to match its ambient color. Otherwise, its material color will be set to white.

Finally, an important note is that the formatting of the color channel info is bugged. There is always a color channel count and a single set of flags; 8 bytes total. However, for some reason the game is expecting one set of flags per color channel. To reach the TEV stages, you need to advance (4 * count) bytes past the count value, rather than 4. A likely explanation is that there was one set of flags per channel earlier in development, and the material loading code wasn't fully updated when this was changed. It's not normally an issue because the count is always 1 in every file the game uses, but beware for experimentation/custom materials.

=== TEV Stages ===

There'll be one of these structures per TEV stage:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Color Input Flags'''
|-
| 0x4
| 4
| '''Alpha Input Flags'''
|-
| 0x8
| 4
| '''Color Combine Flags'''
|-
| 0xC
| 4
| '''Alpha Combine Flags'''
|-
| 0x10
| 1
| '''Padding'''
|-
| 0x11
| 1
| '''Konst Alpha Input''' ([http://libogc.devkitpro.org/group__tevkalphasel.html possible values])
|-
| 0x12
| 1
| '''Konst Color Input''' ([http://libogc.devkitpro.org/group__tevkcolorsel.html possible values])
|-
| 0x13
| 1
| '''Rasterized Color Input''' ([http://libogc.devkitpro.org/group__channelid.html possible values])
|-
| 0x14
| colspan=2 {{unknown|End of TEV stage}}
|}

After looping through each TEV stage, there will be one of these structures per stage:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Padding'''
|-
| 0x2
| 1
| '''Texture TEV Input'''
|-
| 0x3
| 1
| '''Tex Coord TEV Input'''
|-
| 0x4
| colspan=2 {{unknown|End of structure}}
|}

==== Color Input Flags ====

These flags set the four color inputs that are used by the TEV stage. Each color is allocated 5 bits, even though only 4 are actually used; the lower bits correspond to the lower input numbers (eg. the bottom 5 bits refer to the first input).

There are 16 possible color sources:

{| class="wikitable"
! Binary
! Hex
! Color Source
|-
| 00000
| 0x0
| Previous stage RGB
|-
| 00001
| 0x1
| Previous stage AAA
|-
| 00010
| 0x2
| Color 0 RGB
|-
| 00011
| 0x3
| Color 0 AAA
|-
| 00100
| 0x4
| Color 1 RGB
|-
| 00101
| 0x5
| Color 1 AAA
|-
| 00110
| 0x6
| Color 2 RGB
|-
| 00111
| 0x7
| Color 2 AAA
|-
| 01000
| 0x8
| Texture RGB
|-
| 01001
| 0x9
| Texture AAA
|-
| 01010
| 0xA
| Rasterized RGB
|-
| 01011
| 0xB
| Rasterized AAA
|-
| 01100
| 0xC
| One
|-
| 01101
| 0xD
| Half
|-
| 01110
| 0xE
| Konstant RGB
|-
| 01111
| 0xF
| Zero
|}

==== Alpha Input Flags ====

Similar to the color input flags, these set the four alpha inputs used by the TEV stage. Each value is allocated 5 bits, although only 3 are used. The main difference with alpha is that there are only 8 possible sources instead of 16:

{| class="wikitable"
! Binary
! Hex
! Alpha Source
|-
| 00000
| 0x0
| Previous stage alpha
|-
| 00001
| 0x1
| Color 0 alpha
|-
| 00010
| 0x2
| Color 1 alpha
|-
| 00011
| 0x3
| Color 2 alpha
|-
| 00100
| 0x4
| Texture alpha
|-
| 00101
| 0x5
| Rasterized alpha
|-
| 00110
| 0x6
| Konstant alpha
|-
| 00111
| 0x7
| Zero
|}

==== Color Combine Flags ====

These flags specify how the operation that combines the four input colors into one output color is performed.

This is the combiner function:

<pre>tevrigid = (d (tevop) ((1.0-c)*a + c*b) + tevbias) * tevscale;</pre>

The values set in the color operation flags correspond to the parameters passed to [http://libogc.devkitpro.org/gx_8h.html#a067b875ff1e3e6760d0d7d7838c6c4c2 GX_SetTevColorOp()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0-3
| 0xF
| '''Combiner operator''' ([http://libogc.devkitpro.org/group__tevop.html tevop])
|-
| 4-5
| 0x30
| '''Bias''' ([http://libogc.devkitpro.org/group__tevbias.html tevbias]); 00 does nothing; 01 adds 0.5; 10 subtracts 0.5; 11 does nothing.
|-
| 6-7
| 0xC0
| '''Scale''' ([http://libogc.devkitpro.org/group__tevscale.html tevscale]); 00 does nothing; 01 multiples by 2; 10 multiplies by 4; 11 divides by 2.
|-
| 8
| 0x100
| '''Clamp flag'''; enabling this will clamp the output color between 0 and 1.
|-
| 9-10
| 0x600
| '''Output register''' ([http://libogc.devkitpro.org/group__tevcoloutreg.html tevrigid]); can be Previous Stage or Color 0/1/2
|-
| 11+
| 0xFFFFF800
| Unused.
|}

Note that the vast majority of materials in the game, if not all of them, don't really bother with any of this; they enable clamping, set an output register, and leave everything else at their defaults of 0.

==== Alpha Combine Flags ====

This is exactly the same as the color combine flags; the only difference is it operates on alpha instead of color.

=== Texgen ===

After the TEV stages comes a sequence of flags determining how texgen is executed. Texgen is the process of taking input values and using them to generate texture coordinates (or UV coordinates), which can then be used by the TEV stages. It's important to note that any vertex attribute can be used as a texgen input; in fact, it's rather common for materials to use the vertex normal as an input to simulate reflections. That means ''the number of texture coords present on each vertex is not the same as the number of texture coords available to TEV''.

{| class="wikitable"
! Type
! Count
! Description
|-
| long
| 1
| '''Texgen count''' (TC)
|-
| long
| TC
| '''Texgen flags'''
|}

The flags correspond to arguments passed to [http://libogc.devkitpro.org/gx_8h.html#a55a426a3ff796db584302bddd829f002 GX_SetTexCoordGen2()]. These are the settings:

{| class="wikitable"
! Bits
! Hex
! Description
|-
| 0-3
| 0xF
| '''Texture coord generation type''' ([http://libogc.devkitpro.org/group__texgentyp.html tgen_typ])
|-
| 4-8
| 0x1F0
| '''Texture coord source''' ([http://libogc.devkitpro.org/group__texgensrc.html tgen_src])
|-
| 9-13
| 0x3E00
| '''Texture matrix index''' ([http://libogc.devkitpro.org/group__texmtx.html mtxsrc] - add 30)
|-
| 14
| 0x4000
| '''Normalize flag''' - normalizes texture coord after it's multiplied by the texture matrix (normalize)
|-
| 15-20
| 0x1F8000
| '''Post-transform texture matrix index''' ([http://libogc.devkitpro.org/group__dttmtx.html postmtx] - add 64)
|-
| 21+
| 0xFFE00000
| Unused
|}

=== UV Animations ===

'' See [[UV Animations]]''

The UV animations section immediately follows the texgen flags. Its purpose is to generate texture matrices and post-transform matrices, which are then used to transform UV coordinates. This is commonly used to animate textures via simple UV scrolls, but it's also often used to simulate reflective surfaces that move with the camera. Materials can have multiple UV animations; in that case, each animation generates a separate texture/post-transform matrix and are loaded into GX sequentially. Texgen is used to set which matrices are used by which UV coordinates (if any).

The section starts with this short header:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Material animations section size''' (includes animation count, so will be 4 at minimum)
|-
| 0x4
| 4
| '''Animation count'''
|}

For info on how to read the animation data and how each animation mode works, see [[UV Animations]].

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]

Chunk Descriptor (Tropical Freeze)

2018-01-31T08:28:43Z

Aruki:

The '''chunk descriptor''' is a very common 24-byte header that describes different data sections, found in many different Donkey Kong Country: Tropical Freeze formats.

{{research|2|A few unknown values.}}

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| {{FourCC}}
| '''Chunk ID'''
|
|-
| 0x4
| u64
| '''Chunk Size'''
| The size does not include the chunk descriptor itself.
|-
| 0xC
| u32
| {{unknown}}
| Usually 1.
|-
| 0x10
| u64
| {{unknown}}
| Usually 0.
|-
| 0x18
| colspan=3 {{unknown|End of Chunk Descriptor}}
|}

[[Category:Donkey Kong Country: Tropical Freeze]]

Geometry (Metroid Prime)

2018-01-20T17:16:23Z

Aruki: /* Surface */

The format for '''geometry''' appears in both the [[CMDL (File Format)|CMDL]] and [[MREA (File Format)|MREA]] formats, and is identical between both. This format is used in all three Prime games, and is largely unchanged between all of them (with the exception of an extra vertex attribute that was added in Echoes and Corruption).

{{research|1|There's two unknowns in the surface headers that appear in Prime 2.}}

__TOC__

== Format ==

An important thing to note off the bat is that both CMDL and MREA files are split up into a number of 32-byte-aligned ''sections''; their respective headers both declare a section count, and list the sizes of each section contained in the file. This is required to navigate to different parts of the file, and is required in order to read the geometry data correctly. Sections are generally split based on the type of data contained in them, so one section might contain vertex coordinates, while another contains a surface (submesh) definition. For the purposes of this article, each subheader will mark the start of a new section; use that as your cue to advance to the next one. Check the CMDL or MREA pages for more info on how the sections work.

In the CMDL format, and in the MP1/2 MREA format, all data sections appear in the order that they are listed in this page. In the Prime 3/DKCR MREA format, the surface definitions, surface group IDs, and surface lookup table are shifted to a different part of the file.

For vertex attributes, note that there's no count value present anywhere. If you want a rough count, you can divide the size of that attribute's section by the attribute's size; this approach doesn't account for padding, however.

=== Vertex Coordinates ===

These are stored as a sequence of three floats.

=== Normals ===

Normals can appear as either floats or shorts. In CMDL, this usually corresponds to the 0x2 bit in the flags value, and in MREA they will always appear as shorts; this is technically supposed to be set by the vertex format flag in the primitive data, though. If they appear as shorts, they should be divided by the mantissa value that appears on each surface (that value is always 0x8000).

=== Vertex Color ===

These are theoretically stored as 32-bit RGBA values, but vertex color isn't actually used by any mesh in any Retro games, so this section always appears completely empty.

=== Float UV Coordinates ===

These are stored as a sequence of two floats.

=== Short UV Coordinates ===

These are stored as a sequence of two shorts. Like normals, these should be divided by the surface's mantissa value. The short UV array is generally only used by terrain lightmaps, and as such this section always appears completely empty (listed with a size of 0) on CMDL. This array can only be used by the first UV coordinate on a given vertex, and whether it's used or not depends on one of the flags on the material. The rest will use the float array.

=== Surface Offsets ===

This section is very small and simple; it simply declares a surface count and then lists the offsets to the end of each surface. Following this section, there'll be one additional section per surface.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| '''Surface Count'''
|
|-
| 0x4
| u32
| ''Surface Count''
| '''Surface Offsets'''
| Relative to the start address of the first surface.
|-
| colspan=5 {{unknown|Surface sections begin}}
|}

=== Surface ===

There will be one of these sections per surface. Each surface starts with a small header; following the end of the header, the file is padded with 0s to the next 32-byte boundary, then the primitive data begins.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| float
| 3
| '''Center Point'''
| Used for depth sorting on CMDL and used as the eye position for reflections
|-
| 0xC
| u32
| 1
| '''Material Index'''
|
|-
| 0x10
| u16
| 1
| '''Mantissa'''
| Always 0x8000.
|-
| 0x12
| u16
| 1
| '''Display List Size'''
| '''Important: this value is not always reliable'''
|-
| 0x14
| u32
| 1
| '''Parent Model Pointer Storage'''
| Always 0; the game uses this space at runtime to store a pointer to the parent CCubeModel instance
|-
| 0x18
| u32
| 1
| '''Next Surface Pointer Storage'''
| Always 0; the game uses this space at runtime to store a pointer to the next surface
|-
| 0x1C
| u32
| 1
| '''Extra Data Size'''
| Amount of space taken up by extra data. Always 0 on CMDLs, 0x18 on MREAs.
|-
| 0x20
| float
| 3
| '''Surface Normal'''
| On materials that use the Samus reflection, this is used to project the reflection onto the surface
|-
| 0x2C
| u16
| 1
| {{unknown|Unknown}}
| Not in Prime 1.
|-
| 0x2E
| u16
| 1
| {{unknown|Unknown}}
| Not in Prime 1.
|-
| 0x30
| u8
| ''Extra Data Size''
| '''Extra Data'''
| Empty on CMDL; contains a bounding box used for depth sorting on MREA.
|-
| colspan=5 {{unknown|End of surface header; pad to multiple of 32 before primitive data starts}}
|}

The primitive data is a GX display list. Each primitive begins with a byte that contains the primitive type in the upper 5 bits, and the vertex format setting in the lower 3; see below for possible settings. After that is a 16-bit vertex count, followed by a series of 16-bit vertex attribute indices.

Note that you'll need to check some settings on the material to read the primitive data properly; the material determines which vertex attributes are present. The material also determines whether the surface is using lightmaps; if it is, then the first UV coordinate will be read out of the short UV array instead of the float one.

There is no primitive count value; you'll need to continue reading data until you hit the end of the display list. There are a couple values you can use for reference; either the surface's section size, or the surface's end offset. '''Do not use the display list size setting from the surface header, though'''; it's usually accurate, but on some models it will give you a size smaller than the table actually is, and you'll miss a bunch of data. See Metroid3/4a11192a.CMDL from Prime 1 (icicle Ridley) or Metroid1/05778239.CMDL from Echoes (Samus's gunship) for an example of this.

There are 7 primitive types supported by GX, indicated in the upper 5 bits of the flag value. Note that the game only ever actually uses triangles, triangle strips, and triangle fans; however, all of these primitives are supported by GX and are therefore supported by the game, and so they could be used in custom model files.

{| class="wikitable"
! Value
! Primitive
|-
| 0x80
| Quads
|-
| 0x90
| Triangles
|-
| 0x98
| Triangle Strip
|-
| 0xA0
| Triangle Fan
|-
| 0xA8
| Lines
|-
| 0xB0
| Line Strip
|-
| 0xB8
| Points
|}

In addition, the game uses three vertex formats, indicated in the lower 3 bits of the flag value (0x7). The only attributes that change between formats are nrm and tex0, so those are the only ones listed in the table below.

{| class="wikitable"
! Format
! GX_VA_NRM type/size
! GX_VA_TEX0 type/size
|-
| 0
| GX_NRM_XYZ / GX_F32
| GX_TEX_ST / GX_F32
|-
| 1
| GX_NRM_XYZ / GX_S16
| GX_TEX_ST / GX_F32
|-
| 2
| GX_NRM_XYZ / GX_S16
| GX_TEX_ST / GX_S16
|}

=== Surface Group IDs ===

This section (and the following one) appears in [[MREA (File Format)|MREA files]] starting in Metroid Prime 2. Starting in MP2, surfaces in world geometry are now merged together to create as few meshes as possible (meshes are now only split when the vertex count exceeds 65535). Two extra data sections are present to manage the resulting super-meshes to enable the game to extract smaller meshes out when needed.

This first section assigns a group ID to each surface, forming smaller meshes. This ID is used in various places that operate on world geometry, including in the [[AROT (MREA Section)|area octree]] as well as in the [[EGMC (File Format)|EGMC format]], among others.

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u16
| 1
| '''Surface Count'''
| Matches the world model surface count
|-
| [[#Surface Group ID|Surface Group ID]]
| ''Surface Count''
| '''Surface Group ID Array'''
| Sequentially assigns a surface group ID to every surface in the mesh.
|}

==== Surface Group ID ====

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u16
| '''Model-Relative Surface Group ID'''
| This is the ID of the group this surface belongs to, relative to the groups in this model (starting from 0).
|-
| 0x2
| u16
| '''Surface Group ID'''
| Same ID, except area-relative (starting where the previous world model's group IDs left off). This is generally the ID that appears in other places to reference this group.
|}

=== Surface Lookup Table ===

This is the second new [[MREA (File Format)|MREA]]-exclusive section introduced in Metroid Prime 2. It provides a mapping of each surface group to the surfaces contained in it, so that surfaces can be quickly accessed by group ID.

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u16
| 1
| '''Surface Group Count'''
|
|-
| u16
| ''Surface Group Count''
| '''Lookup Table Index Array'''
| The value of each element corresponds to the end index of the surfaces for this group in the lookup table. Each element is equal to the previous element + the number of surfaces contained in this group.
|-
| u16
| ''Surface Count''
| '''Surface Lookup Table'''
| List of surface indices ordered by group ID.
|}

[[Category:File Formats]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3: Corruption]]

TXTR (Tropical Freeze)

2017-12-17T21:04:32Z

Aruki: /* PAK Metadata */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! style="width:110px;"|Type
! style="width:100px;"|Count
! style="width:170px;"|Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| '''Mipmap Sizes'''
| The size of the base level mipmap is calculated with padding and alignment taken into account. The size of subsequent mipmaps is calculated as Width*Height*Depth*BPP/8. This does '''not''' take padding and alignment into account, and so it does not accurately reflect the amount of space the mipmap takes up in the file, and it cannot be used to accurately locate and read mipmap data. The offset and size needs to be calculated from the other parameters in the header. The game calculates this data by calling GX2CalcSurfaceSizeAndAlignment.
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! Type
|-
| 0
| 1D Texture
|-
| 1
| 2D Texture
|-
| 2
| 3D Texture
|-
| 3
| Cube Texture
|-
| 4
| 1D Texture Array
|-
| 5
| 2D Texture Array
|-
| 6
| Multisampled 2D Texture
|-
| 7
| Multisampled 2D Texture Array
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
| Always 4
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| '''Base Alignment'''
| Alignment of the surface image data
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-12-17T19:27:02Z

Aruki: /* PAK Metadata */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! style="width:110px;"|Type
! style="width:100px;"|Count
! style="width:170px;"|Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| '''Mipmap Sizes'''
| The size of the base level mipmap is calculated with padding and alignment taken into account. The size of subsequent mipmaps is calculated as Width*Height*Depth*BPP/8. This does '''not''' take padding and alignment into account, and so it does not accurately reflect the amount of space the mipmap takes up in the file, and it cannot be used to accurately locate and read mipmap data. The offset and size needs to be calculated from the other parameters in the header. The game calculates this data by calling GX2CalcSurfaceSizeAndAlignment.
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! Type
|-
| 0
| 1D Texture
|-
| 1
| 2D Texture
|-
| 2
| 3D Texture
|-
| 3
| Cube Texture
|-
| 4
| 1D Texture Array
|-
| 5
| 2D Texture Array
|-
| 6
| Multisampled 2D Texture
|-
| 7
| Multisampled 2D Texture Array
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
| Always 4
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
| Always 0
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| '''Base Alignment'''
| Alignment of the surface image data
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-12-16T19:55:08Z

Aruki: /* Texture Type */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! style="width:110px;"|Type
! style="width:100px;"|Count
! style="width:170px;"|Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| '''Mipmap Sizes'''
| The size of the base level mipmap is calculated with padding and alignment taken into account. The size of subsequent mipmaps is calculated as Width*Height*Depth*BPP/8. This does '''not''' take padding and alignment into account, and so it does not accurately reflect the amount of space the mipmap takes up in the file, and it cannot be used to accurately locate and read mipmap data. The offset and size needs to be calculated from the other parameters in the header. The game calculates this data by calling GX2CalcSurfaceSizeAndAlignment.
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! Type
|-
| 0
| 1D Texture
|-
| 1
| 2D Texture
|-
| 2
| 3D Texture
|-
| 3
| Cube Texture
|-
| 4
| 1D Texture Array
|-
| 5
| 2D Texture Array
|-
| 6
| Multisampled 2D Texture
|-
| 7
| Multisampled 2D Texture Array
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-12-16T08:23:16Z

Aruki: /* Format */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! style="width:110px;"|Type
! style="width:100px;"|Count
! style="width:170px;"|Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| '''Mipmap Sizes'''
| The size of the base level mipmap is calculated with padding and alignment taken into account. The size of subsequent mipmaps is calculated as Width*Height*Depth*BPP/8. This does '''not''' take padding and alignment into account, and so it does not accurately reflect the amount of space the mipmap takes up in the file, and it cannot be used to accurately locate and read mipmap data. The offset and size needs to be calculated from the other parameters in the header. The game calculates this data by calling GX2CalcSurfaceSizeAndAlignment.
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceDim
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-12-15T08:09:22Z

Aruki: /* Format */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! style="width:110px;"|Type
! style="width:100px;"|Count
! style="width:170px;"|Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| '''Mipmap Sizes'''
| The size of the base level mipmap is calculated with padding and alignment taken into account. The size of subsequent mipmaps is calculated as Width*Height*Depth*BPP/8. This does '''not''' take padding and alignment into account so it cannot be used to accurately locate and read mipmap data in the file. The offset and size needs to be calculated from the other parameters in the header. The game calculates this data by calling GX2CalcSurfaceSizeAndAlignment.
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceDim
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-12-14T21:21:22Z

Aruki:

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| '''Mipmap Sizes'''
|
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceDim
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-11-29T08:13:30Z

Aruki: I'm like 90% sure this is accurate right now...

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| '''Tile Mode'''
| Indicates how the texture image data is tiled.
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| {{unknown|Unknown array}}
| Appears to be mipmap sizes, but it doesn't match the size of the image data (unless there's 1)...
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceDim
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-11-27T06:17:24Z

Aruki: /* Texture Type */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| {{unknown|Unknown array}}
| Appears to be mipmap sizes, but it doesn't match the size of the image data (unless there's 1)...
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceDim
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-11-26T21:23:35Z

Aruki: /* Format */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
| Describes the type/dimensionality of the texture (2D texture, 3D texture, cubemap, array of 2D images, etc).
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
| Describes the format that the image data is encoded in.
|-
| 0x20
| u32
| 1
| '''Width'''
| Texture X resolution.
|-
| 0x24
| u32
| 1
| '''Height'''
| Texture Y resolution.
|-
| 0x28
| u32
| 1
| '''Depth'''
| Texture Z resolution.
|-
| 0x2C
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x30
| u32
| 1
| '''Swizzle'''
| Indicates how the texture image data is swizzled.
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| {{unknown|Unknown array}}
| Appears to be mipmap sizes, but it doesn't match the size of the image data (unless there's 1)...
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
| Determines how the texture is filtered when sampled.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
| Determines how the texture wraps on the X coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
| Determines how the texture wraps on the Y coordinate.
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
| Determines how the texture wraps on the Z coordinate.
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceType
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-11-26T17:00:34Z

Aruki: /* Format */

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
|
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
|
|-
| 0x20
| u32
| 1
| '''Width'''
|
|-
| 0x24
| u32
| 1
| '''Height'''
|
|-
| 0x28
| u32
| 1
| '''Depth'''
|
|-
| 0x2C
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x30
| u32
| 1
| '''Swizzle'''
|
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| {{unknown|Unknown array}}
| Appears to be mipmap sizes, but it doesn't match the size of the image data (unless there's 1)...
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap X''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
|
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceType
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-11-26T16:55:31Z

Aruki:

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|moderate|There are a couple unknowns in the header. It would also be good to have some documentation on how to deswizzle/decompress different texture formats.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
|
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
|
|-
| 0x20
| u32
| 1
| '''Width'''
|
|-
| 0x24
| u32
| 1
| '''Height'''
|
|-
| 0x28
| u32
| 1
| '''Depth'''
|
|-
| 0x2C
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x30
| u32
| 1
| '''Swizzle'''
|
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| {{unknown|Unknown array}}
| Appears to be mipmap sizes, but it doesn't match the size of the image data (unless there's 1)...
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wraps X''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
|
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceType
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

TXTR (Tropical Freeze)

2017-11-26T16:54:52Z

Aruki:

''See [[TXTR (File Format)]] for the other revisions of this format.''

The '''TXTR''' format is Tropical Freeze's texture format. The image data in the GPU buffer is compressed using [[LZSS Compression|LZSS compression]].

{{research|major|Most everything in the header + image compression formats needs to be cracked + documented.}}

__TOC__

== Format ==

The format starts with the typical [[Form Descriptor (Tropical Freeze)|form descriptor]] found in every Tropical Freeze format. Following that, there's a HEAD header section that contains most of the texture parameters, then the GPU section containing the actual compressed image data. This is the structure of the HEAD section:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''HEAD Chunk Descriptor'''
|
|-
| 0x18
| u32
| 1
| [[#Texture Type|'''Texture Type''']]
|
|-
| 0x1C
| u32
| 1
| [[#Texture Format|'''Texture Format''']]
|
|-
| 0x20
| u32
| 1
| '''Width'''
|
|-
| 0x24
| u32
| 1
| '''Height'''
|
|-
| 0x28
| u32
| 1
| '''Depth'''
|
|-
| 0x2C
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x30
| u32
| 1
| '''Swizzle'''
|
|-
| 0x34
| u32
| 1
| '''Mipmap Count'''
|
|-
| 0x38
| u32
| ''Mipmap Count''
| {{unknown|Unknown array}}
| Appears to be mipmap sizes, but it doesn't match the size of the image data (unless there's 1)...
|-
| {{none}}
| u32
| 1
| {{unknown|Unknown}}
| This parameter is part of NTextureFormat::STextureSamplerData (along with the next 4 parameters)
|-
| {{none}}
| u8
| 1
| [[#Texture Filter|'''Texture Filter''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wraps X''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Y''']]
|
|-
| {{none}}
| u8
| 1
| [[#Texture Wrap|'''Texture Wrap Z''']]
|
|}

=== Texture Type ===

This enum basically maps directly to a GX2SurfaceDim enum.

{| class="wikitable"
! ID
! GX2SurfaceType
|-
| 0
| GX2_SURFACE_DIM_1D
|-
| 1
| GX2_SURFACE_DIM_2D
|-
| 2
| GX2_SURFACE_DIM_3D
|-
| 3
| GX2_SURFACE_DIM_CUBE
|-
| 4
| GX2_SURFACE_DIM_1D_ARRAY
|-
| 5
| GX2_SURFACE_DIM_2D_ARRAY
|-
| 6
| GX2_SURFACE_DIM_2D_MSAA
|-
| 7
| GX2_SURFACE_DIM_2D_MSAA_ARRAY
|}

=== Texture Format ===

{| class="wikitable"
! ID
! GX2SurfaceFormat
|-
| 0x00
| GX2_SURFACE_FORMAT_TC_R8_UNORM
|-
| 0x01
| GX2_SURFACE_FORMAT_TC_R8_SNORM
|-
| 0x02
| GX2_SURFACE_FORMAT_TC_R8_UINT
|-
| 0x03
| GX2_SURFACE_FORMAT_TC_R8_SINT
|-
| 0x04
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x05
| GX2_SURFACE_FORMAT_TC_R16_SNORM
|-
| 0x06
| GX2_SURFACE_FORMAT_TC_R16_UINT
|-
| 0x07
| GX2_SURFACE_FORMAT_TC_R16_SINT
|-
| 0x08
| GX2_SURFACE_FORMAT_TC_R16_FLOAT
|-
| 0x09
| GX2_SURFACE_FORMAT_TC_R32_UINT
|-
| 0x0A
| GX2_SURFACE_FORMAT_TC_R32_SINT
|-
| 0x0B
| GX2_SURFACE_FORMAT_INVALID
|-
| 0x0C
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_UNORM
|-
| 0x0D
| GX2_SURFACE_FORMAT_TCS_R8_G8_B8_A8_SRGB
|-
| 0x0E
| GX2_SURFACE_FORMAT_TC_R16_G16_B16_A16_FLOAT
|-
| 0x0F
| GX2_SURFACE_FORMAT_TC_R32_G32_B32_A32_FLOAT
|-
| 0x10
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x11
| GX2_SURFACE_FORMAT_TCD_R16_UNORM
|-
| 0x12
| GX2_SURFACE_FORMAT_D_D24_S8_UNORM
|-
| 0x13
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x14
| GX2_SURFACE_FORMAT_T_BC1_UNORM
|-
| 0x15
| GX2_SURFACE_FORMAT_T_BC1_SRGB
|-
| 0x16
| GX2_SURFACE_FORMAT_T_BC2_UNORM
|-
| 0x17
| GX2_SURFACE_FORMAT_T_BC2_SRGB
|-
| 0x18
| GX2_SURFACE_FORMAT_T_BC3_UNORM
|-
| 0x19
| GX2_SURFACE_FORMAT_T_BC3_SRGB
|-
| 0x1A
| GX2_SURFACE_FORMAT_T_BC4_UNORM
|-
| 0x1B
| GX2_SURFACE_FORMAT_T_BC4_SNORM
|-
| 0x1C
| GX2_SURFACE_FORMAT_T_BC5_UNORM
|-
| 0x1D
| GX2_SURFACE_FORMAT_T_BC5_SNORM
|-
| 0x1E
| GX2_SURFACE_FORMAT_TC_R11_G11_B10_FLOAT
|-
| 0x1F
| GX2_SURFACE_FORMAT_TCD_R32_FLOAT
|-
| 0x20
| GX2_SURFACE_FORMAT_TC_R16_G16_FLOAT
|-
| 0x21
| GX2_SURFACE_FORMAT_TC_R8_G8_UNORM
|}

=== Texture Filter ===

Invalid values default to 1 (linear).

{| class="wikitable"
! ID
! GX2TexMipFilterType
|-
| 0
| GX2_TEX_MIP_FILTER_POINT
|-
| 1
| GX2_TEX_MIP_FILTER_LINEAR
|}

=== Texture Wrap ===

Invalid values default to 0 (clamp).

{| class="wikitable"
! ID
! GX2TexClamp
|-
| 0
| GX2_TEX_CLAMP_CLAMP
|-
| 1
| GX2_TEX_CLAMP_WRAP
|-
| 2
| GX2_TEX_CLAMP_MIRROR
|-
| 3
| GX2_TEX_CLAMP_MIRROR_ONCE
|}

== PAK Metadata ==

The pak metadata for the TXTR format primarily contains compression-related information and provides the values required to decompress it.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x4
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x8
| u32
| 1
| '''GPU Section Offset'''
| Relative to the start of the file
|-
| 0xC
| u32
| 1
| {{unknown|Unknown}}
|
|-
| 0x10
| u32
| 1
| '''GPU Data Start'''
| This is the offset to the start of the GPU data, immediately after the GPU section header.
|-
| 0x14
| u32
| 1
| '''GPU Section Size'''
| Matches the size from the GPU section header.
|-
| 0x18
| u32
| 1
| '''Compressed Buffer Count'''
|
|-
| 0x1C
| [[#Compressed Buffer|Compressed Buffer]]
| ''Compressed Buffer Count''
| '''Compressed Buffer Array'''
|
|}

=== Compressed Buffer ===

This is a small struct that defines a compressed data buffer within the GPU section.

{| class="wikitable"
! Offset
! Type
! Name
! Notes
|-
| 0x0
| u32
| '''Decompressed Size'''
|
|-
| 0x4
| u32
| '''Compressed Size'''
|
|-
| 0x8
| u32
| '''Offset'''
| Relative to after the GPU section header
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

UINF (File Format)

2017-11-04T19:14:19Z

Aruki: /* Area Info */

The '''UINF format''' sets up the global game universe. The extension stands for ''Universe Info''.

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Form Descriptor (Tropical Freeze)|Form Descriptor]]
| 1
| '''UINF Form Descriptor'''
| Data type is <code>UINF</code>
|-
| 0x20
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Level Names MSBT'''
| Reference to the MSBT file containing all level names.
|-
| 0x30
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Act Number Strings MSBT'''
| Reference to the MSBT file containing all act number strings.
|-
| 0x40
| Asset ID ([[CAUD (File Format)|CAUD]])
| 1
| '''Loading Screen Music CAUD'''
| Reference to the CAUD file containing the loading screen music.
|-
| 0x50
| [[#Area Info|Area Info]]
| ''Varies''
| '''Area Info Array'''
| Array describing all areas/levels in the game. There is no count; read until you reach the end of the UINF form.
|}

=== Area Info ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''ROOM Descriptor'''
| Data type is <code>ROOM</code>
|-
| Asset ID ([[ROOM (File Format)|ROOM]])
| 1
| '''ROOM ID'''
| Asset ID of the ROOM asset for this area
|-
| u32
| 1
| '''Area Name Length'''
| Length of the area name string
|-
| char
| ''Area Name Length''
| '''Area Name'''
| Internal area name. This is probably used for name lookups in the MSBT file and might also be used to look up the pak file for this area.
|-
| u8
| 1
| '''World Number'''
| World number that this level belongs to. (1 = Mangroves, 2 = Alps, 3 = Savannah, etc)
|-
| u8
| 1
| '''Act Number'''
| Act number of this level.
|-
| u8
| 1
| {{unknown|Unknown}}
|
|-
| u16
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

UINF (File Format)

2017-11-04T19:14:06Z

Aruki: /* Area Info */

The '''UINF format''' sets up the global game universe. The extension stands for ''Universe Info''.

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Form Descriptor (Tropical Freeze)|Form Descriptor]]
| 1
| '''UINF Form Descriptor'''
| Data type is <code>UINF</code>
|-
| 0x20
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Level Names MSBT'''
| Reference to the MSBT file containing all level names.
|-
| 0x30
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Act Number Strings MSBT'''
| Reference to the MSBT file containing all act number strings.
|-
| 0x40
| Asset ID ([[CAUD (File Format)|CAUD]])
| 1
| '''Loading Screen Music CAUD'''
| Reference to the CAUD file containing the loading screen music.
|-
| 0x50
| [[#Area Info|Area Info]]
| ''Varies''
| '''Area Info Array'''
| Array describing all areas/levels in the game. There is no count; read until you reach the end of the UINF form.
|}

=== Area Info ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''ROOM Descriptor'''
| Data type is <code>ROOM</code>
|-
| Asset ID ([[ROOM (File Format)|ROOM]])
| 1
| '''ROOM ID'''
| Asset ID of the ROOM asset for this area
|-
| u32
| 1
| '''Area Name Length'''
| Length of the area name string
|-
| char
| ''Area Name Length''
| '''Area Name'''
| Internal area name. This is probably used for name lookups in the MSBT file and might also be used to look up the pak file for this area.
|-
| u8
| 1
| '''World Number'''
| World number that this level belongs to. (1 = Mangroves, 2 = Alps, 3 = Savannah, etc)
|-
| u8
| 1
| '''Act Index'''
| Act number of this level.
|-
| u8
| 1
| {{unknown|Unknown}}
|
|-
| u16
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

UINF (File Format)

2017-11-04T19:13:59Z

Aruki: /* Area Info */

The '''UINF format''' sets up the global game universe. The extension stands for ''Universe Info''.

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Form Descriptor (Tropical Freeze)|Form Descriptor]]
| 1
| '''UINF Form Descriptor'''
| Data type is <code>UINF</code>
|-
| 0x20
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Level Names MSBT'''
| Reference to the MSBT file containing all level names.
|-
| 0x30
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Act Number Strings MSBT'''
| Reference to the MSBT file containing all act number strings.
|-
| 0x40
| Asset ID ([[CAUD (File Format)|CAUD]])
| 1
| '''Loading Screen Music CAUD'''
| Reference to the CAUD file containing the loading screen music.
|-
| 0x50
| [[#Area Info|Area Info]]
| ''Varies''
| '''Area Info Array'''
| Array describing all areas/levels in the game. There is no count; read until you reach the end of the UINF form.
|}

=== Area Info ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''ROOM Descriptor'''
| Data type is <code>ROOM</code>
|-
| Asset ID ([[ROOM (File Format)|ROOM]])
| 1
| '''ROOM ID'''
| Asset ID of the ROOM asset for this area
|-
| u32
| 1
| '''Area Name Length'''
| Length of the area name string
|-
| char
| ''Area Name Length''
| '''Area Name'''
| Internal area name. This is probably used for name lookups in the MSBT file and might also be used to look up the pak file for this area.
|-
| u8
| 1
| '''World Number'''
| World number that this level belongs to. (1 = Mangroves, 2 = Alps, 3 = Savannah, etc)
|-
| u8
| 1
| '''Act Index'''
| Act number of this level.
|-
| bool
| 1
| {{unknown|Unknown}}
|
|-
| u16
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

UINF (File Format)

2017-11-04T19:10:44Z

Aruki: /* Area Info */

The '''UINF format''' sets up the global game universe. The extension stands for ''Universe Info''.

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[Form Descriptor (Tropical Freeze)|Form Descriptor]]
| 1
| '''UINF Form Descriptor'''
| Data type is <code>UINF</code>
|-
| 0x20
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Level Names MSBT'''
| Reference to the MSBT file containing all level names.
|-
| 0x30
| Asset ID ([[MSBT (File Format)|MSBT]])
| 1
| '''Act Number Strings MSBT'''
| Reference to the MSBT file containing all act number strings.
|-
| 0x40
| Asset ID ([[CAUD (File Format)|CAUD]])
| 1
| '''Loading Screen Music CAUD'''
| Reference to the CAUD file containing the loading screen music.
|-
| 0x50
| [[#Area Info|Area Info]]
| ''Varies''
| '''Area Info Array'''
| Array describing all areas/levels in the game. There is no count; read until you reach the end of the UINF form.
|}

=== Area Info ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| [[Chunk Descriptor (Tropical Freeze)|Chunk Descriptor]]
| 1
| '''ROOM Descriptor'''
| Data type is <code>ROOM</code>
|-
| Asset ID ([[ROOM (File Format)|ROOM]])
| 1
| '''ROOM ID'''
| Asset ID of the ROOM asset for this area
|-
| u32
| 1
| '''Area Name Length'''
| Length of the area name string
|-
| char
| ''Area Name Length''
| '''Area Name'''
| Internal area name. This is probably used for name lookups in the MSBT file and might also be used to look up the pak file for this area.
|-
| u8
| 1
| '''World Number'''
| World number that this level belongs to. (1 = Mangroves, 2 = Alps, 3 = Savannah, etc)
|-
| u8
| 1
| '''Act Index'''
| Act number of this level.
|-
| bool
| 1
| '''Is Boss?'''
| True if this level is a boss fight, false otherwise.
|-
| u16
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|-
| u32
| 1
| {{unknown|Unknown}}
|
|}

[[Category:File Formats]]
[[Category:Donkey Kong Country: Tropical Freeze]]

PAS Database

2017-07-08T06:45:37Z

Aruki: /* Anim State */

The '''Parameterized Animation State Database''' is an animation-related thing that appears in every Retro game. It can be found in the [[ANCS (File Format)|ANCS format]] in Metroid Prime 1 and 2, and the [[CHAR (File Format)|CHAR format]] in Metroid Prime 3, Donkey Kong Country Returns, and Donkey Kong Country: Tropical Freeze.

__TOC__

== Format ==

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| {{FourCC}}
| 1
| '''Magic'''
| Always <code>PAS4</code>
|-
| u32
| 1
| '''Anim State Count'''
| Number of anim states
|-
| u32
| 1
| '''Default Anim State'''
| Anim state used by the character by default. If there are no anim states, this will be set to -1.
|-
| [[#Anim State|Anim State]]
| ''Anim State Count''
| '''Anim State Array'''
| Array of anim states.
|}

=== Anim State ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| enum
| 1
| [[#Anim State Type|Anim State Type]]
|
|-
| u32
| 1
| '''Parm Info Count'''
| Number of parameters
|-
| u32
| 1
| '''Anim Info Count'''
| Number of animations
|-
| [[#Parm Info|Parm Info]]
| ''Parm Info Count''
| '''Parm Info Array'''
| Describes parameters in this anim state
|-
| [[#Anim Info|Anim Info]]
| ''Anim Info Count''
| '''Anim Info Array'''
| Describes animations in this anim state
|}

==== Anim State Type ====

{| class="wikitable"
! ID
! State
|-
| 0
| Fall
|-
| 1
| Get Up
|-
| 2
| Lie On Ground
|-
| 3
| Step
|-
| 4
| Death
|-
| 5
| Locomotion
|-
| 6
| Knock Back
|-
| 7
| Melee Attack
|-
| 8
| Turn
|-
| 9
| Loop Attack
|-
| 10
| Loop Reaction
|-
| 11
| Ground Hit
|-
| 12
| Generate
|-
| 13
| Jump
|-
| 14
| Hurled
|-
| 15
| Slide
|-
| 16
| Taunt
|-
| 17
| Scripted
|-
| 18
| Projectile Attack
|-
| 19
| Cover
|-
| 20
| Wall Hang
|}

=== Parm Info ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| [[#Parm Type|'''Parm Type''']]
| Parameter type. This value controls the type of other values in the Parm Info and Anim Info structures.
|-
| u32
| 1
| [[#Weight Function|'''Weight Function''']]
| Specifies the weighting algorithm used for this parameter during selection.
|-
| float
| 1
| '''Weight'''
| Specifies how much influence this parameter has during selection.
|-
| ''Parm Type''
| 1
| '''Minimum Value'''
| Minimum value this parameter can represent. The exact meaning depends on the context within the class implementation that uses it.
|-
| ''Parm Type''
| 1
| '''Maximum Value'''
| Maximum value this parameter can represent. The exact meaning depends on the context within the class implementation that uses it.
|}

==== Parm Type ====

{| class="wikitable"
! ID
! Type
|-
| 0
| Int32
|-
| 1
| Uint32
|-
| 2
| Real
|-
| 3
| Bool
|-
| 4
| Enum
|}

==== Weight Function ====

{| class="wikitable"
! ID
! Type
|-
| 0
| Exact Match
|-
| 1
| Percent Error
|-
| 2
| Angular Percent
|-
| 3
| No Weight
|}

=== Anim Info ===

{| class="wikitable"
! Type
! Count
! Name
! Notes
|-
| u32
| 1
| '''Anim ID'''
| This is a character-relative anim index. In Prime 1/2, this should be indexed into the character's anim list to get the animset-relative index.
|-
| ''Parm Type''
| ''Parm Info Count''
| '''Parm Values Array'''
| This array contains one value per Parm Info. The type of each value is determined by the corresponding Parm Info's ''Parm Type'' value.
|}

[[Category:File Formats]]
[[Category:Metroid Prime Demo]]
[[Category:Metroid Prime]]
[[Category:Metroid Prime 2 Demo]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3 Prototype]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]
[[Category:Donkey Kong Country: Tropical Freeze]]

Scriptable Layers (Metroid Prime 2)

2017-06-27T06:22:07Z

Aruki: /* Generated Objects */

''This article is for the scriptable layers format from Metroid Prime 2, 3, and Donkey Kong Country Returns. See [[Scriptable Layers (File Format)]] for other revisions of this format.''

'''Scriptable layers''' are a data section found in the MREA format, denoted by the fourCC identifier <code>SCLY</code>. It contains script object instances which are used to set the object layout of each room. Rooms can contain multiple layers, with each being able to be toggled on and off independently, allowing for the layout of a room to be updated after significant ingame events, which is done using a ScriptLayerController object. Each instance has a large number of parameters that can be toggled to customize the appearance and behavior of that instance, and they're capable of sending messages to other objects, allowing for fairly complex interactions between objects to be scripted.

In Echoes, the SCLY format was overhauled. The most notable change is that all properties now have a 32-bit ID and a size value listed, allowing the game to match properties in the file with data members by ID rather than by their position in the file; this was presumably done to avoid breaking cooked data when objects were modified during development, since this change meant the file could still be read correctly if properties were added or removed from an object and the script data hadn't been recooked. Another change is that there's now a separate layer for generated objects (ie objects that are spawned using a Generator or a PickupGenerator), which uses the fourCC <code>SCGN</code>. Aside from minor changes in the header, the <code>SCGN</code> layer is identical to <code>SCLY</code> layers.

In Donkey Kong Country Returns, the format is identical, but the way the data is cooked was slightly modified. In every game starting with Prime 2, the engine assigns an arbitrary default value to every object property before reading in the values from the file. In the Prime series, this didn't have much of an effect, since (almost) every property for every object is written to the file anyway. But starting in Donkey Kong Country Returns, any properties whose value matches the internal default value are left out of the file in order to speed up loading times. This means a full list of properties and their internal default value is required to correctly read/write DKCR files. (This change could also be applied in the Prime series with custom script data.)

Although this format is primarily found in MREA files, it's also occasionally reused in other formats, such as [[SCAN (Metroid Prime 2)|SCAN]].

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''Magic'''
| Always <code>SCLY</code> or <code>SCGN</code>
|-
| 0x4
| char
| 1
| {{unknown|Unknown}}
|
|-
| 0x5
| u32
| 1
| {{unknown|Unknown}}
| Appears to be layer self-index. Not present in SCGN.
|-
| 0x9
| char
| 1
| '''Version'''
| Always 1
|-
| 0xA
| u32
| 1
| '''Instance Count'''
| Count of instances in this layer.
|-
| 0xE
| [[#Script Instance|Script Instance]]
| ''Instance Count''
| '''Script Instances'''
| Layer instance data.
|-
| colspan=5 {{unknown|End of layer}}
|}

=== Script Instance ===

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''Instance Type'''
| FourCC representing the type of object this is.
|-
| 0x4
| u16
| 1
| '''Instance Size'''
| Size of this instance, relative to after the size value.
|-
| 0x6
| u32
| 1
| '''Instance ID'''
| ID used by other objects to reference this instance. The bottom 16 bits is an area-relative instance ID. The next 10 bits up are the world-relative area index. The top 6 bits are the layer index. The layer index isn't technically part of the ID, as the game removes it for ID-based lookups.
|-
| 0xA
| u16
| 1
| '''Connection Count'''
| Count of outgoing script connections.
|-
| 0xC
| [[#Connection|Connection]]
| ''Connection Count''
| '''Connection Array'''
| Array of outgoing script connections.
|-
| {{none}}
| [[#Property Struct|Property Struct]]
| 1
| '''Base Struct'''
| This is the instance's base struct, which contains all properties in this instance. The property ID is always 0xFFFFFFFF.
|-
| colspan=5 {{unknown|End of instance}}
|}

=== Connection ===

A connection is used to script interactions between objects; when this instance enters the given ''state'', it sends the target instance the given ''message''.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''State'''
| When the instance enters this state, the connection will activate.
|-
| 0x4
| char
| 4
| '''Message'''
| Message that will be sent to the target instance when the connection activates.
|-
| 0x8
| u32
| 1
| '''Target Instance ID'''
| ID of the target instance.
|-
| 0xC
| colspan=4 {{unknown|End of connection}}
|}

=== Property Struct ===

A property struct is a property that contains other properties. These are often modular pieces that are present on multiple objects (for example, the PatternedAI struct that appears on all enemies). Structs can contain other structs as sub-properties.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| '''Property ID'''
| Property ID for this struct property.
|-
| 0x4
| u16
| 1
| '''Property Size'''
| Size of this struct including all sub-properties.
|-
| 0x6
| u16
| 1
| '''Sub-Property Count'''
| Count of sub-properties contained in this struct.
|-
| 0x8
| [[#Property|Property]]
| ''Sub-Property Count''
| '''Sub-Properties'''
| Array of this struct's sub-properties.
|-
| colspan=5 {{unknown|End of struct}}
|}

=== Property ===

A property represents a single data value on a script instance. The type of each property varies depending on the ID.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| '''Property ID'''
| ID that uniquely identifies this property.
|-
| 0x4
| u16
| 1
| '''Property Size'''
| Size of this property. This is used by the game to skip over the property if it encounters an unrecognized ID.
|-
| 0x6
| Varies
| 1
| '''Property Data'''
| The actual data for this property. The type and size of this data varies depending on which property it is (ie. depending on the ID).
|-
| colspan=5 {{unknown|End of property}}
|}

== Generated Objects ==

Generated objects are stored on a separate layer, denoted with <code>SCGN</code>. The SCGN layer isn't a real layer; it doesn't store a self-index and instances on the layer still contain the index of their original SCLY script layer in their instance ID. These are the stipulations that cause an instance to be written to SCGN:

* Any instance that receives a Generate/Activate message (MP2) or a Generate/Attach, Generate0/Attach, or Generate1/Attach message (MP3, DKCR) is written to SCGN instead of SCLY.
* In DKCR, all GenericCreature instances are written to both SCLY and SCGN. (The generated one is spawned if you scroll the creature offscreen and come back.)

[[Category:File Formats]]
[[Category:Metroid Prime 2 Demo]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3 Prototype]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

Scriptable Layers (Metroid Prime 2)

2017-06-27T05:09:18Z

Aruki:

''This article is for the scriptable layers format from Metroid Prime 2, 3, and Donkey Kong Country Returns. See [[Scriptable Layers (File Format)]] for other revisions of this format.''

'''Scriptable layers''' are a data section found in the MREA format, denoted by the fourCC identifier <code>SCLY</code>. It contains script object instances which are used to set the object layout of each room. Rooms can contain multiple layers, with each being able to be toggled on and off independently, allowing for the layout of a room to be updated after significant ingame events, which is done using a ScriptLayerController object. Each instance has a large number of parameters that can be toggled to customize the appearance and behavior of that instance, and they're capable of sending messages to other objects, allowing for fairly complex interactions between objects to be scripted.

In Echoes, the SCLY format was overhauled. The most notable change is that all properties now have a 32-bit ID and a size value listed, allowing the game to match properties in the file with data members by ID rather than by their position in the file; this was presumably done to avoid breaking cooked data when objects were modified during development, since this change meant the file could still be read correctly if properties were added or removed from an object and the script data hadn't been recooked. Another change is that there's now a separate layer for generated objects (ie objects that are spawned using a Generator or a PickupGenerator), which uses the fourCC <code>SCGN</code>. Aside from minor changes in the header, the <code>SCGN</code> layer is identical to <code>SCLY</code> layers.

In Donkey Kong Country Returns, the format is identical, but the way the data is cooked was slightly modified. In every game starting with Prime 2, the engine assigns an arbitrary default value to every object property before reading in the values from the file. In the Prime series, this didn't have much of an effect, since (almost) every property for every object is written to the file anyway. But starting in Donkey Kong Country Returns, any properties whose value matches the internal default value are left out of the file in order to speed up loading times. This means a full list of properties and their internal default value is required to correctly read/write DKCR files. (This change could also be applied in the Prime series with custom script data.)

Although this format is primarily found in MREA files, it's also occasionally reused in other formats, such as [[SCAN (Metroid Prime 2)|SCAN]].

__TOC__

== Format ==

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''Magic'''
| Always <code>SCLY</code> or <code>SCGN</code>
|-
| 0x4
| char
| 1
| {{unknown|Unknown}}
|
|-
| 0x5
| u32
| 1
| {{unknown|Unknown}}
| Appears to be layer self-index. Not present in SCGN.
|-
| 0x9
| char
| 1
| '''Version'''
| Always 1
|-
| 0xA
| u32
| 1
| '''Instance Count'''
| Count of instances in this layer.
|-
| 0xE
| [[#Script Instance|Script Instance]]
| ''Instance Count''
| '''Script Instances'''
| Layer instance data.
|-
| colspan=5 {{unknown|End of layer}}
|}

=== Script Instance ===

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''Instance Type'''
| FourCC representing the type of object this is.
|-
| 0x4
| u16
| 1
| '''Instance Size'''
| Size of this instance, relative to after the size value.
|-
| 0x6
| u32
| 1
| '''Instance ID'''
| ID used by other objects to reference this instance. The bottom 16 bits is an area-relative instance ID. The next 10 bits up are the world-relative area index. The top 6 bits are the layer index. The layer index isn't technically part of the ID, as the game removes it for ID-based lookups.
|-
| 0xA
| u16
| 1
| '''Connection Count'''
| Count of outgoing script connections.
|-
| 0xC
| [[#Connection|Connection]]
| ''Connection Count''
| '''Connection Array'''
| Array of outgoing script connections.
|-
| {{none}}
| [[#Property Struct|Property Struct]]
| 1
| '''Base Struct'''
| This is the instance's base struct, which contains all properties in this instance. The property ID is always 0xFFFFFFFF.
|-
| colspan=5 {{unknown|End of instance}}
|}

=== Connection ===

A connection is used to script interactions between objects; when this instance enters the given ''state'', it sends the target instance the given ''message''.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| char
| 4
| '''State'''
| When the instance enters this state, the connection will activate.
|-
| 0x4
| char
| 4
| '''Message'''
| Message that will be sent to the target instance when the connection activates.
|-
| 0x8
| u32
| 1
| '''Target Instance ID'''
| ID of the target instance.
|-
| 0xC
| colspan=4 {{unknown|End of connection}}
|}

=== Property Struct ===

A property struct is a property that contains other properties. These are often modular pieces that are present on multiple objects (for example, the PatternedAI struct that appears on all enemies). Structs can contain other structs as sub-properties.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| '''Property ID'''
| Property ID for this struct property.
|-
| 0x4
| u16
| 1
| '''Property Size'''
| Size of this struct including all sub-properties.
|-
| 0x6
| u16
| 1
| '''Sub-Property Count'''
| Count of sub-properties contained in this struct.
|-
| 0x8
| [[#Property|Property]]
| ''Sub-Property Count''
| '''Sub-Properties'''
| Array of this struct's sub-properties.
|-
| colspan=5 {{unknown|End of struct}}
|}

=== Property ===

A property represents a single data value on a script instance. The type of each property varies depending on the ID.

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| '''Property ID'''
| ID that uniquely identifies this property.
|-
| 0x4
| u16
| 1
| '''Property Size'''
| Size of this property. This is used by the game to skip over the property if it encounters an unrecognized ID.
|-
| 0x6
| Varies
| 1
| '''Property Data'''
| The actual data for this property. The type and size of this data varies depending on which property it is (ie. depending on the ID).
|-
| colspan=5 {{unknown|End of property}}
|}

== Generated Objects ==

Generated objects are stored on a separate layer, denoted with <code>SCGN</code>. The SCGN layer isn't a real layer; it doesn't store a self-index and instances on the layer still contain the index of their original SCLY script layer in their instance ID. These are the stipulations that cause an instance to be written to SCGN:

* Any instance that receives a Generate/Activate message (MP2) or a Generate/Attach message (MP3, DKCR) is written to SCGN instead of SCLY.
* In DKCR, all GenericCreature instances are written to both SCLY and SCGN. (The generated one is spawned if you scroll the creature offscreen and come back.)

[[Category:File Formats]]
[[Category:Metroid Prime 2 Demo]]
[[Category:Metroid Prime 2: Echoes]]
[[Category:Metroid Prime 3 Prototype]]
[[Category:Metroid Prime 3: Corruption]]
[[Category:Donkey Kong Country Returns]]

SpecialFunction

2017-06-24T00:12:52Z

Aruki:

SpecialFunctions are script objects that can do a multitude of things depending what the Function enum is set to.

=== PlayerInArea ===

* Sends messages on the "Entered" state when the player enters the area.
* Sends messages on the "Exited" state when the player leaves the area.