Retro Modding Wiki - User contributions [en]

AROT (MREA Section)

2018-10-19T05:59:56Z

Jackoalan:

[[File:Octree2.svg|thumb|right|400px|Left: Recursive subdivision of a cube into [[wikipedia:octant (solid geometry)|octant]]s. Right: The corresponding octree.]]

Within [[MREA (File Format)|MREA]] resources, the '''AROT section''' stores an [[wikipedia:Octree|octree]] which
is used to accelerate rendering of areas in back-to-front order.

Octrees are a form of [[wikipedia:Binary Space Partitioning|BSP tree]] that subdivide an area in 3-dimensions.
They are structured recursively, starting with a ''root'' node and traversing their way to individual ''leaf'' nodes.
A full-branch octant will split sub-octants across 3-tiers, one for each dimension of euclidean space.
Retro uses a Z-major convention with (up to) 8 child-nodes subdivided as: 2 nodes along Z, 4 nodes along Y,
and 8 nodes along X. A set of three bit-flags in each node determines which dimensions are subdivided.
Nodes that do not subdivide all 3 dimensions will parent less child nodes as a result.

Within each octant is an index to a [[wikipedia:Bit array|bitmap]] relating that AABB-volume to a set of meshes within the MREA; they
are sorted and frustum-culled accordingly. Actors, particle effects, and other visual entities are also sorted and
frustum-culled according to which octant(s) they intersect.

=== Layout ===

{| class="wikitable"
! Data Type
! Element Count
! Description
! Notes
|-
| [[#Header|Header]]
| 1
| Octree Header
|
|-
| long
| round_up(bitmap_bit_count / 32) * bitmap_count
| Mesh Bitmap Array
| An array of word-packed bitmaps relating octant nodes to sets of MREA meshes
|-
| long
| node_count
| Node Indirection Table
| Since nodes use variable-length-encoding, there is an indirection table with byte-offsets (relative to first node)
|-
| [[#Node Entry|Node Entry]]
| node_count
| Node Entry Table
| Tightly-packed blob of nodes
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Data Type
! Description
! Notes
|-
| 0x0
| 4
| long
| Magic
| <code>AROT</code>
|-
| 0x4
| 4
| long
| Version
| Always 0x1
|-
| 0x8
| 4
| long
| Mesh-Bitmap Count
| Count of mesh-bitmaps
|-
| 0xC
| 4
| long
| Mesh-Bitmap Bit-Count
| Count of bits in each mesh-bitmap (matches MREA's mesh count)
|-
| 0x10
| 4
| long
| Node Count
| Number of octant nodes
|-
| 0x14
| 24
| float2x3
| AABB
| AABB that fully-encloses area and serves as the octree's root-shape
|-
| 0x2C
| 20
|
| Alignment Padding
| Allows the following bitmaps to be data-cached with guaranteed 32-byte alignment
|}

=== Node Entry ===

{| class="wikitable"
! Offset
! Size
! Data Type
! Description
! Notes
|-
| 0x0
| 2
| short
| Bitmap Index
| Index of the mesh bitmap defining a set of MREA meshes for this octant node
|-
| 0x2
| 2
| short
| Dimensional Flags
| If non-zero, this half-word contains 3-bits specifying which dimensions are subdivided using the children specified (using Z-major convention)
<ul>
<li>0x4 — Z subdivided</li>
<li>0x2 — Y subdivided</li>
<li>0x1 — X subdivided</li>
</ul>
'''If zero, this node-entry ends here'''
|-
| 0x4
| Varies
| short[]
| Node Child Indices
| Variable-length array of node-entry indices that are children of this node-entry (Z-major layout)
|}

CSNG (File Format)

2018-09-04T05:32:27Z

Jackoalan: /* Region Info */

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data when positive; -1 value terminates track; -2 value loops jumps to ''Loop Region Index'' at this region's tick
|-
| 0xA
| 2
| '''Loop Region Index'''; index of region to jump to if ''Region Data Index'' set to -2
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time Encoding=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
value to store the delta times. In case of a delta time greater than 65535, no-op commands
with a 65535 delta time are inserted into the command stream until the target time is attained.

In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTime(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
next = streamIn.PeekU16()
if next == 0:
# Automatically consume no-op and continue accumulating time value
total += 0xffff
streamIn.seekAhead(2)
continue
total += term
return total
</syntaxhighlight>

=====No-Op Command=====

When the two bytes following the delta-time are both zero, this is a no-op command.

As mentioned before, no-ops are useful for accumulating delta times greater than 65535.

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of
(delta-tick, delta-value) pairs. The delta times are encoded as unsigned 7/15 bit values
and the delta values are signed 7/15-bit values. The values are promoted to 15-bit if they
exceed their 7-bit range. In this case, the highest bit is set on the first byte in the pair
(0x80). The decoder must track the absolute time and value, summing each consecutive update
for the current time/values.

The byte sequence 0x80 0x00 is a special case that signals the end of the stream.

Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
with a zeroed value delta are inserted.

<syntaxhighlight lang="python" line="1">
def SignExtend7(value):
return (value & 0x3f) - (value & 0x40)

def SignExtend15(value):
return (value & 0x3fff) - (value & 0x4000)

def DecodeSignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return SignExtend15(byte1 | ((byte0 & 0x7f) << 8))
else:
return SignExtend7(byte0)

def DecodeUnsignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return byte1 | ((byte0 & 0x7f) << 8)
else:
return byte0

def DecodeDeltaPair(streamIn):
ret = [0,0]
while ret[1] == 0:
if streamIn.PeekU16() == 0x8000:
# The stream has ended
break
ret[0] += DecodeUnsignedValue(streamIn)
ret[1] = DecodeSignedValue(streamIn)
return ret
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

CSNG (File Format)

2018-08-16T21:08:13Z

Jackoalan: /* Continuous Pitch / Modulation Data */

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time Encoding=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
value to store the delta times. In case of a delta time greater than 65535, no-op commands
with a 65535 delta time are inserted into the command stream until the target time is attained.

In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTime(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
next = streamIn.PeekU16()
if next == 0:
# Automatically consume no-op and continue accumulating time value
total += 0xffff
streamIn.seekAhead(2)
continue
total += term
return total
</syntaxhighlight>

=====No-Op Command=====

When the two bytes following the delta-time are both zero, this is a no-op command.

As mentioned before, no-ops are useful for accumulating delta times greater than 65535.

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of
(delta-tick, delta-value) pairs. The delta times are encoded as unsigned 7/15 bit values
and the delta values are signed 7/15-bit values. The values are promoted to 15-bit if they
exceed their 7-bit range. In this case, the highest bit is set on the first byte in the pair
(0x80). The decoder must track the absolute time and value, summing each consecutive update
for the current time/values.

The byte sequence 0x80 0x00 is a special case that signals the end of the stream.

Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
with a zeroed value delta are inserted.

<syntaxhighlight lang="python" line="1">
def SignExtend7(value):
return (value & 0x3f) - (value & 0x40)

def SignExtend15(value):
return (value & 0x3fff) - (value & 0x4000)

def DecodeSignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return SignExtend15(byte1 | ((byte0 & 0x7f) << 8))
else:
return SignExtend7(byte0)

def DecodeUnsignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return byte1 | ((byte0 & 0x7f) << 8)
else:
return byte0

def DecodeDeltaPair(streamIn):
ret = [0,0]
while ret[1] == 0:
if streamIn.PeekU16() == 0x8000:
# The stream has ended
break
ret[0] += DecodeUnsignedValue(streamIn)
ret[1] = DecodeSignedValue(streamIn)
return ret
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

AGSC (File Format)

2018-08-16T20:56:54Z

Jackoalan: /* Normal / Drum Page Entry */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID'''.

Factor5 designed ObjectIDs to used in a polymorphic manner. The top 2 bits of the ID are used
to differentiate between SoundMacros, Keymaps, and Layers. If the ID passes a mask of 0x4000,
the object is a ''Keymap''. If the ID passes a mask of 0x8000, the object is a ''Layer''.
Otherwise, the object is assumed to be a ''SoundMacro''. ''Tables'' don't require this type of
polymorphism due to the context in which they are accessed.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x36
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x37
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x38
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x39
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x65
| SET_VAR
| Ctrl
| A =
| colspan="1" {{unknown|}}
| colspan="2" | Immediate
| colspan="2" {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values (although typically in MIDI range [0,127])

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

'''Note:''' Keymap and Layer IDs in these tables have their top 2 bits (indicating their type) masked off.
Keymaps must be OR'd with 0x4000 and Layers must be OR'd with 0x8000 in order to reconstruct the actual IDs.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

'''Note:''' The drum table is accessed when the MIDI channel is 10, otherwise the normal table is accessed.

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 1
| '''Definite Key'''; The default pitch - usually 0x3C (MIDI C4)
|-
| 0x9
| 1
| '''Padding'''
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Aruki will dump all sound effects contained in a given AGSC file.

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

AGSC (File Format)

2018-08-16T20:56:43Z

Jackoalan: /* Normal / Drum Page Entry */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID'''.

Factor5 designed ObjectIDs to used in a polymorphic manner. The top 2 bits of the ID are used
to differentiate between SoundMacros, Keymaps, and Layers. If the ID passes a mask of 0x4000,
the object is a ''Keymap''. If the ID passes a mask of 0x8000, the object is a ''Layer''.
Otherwise, the object is assumed to be a ''SoundMacro''. ''Tables'' don't require this type of
polymorphism due to the context in which they are accessed.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x36
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x37
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x38
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x39
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x65
| SET_VAR
| Ctrl
| A =
| colspan="1" {{unknown|}}
| colspan="2" | Immediate
| colspan="2" {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values (although typically in MIDI range [0,127])

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

'''Note:''' Keymap and Layer IDs in these tables have their top 2 bits (indicating their type) masked off.
Keymaps must be OR'd with 0x4000 and Layers must be OR'd with 0x8000 in order to reconstruct the actual IDs.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

''Note:'' The drum table is accessed when the MIDI channel is 10, otherwise the normal table is accessed.

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 1
| '''Definite Key'''; The default pitch - usually 0x3C (MIDI C4)
|-
| 0x9
| 1
| '''Padding'''
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Aruki will dump all sound effects contained in a given AGSC file.

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

AGSC (File Format)

2018-08-16T20:54:09Z

Jackoalan: /* SFX Entry */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID'''.

Factor5 designed ObjectIDs to used in a polymorphic manner. The top 2 bits of the ID are used
to differentiate between SoundMacros, Keymaps, and Layers. If the ID passes a mask of 0x4000,
the object is a ''Keymap''. If the ID passes a mask of 0x8000, the object is a ''Layer''.
Otherwise, the object is assumed to be a ''SoundMacro''. ''Tables'' don't require this type of
polymorphism due to the context in which they are accessed.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x36
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x37
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x38
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x39
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x65
| SET_VAR
| Ctrl
| A =
| colspan="1" {{unknown|}}
| colspan="2" | Immediate
| colspan="2" {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values (although typically in MIDI range [0,127])

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

'''Note:''' Keymap and Layer IDs in these tables have their top 2 bits (indicating their type) masked off.
Keymaps must be OR'd with 0x4000 and Layers must be OR'd with 0x8000 in order to reconstruct the actual IDs.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 1
| '''Definite Key'''; The default pitch - usually 0x3C (MIDI C4)
|-
| 0x9
| 1
| '''Padding'''
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Aruki will dump all sound effects contained in a given AGSC file.

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

AGSC (File Format)

2018-08-16T20:48:51Z

Jackoalan: /* Sample ID / Table / Keymap / Layer Tables */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID'''.

Factor5 designed ObjectIDs to used in a polymorphic manner. The top 2 bits of the ID are used
to differentiate between SoundMacros, Keymaps, and Layers. If the ID passes a mask of 0x4000,
the object is a ''Keymap''. If the ID passes a mask of 0x8000, the object is a ''Layer''.
Otherwise, the object is assumed to be a ''SoundMacro''. ''Tables'' don't require this type of
polymorphism due to the context in which they are accessed.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x36
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x37
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x38
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x39
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x65
| SET_VAR
| Ctrl
| A =
| colspan="1" {{unknown|}}
| colspan="2" | Immediate
| colspan="2" {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values (although typically in MIDI range [0,127])

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

'''Note:''' Keymap and Layer IDs in these tables have their top 2 bits (indicating their type) masked off.
Keymaps must be OR'd with 0x4000 and Layers must be OR'd with 0x8000 in order to reconstruct the actual IDs.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 2
| '''Definite Key'''; The default pitch (usually 0x3C00... the second byte may possibly be the MIDI channel)
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Aruki will dump all sound effects contained in a given AGSC file.

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

AGSC (File Format)

2018-08-16T20:44:41Z

Jackoalan: /* ObjectID */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID'''.

Factor5 designed ObjectIDs to used in a polymorphic manner. The top 2 bits of the ID are used
to differentiate between SoundMacros, Keymaps, and Layers. If the ID passes a mask of 0x4000,
the object is a ''Keymap''. If the ID passes a mask of 0x8000, the object is a ''Layer''.
Otherwise, the object is assumed to be a ''SoundMacro''. ''Tables'' don't require this type of
polymorphism due to the context in which they are accessed.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x36
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x37
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x38
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x39
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x65
| SET_VAR
| Ctrl
| A =
| colspan="1" {{unknown|}}
| colspan="2" | Immediate
| colspan="2" {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values (although typically in MIDI range [0,127])

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 2
| '''Definite Key'''; The default pitch (usually 0x3C00... the second byte may possibly be the MIDI channel)
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Aruki will dump all sound effects contained in a given AGSC file.

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

CSNG (File Format)

2018-08-16T20:36:07Z

Jackoalan: /* Delta Time RLE */

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time Encoding=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
value to store the delta times. In case of a delta time greater than 65535, no-op commands
with a 65535 delta time are inserted into the command stream until the target time is attained.

In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTime(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
next = streamIn.PeekU16()
if next == 0:
# Automatically consume no-op and continue accumulating time value
total += 0xffff
streamIn.seekAhead(2)
continue
total += term
return total
</syntaxhighlight>

=====No-Op Command=====

When the two bytes following the delta-time are both zero, this is a no-op command.

As mentioned before, no-ops are useful for accumulating delta times greater than 65535.

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of
(delta-tick, delta-value) pairs. The delta times are encoded as unsigned 7/15 bit values
and the delta values are signed 7/15-bit values. The values are promoted to 15-bit if they
exceed their 7-bit range. In this case, the highest bit is set on the first byte in the pair
(0x80). The decoder must track the absolute time and value, summing each consecutive update
for the current time/values.

Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
with a zeroed value delta are inserted.

<syntaxhighlight lang="python" line="1">
def SignExtend7(value):
return (value & 0x3f) - (value & 0x40)

def SignExtend15(value):
return (value & 0x3fff) - (value & 0x4000)

def DecodeSignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return SignExtend15(byte1 | ((byte0 & 0x7f) << 8))
else:
return SignExtend7(byte0)

def DecodeUnsignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return byte1 | ((byte0 & 0x7f) << 8)
else:
return byte0

def DecodeDeltaPair(streamIn):
ret = [0,0]
while ret[1] == 0:
ret[0] += DecodeUnsignedValue(streamIn)
ret[1] = DecodeSignedValue(streamIn)
return ret
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

CSNG (File Format)

2018-08-16T20:31:45Z

Jackoalan: /* Continuous Pitch / Modulation Data */

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time RLE=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
value to store the delta times. In case of a delta time greater than 65535, no-op commands
with a 65535 delta time are inserted into the command stream until the target time is attained.

In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTime(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
next = streamIn.PeekU16()
if next == 0:
# Automatically consume no-op and continue accumulating time value
total += 0xffff
streamIn.seekAhead(2)
continue
total += term
return total
</syntaxhighlight>

=====No-Op Command=====

When the two bytes following the delta-time are both zero, this is a no-op command.

As mentioned before, no-ops are useful for accumulating delta times greater than 65535.

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of
(delta-tick, delta-value) pairs. The delta times are encoded as unsigned 7/15 bit values
and the delta values are signed 7/15-bit values. The values are promoted to 15-bit if they
exceed their 7-bit range. In this case, the highest bit is set on the first byte in the pair
(0x80). The decoder must track the absolute time and value, summing each consecutive update
for the current time/values.

Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
with a zeroed value delta are inserted.

<syntaxhighlight lang="python" line="1">
def SignExtend7(value):
return (value & 0x3f) - (value & 0x40)

def SignExtend15(value):
return (value & 0x3fff) - (value & 0x4000)

def DecodeSignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return SignExtend15(byte1 | ((byte0 & 0x7f) << 8))
else:
return SignExtend7(byte0)

def DecodeUnsignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return byte1 | ((byte0 & 0x7f) << 8)
else:
return byte0

def DecodeDeltaPair(streamIn):
ret = [0,0]
while ret[1] == 0:
ret[0] += DecodeUnsignedValue(streamIn)
ret[1] = DecodeSignedValue(streamIn)
return ret
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

CSNG (File Format)

2018-08-16T20:30:01Z

Jackoalan: Fix pitch/mod encoding scheme

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time RLE=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
value to store the delta times. In case of a delta time greater than 65535, no-op commands
with a 65535 delta time are inserted into the command stream until the target time is attained.

In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTime(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
next = streamIn.PeekU16()
if next == 0:
# Automatically consume no-op and continue accumulating time value
total += 0xffff
streamIn.seekAhead(2)
continue
total += term
return total
</syntaxhighlight>

=====No-Op Command=====

When the two bytes following the delta-time are both zero, this is a no-op command.

As mentioned before, no-ops are useful for accumulating delta times greater than 65535.

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of
(delta-tick, delta-value) pairs. The delta times are encoded as unsigned 7/15 bit values
and the delta values are signed 7/15-bit values. The values are promoted to 15-bit if they
exceed their 7-bit range. In this case, the highest bit is set on the first byte in the pair
(0x80). The decoder must track the absolute time and value, summing each consecutive update
for the current time/values.

Similar to the command stream, when the delta time exceeds 15 bit range (>32767), extra pairs
with a value delta are inserted.

<syntaxhighlight lang="python" line="1">
def SignExtend7(value):
return (value & 0x3f) - (value & 0x40)

def SignExtend15(value):
return (value & 0x3fff) - (value & 0x4000)

def DecodeSignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return SignExtend15(byte1 | ((byte0 & 0x7f) << 8))
else:
return SignExtend7(byte0)

def DecodeUnsignedValue(streamIn):
byte0 = streamIn.ReadU8()
if byte0 & 0x80:
byte1 = streamIn.ReadU8()
return byte1 | ((byte0 & 0x7f) << 8)
else:
return byte0

def DecodeDeltaPair(streamIn):
ret = [0,0]
while ret[1] == 0:
ret[0] += DecodeUnsignedValue(streamIn)
ret[1] = DecodeSignedValue(streamIn)
return ret
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

CSNG (File Format)

2018-08-16T20:04:55Z

Jackoalan: Clarify nature of delta time encoding

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time RLE=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a fixed 16-bit
value to store the delta times. In case of a delta time greater than 65535, no-op commands
with a 65535 delta time are inserted into the command stream until the target time is attained.

In a theoretical Python streaming API, the delta time can be decoded with no-ops automatically consumed like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTime(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
next = streamIn.PeekU16()
if next == 0:
total += 0xffff
streamIn.seekAhead(2)
continue
total += term
return total
</syntaxhighlight>

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of RLE-compressed
(delta-tick, delta-value) pairs, decoding to signed 16-bit precision. The decoder must track
the absolute time and value, summing each consecutive update for the current time/values.

The algorithm for this RLE is different than the delta-time one for commands. It may
scale down to a single byte if able.

<syntaxhighlight lang="python" line="1">
def DecodeRLE(streamIn):
# high-bit shift-trigger RLE, limited to 2 bytes
term = streamIn.ReadU8()
total = term & 0x7f
if term & 0x80:
total = total * 256 + streamIn.ReadU8()
return total

def DecodeContinuousRLE(streamIn, isValue):
total = 0
while True:
# 1-2 byte RLE accumulated within continuable RLE
term = DecodeRLE(streamIn)
if term == 0x8000:
total += 0xffff
dummy = streamIn.ReadU8()
continue
total += term

# values are signed deltas;
# extending into the high-half of 15-bit precision
if isValue:
if total >= 0x4000:
return total - 0xffff
else:
return total

# times are always forward-deltas
return total
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

VISI (MREA Section)

2018-06-28T03:31:45Z

Jackoalan:

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Has Actors
| If set, the game will resolve script entity IDs for the PVS lookup
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Total number of area lights encoded in octree leaves.
|-
| u32
| 2nd Layer Light Count
| Lights within total that are in the 2nd BABEDEAD layer.
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective. 2nd layer lights are listed first.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree. '''Note:''' the coordinates of the AABB are in local area space (i.e. inverse-transformed with the matrix in the MREA header).
|-
| u32
| Total visibility object count
| Number of objects per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light object count
| Number of objects within total that are lights.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.

Finally are the bits relating lights in order of the BABEDEAD section of the MREA. The 2nd layer lights are related first. Each light encodes 2-bits apiece,
with the following enum represented:

{| class="wikitable"
! Value
! Description
|-
| 0
| Not Visible
|-
| 1
| Visible
|-
| 2
| Outside Octree Bounds
|}

PART (File Format)

2018-05-13T01:51:31Z

Jackoalan: RSOP description

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''PART''' [[Particle Script|particle script]] format is used to configure ''particle effects''.

Particles are the most widely-used effect in ''Metroid Prime'', with approximately
3,500 unique scripts across the [[PAK_(Metroid_Prime)|PAK archives]].
Each script configures a complete ''particle system'' that may draw into the scene.

The particle system is configurable to generate many visual effects:

* Flames and smoke
* Floating embers
* Water splashes/drips
* Dust and dirt in windy conditions
* Volumetric light "shimmers"
* Energy/plasma discharges
* Many others

The concept behind the particle system is quite simple: lots of
view-aligned (camera-facing) quads with a texture-image
are emitted, positioned, rotated, sized, colored, etc... according to the
parameters in the particle script.

== Particle System ==

The ''particle system'' ties together all procedures necessary to host an ''emitter''
and specifies the rate at which new particles should be created. New particles have a predetermined
''lifetime'' (in frames) set by the system, and the emitter initializes the position and velocity of these particles.
The system continuously updates all currently-living particles that it's created. This includes updating
properties like ''position'', ''velocity'', ''color'', ''size'' and ''view-rotation''.

=== Child Systems ===

Particle systems may also host ''child systems'' which are timed and positioned within the parent's reference.
Not only does this include other PART systems, but [[SWHC (File Format)|SWHC]] and [[ELSC (File Format)|ELSC]]
systems may be parented as well.

A good example of this is the ''flamethrower's'' system, which composes flame
particles with a trailing SWHC and small cinders from a separate PART.

=== Line Mode ===

When the <code>LINE</code> property is activated, particles are rendered as ''lines'' rather than quads.

The usual 3D particle position is used as the ''trailing-point'' of the line, with the ''leading-point'' computed
via positional-differential, scaled by other parameters. Lines sample textures diagonally as a single-texel strip,
allowing for gradients to be applied via spherical or diagonal ramp-textures.

=== Model Mode ===

When the <code>PMDL</code> property is provided with a [[CMDL (File Format)|CMDL]], particles are rendered
using that ''model'', in addition to the quad. Alternatively, <code>PMUS</code> generates a quad transformed
as if it were a model (non view aligned).

Model-based particles have a whole separate suite of properties for controlling local-transformation and color.
Most of the properties involving positioning and transforms from the client systems are shared from the
normal quad-mode.

Many weapon effects, notably the "sphere" of the charge-beam, are accomplished using particle models.

== Particle Instance ==

For each frame, each particle does the following primary tasks:

* Determines if particle's lifetime has finished, removing it from the scene and releasing its resources for newly created particles to use
* Invokes all [[Particle Script#Mod_Vector_Elements|velocity/position sources]]; advancing position 1/60th of a second
* Evaluates local transforms
** Size
** View-aligned rotation
** View-aligned offset
* Evaluates particle color (shader-multiplied with texture-image)

== Emitter ==

''Main article: [[Particle Script#Emitter_Elements|Emitter Elements]]''

Each particle-system employs a single ''emitter'' context.
The system generates a specified number of particles each frame;
the emitter initializing the position and velocity-vector for each.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>GPSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|PSIV|VectorElement|System Initial Velocity|System Init|Defines the initial velocity vector which moves the entire system in local orientation (may be overridden by <code>PSVM</code>)|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|PSVM|ModVectorElement|System Velocity Mod|Post Particles Update|Mod Vector which influences the position and velocity of the entire system in local space|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|PSOV|VectorElement|System Orientation Velocity|Post Particles Update|Angular velocity (in degrees/frame) of the system's orientation|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|PSLT|IntElement|System Lifetime|System Init|Count of frames that the system generates new particles|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PSWT|IntElement|System Warmup Time|Warmup-Phase Update|Count of frames that the particle system virtually updates itself within one initial frame; exiting the warmup phase afterwards|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PSTS|RealElement|System Time Scale|Pre Particles Update|Factor that redefines the second for the system, including the rate at which the system's frame count is incremented. 1.0 is native 60-fps. 0.5 causes every other frame to skip updates, slowing down and making the motion "choppy". 2.0 causes 2 updates every frame, speeding up.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|POFS|VectorElement|Particle Offset|System Init, Post Particles Update|Vector that offsets all particles in world space|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SEED|IntElement|Random Seed|System Init|Value used to initialize the [[wikipedia:Linear congruential generator|LCG]] seed state used within the system's update and render cycles (default 99)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LENG|RealElement|Line Length|Line Particle Creation, Line Particle Update|Length of <code>LINE</code> particles, scaled according to <code>FXLL</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|WIDT|RealElement|Line Width|Line Particle Render|Width of <code>LINE</code> particles in viewport pixels|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|MAXP|IntElement|Max Particles|System Init, Pre Particles Update|Max count of particles allowed to live at once. No new particles created if there are already this many active particles.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|GRTE|RealElement|Generation Rate|Pre Particles Update|Count of particles to create each frame. Remainder value is accumulated for the next update cycle.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|COLR|ColorElement|Color|Particle Creation, Particle Update|Color to multiply with particle's texture|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LTME|IntElement|Lifetime|Particle Creation|Count of frames the about-to-be-created particle lives|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|ILOC|VectorElement|Particle Emit Location|Particle Creation|Position to initialize particle in local space (replaced by <code>EMTR</code>)|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IVEC|VectorElement|Particle Emit Velocity|Particle Creation|Velocity to initialize particle in local space (replaced by <code>EMTR</code>)|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EMTR|EmitterElement|Emitter|Particle Creation|[[Particle Script#Emitter Elements|Modular data source]] for initializing position and velocity of new particles|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LINE|bool|Line Mode|System Init|Render particles as lines instead of quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|FXLL|bool|Line Mode|System Init|Scale leading point of line as the exact value of <code>LENG</code>, rather than multiplying <code>LENG</code> with the position-differential|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|AAPH|bool|Additive Alpha|System Init|Set up blending of quads and lines with source factor of <code>GX_BL_SRCALPHA</code> and destination factor of <code>GX_BL_ONE</code> as opposed to <code>GX_BL_SRCALPHA</code> and <code>GX_BL_INVSRCALPHA</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|ZBUF|bool|Z-buffer Write|System Init|Perform rendering while writing into the z-buffer to ensure later-drawn objects don't occlude particles if positioned behind them|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SORT|bool|View-space Sort|System Init|Sort particles by their z-coordinate in view-space before drawing, which is essential for proper alpha blending (although mathematically unnecessary when <code>AAPH</code> is active)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LIT_|bool|{{unknown|Unknown}}|System Init|Unused in demo|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|ORNT|bool|Orient To Origin|System Init|''New in retail'' - Simultaneously orients particle instances toward the local origin and view-point via cross-product. <code>ROTA</code> is used to control the width of quads in this mode, while <code>SIZE</code> controls the length.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|RSOP|bool|Right Vector Scaled on Particle|System Init|''New in retail'' - The right vector (particle width) is proportionally scaled with length|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|MBLR|bool|Motion Blur|System Init|Enables sub-positional overdraw of each particle instance between its previous position and new position each frame; draw count controlled by <code>MBSP</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMAB|bool|Model Additive Alpha|System Init|Equivalent of <code>AAPH</code> for models and <code>PMUS</code> quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMUS|bool|Model Unoriented Square|System Init|Draws a 1x1 quad in the XZ-plane in place of a <code>PMDL</code> model|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMOO|bool|Model Object Orientation|System Init|Includes client-supplied orientation in model's transform chain (after <code>PMRT</code>). Unlike other <code>bool</code> properties, this property is enabled by default|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|VMDn|bool|Local Vector Mod [1-4]|System Init|Applies mod vectors <code>VELn</code> in system local-space rather than world-space|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|CIND|bool|Colored Indirect Texture|System Init|When <code>TIND</code> is active, texels copied from the underlying framebuffer are multiplied with the texels in <code>TEXR</code> (rather than added). The alpha component is ''always'' multiplied.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|OPTS|bool|Optional System|System Init|When a client system constructs a generator instance, it has the option to filter out child systems at any level that aren't essential to the effect. The exclusion is a mutual decision between the client and the particle description via this property.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|MBSP|IntElement|Motion Blur Samples|Pre Particles Update|When <code>MBLR</code> is active, this is the number of times the position differential of each particle instance is subdivided for overdraw|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SIZE|RealElement|Particle Size|Particle Creation, Particle Update|Proportional scale (length and width) of particle quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|ROTA|RealElement|Particle View-Rotation|Particle Creation, Particle Update|View-aligned counterclockwise-rotation of particle instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|TEXR|UVElement|Particle Texture|Particle Creation, Particle Update|Particle texture map and UV coordinate source|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|TIND|UVElement|Indirect Particle Texture|Particle Creation, Particle Update|Indirect texture map and UV coordinate source. Setting this property enables framebuffer->texture copies of the rectangular region behind particle instances. These texels are warped using coordinates defined in the texels of the IA texture in this property.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMDL|[[CMDL (File Format)|CMDL]]|Particle Model|System Init|Render particle instances using this model, in addition to quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMOP|VectorElement|Particle Model Pre-Offset|Particle Model Render|Translate models using this vector ''before'' transforming normally|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMRT|VectorElement|Particle Model Rotate|Particle Model Render|Rotate models using these euler angles (in degrees, ZYX order)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMSC|VectorElement|Particle Model Scale|Particle Model Render|Scale models using this (potentially non-proportional) vector|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PMCL|ColorElement|Particle Model Color|Particle Model Render|Multiply textured model color with this color|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|VELn|ModVectorElement|Particle Mod Vectors [1-4]|Particle Update|Up to 4 [[Particle Script#Mod Vector Elements|mod vectors]] invoked (in order) on each particle instance for each frame; influencing position and velocity|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|ICTS|PART|Counted Child System|System Init|Child particle system to spawn multiple instances of|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|NCSY|IntElement|Counted Child System Count|System Init|Count of <code>ICTS</code> systems to spawn (default 1)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|CSSD|IntElement|Counted Child System Frame|System Init|Frame index to spawn <code>ICTS</code> instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|IDTS|PART|Done Child System|System Init|Child particle system to spawn multiple instances of when parent system's lifetime finishes|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|NDSY|IntElement|Done Child System Count|System Init|Count of <code>IDTS</code> systems to spawn (default 1)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|IITS|PART|Interval Child System|System Init|Child particle system to spawn at regular intervals|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|PISY|IntElement|Interval Child System Frame Interval|System Init|Frame interval to emit <code>IITS</code> instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SISY|IntElement|Interval Child System Start Frame|System Init|Frame index to start emitting <code>IITS</code> instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|KSSM|[[#SpawnSystemKeyframeData|SpawnSystemKeyframeData]]|Timed-Spawn Particle Systems|System Init|List of start-frame events and corresponding child systems to spawn|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh System|System Init|Child swoosh system parented to this system|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SSSD|IntElement|Child Swoosh System Start Frame|System Init|Frame index to start emitting <code>SSWH</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SSPO|VectorElement|Child Swoosh System Offset|System Init|Offset supplied as swoosh system's translation|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SELC|[[ELSC (File Format)|ELSC]]|Child Electric System|System Init|Child electric system parented to this system|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SESD|IntElement|Child Electric System Start Frame|System Init|Frame index to start emitting <code>SELC</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|SEPO|VectorElement|Child Electric System Offset|System Init|Offset supplied as electric system's translation|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
|-
| '''LTYP'''
| style="font-family:monospace;" | IntElement
| System Light Type
| System Init
| Type of GX light to parent to system <ol start="0"><li>None (no light)</li><li>Custom (point)</li><li>Directional</li><li>Spot</li></ol>
| {{check}}
| {{check}}
| {{check}}
| {{check}}
| {{check}}
{{ParticlePropertyRow|LCLR|ColorElement|System Light Color|Post Particles Update|Diffuse color of GX light|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LINT|RealElement|System Light Intensity|Post Particles Update|Light intensity factor used for calculating falloff|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LOFF|VectorElement|System Light Offset|Post Particles Update|Light offset (not applicable to directional lights)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LDIR|VectorElement|System Light Direction|Post Particles Update|Light direction (not applicable to custom lights)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
|-
| '''LFOT'''
| style="font-family:monospace;" | IntElement
| System Light Falloff Type
| System Init
| Type of linear-attenuation equation to use for light <ol start="0"><li>Constant</li><li>Linear</li><li>Quadratic</li></ol>
| {{check}}
| {{check}}
| {{check}}
| {{check}}
| {{check}}
{{ParticlePropertyRow|LFOR|RealElement|System Light Falloff Radius|Post Particles Update|Falloff radius for linear-attenuation (not applicable to constant)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|LSLA|RealElement|System Light Cutoff Angle|Post Particles Update|Cutoff angle for angular-attenuation (only applicable to spot)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
{{ParticlePropertyRow|ADVn|RealElement|Advance Parameters [1-8]|Pre Particles Update|Parameters to compute per system update, values shared across all particle instances via <code>PAPn</code> real elements|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
|}

=== SpawnSystemKeyframeData ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| style="font-family:monospace;" | u32
| {{unknown|'''Unknown'''}}
|
|-
| style="font-family:monospace;" | u32
| {{unknown|'''Unknown'''}}
|
|-
| style="font-family:monospace;" | u32
| End Frame
| Final frame index where a system is spawned
|-
| style="font-family:monospace;" | u32
| {{unknown|'''Unknown'''}}
|
|-
| style="font-family:monospace;" | u32
| List Count
|
|-
| style="font-family:monospace;" | {u32 ''frame'', u32 ''infoCount'', [[#SpawnSystemKeyframeInfo|SpawnSystemKeyframeInfo]][infoCount]}[listCount]
| Lists
| Pairs of ''frame index'' and sequence of ''SpawnSystemKeyframeInfo'' for grouping systems that start on the same frame
|}

=== SpawnSystemKeyframeInfo ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| style="font-family:monospace;" | PART
| Child System ID
|
|-
| style="font-family:monospace;" | u32
| {{unknown|'''Unknown'''}}
|
|-
| style="font-family:monospace;" | u32
| {{unknown|'''Unknown'''}}
|
|-
| style="font-family:monospace;" | u32
| {{unknown|'''Unknown'''}}
|
|}

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

UV Animations

2018-01-15T01:56:43Z

Jackoalan: Minor Mode6 translation scale fix

'''UV animations''' are used to animate texture coordinates. They're present in the material data of the Metroid Prime trilogy and Donkey Kong Country Returns. There are 13 animation types across those four games.

{{research|moderate|Modes 8/10/11/12/13 are unknown}}

__TOC__

== Format ==

UV animations generally contain an int indicating what animation type they are, followed by float parameters. The number of parameters depends on the animation mode; some modes don't have any parameters while some have as many as 9.

=== Metroid Prime 1/2 ===

At the end of the material data, there's a 32-bit animations size value, then an animation count. Each animation is structured as:

{| class="wikitable"
! Offset
! Type
! Size
! Description
|-
| 0x0
| u32
| 4
| '''Animation type'''
|-
| 0x4
| float[]
| -
| '''Parameters'''
|}

=== Metroid Prime 3/Donkey Kong Country Returns ===

Animations are located at the end of each PASS section. There's no animation count; instead, one animation can be supplied per pass and can be directly associated with that pass. Like Prime 1, the animation data follows a 32-bit animations size value.

{| class="wikitable"
! Offset
! Type
! Size
! Description
|-
| 0x0
| u16
| 2
| {{unknown|'''Unknown'''}}
|-
| 0x2
| u16
| 2
| {{unknown|'''Unknown'''}}
|-
| 0x4
| u32
| 4
| '''Animation Mode'''
|-
| 0x8
| float[]
| -
| '''Parameters'''
|}

== Animation Modes ==

{| class="wikitable"
! Mode
! Name
! Params
! MP1
! MP2
! MP3
! DKCR
|-
| 0
| [[#Mode_0:_Inverse ModelView Matrix (No Translation)|Inverse ModelView Matrix (No Translation)]]
| 0
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 1
| [[#Mode_1:_Inverse ModelView Matrix|Inverse ModelView Matrix]]
| 0
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 2
| [[#Mode_2:_UV Scroll|UV Scroll]]
| 4
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 3
| [[#Mode_3:_Rotation|Rotation]]
| 2
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 4
| [[#Mode_4/5:_Horizontal/Vertical_Filmstrip|Horizontal Filmstrip]]
| 4
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 5
| [[#Mode_4/5:_Horizontal/Vertical_Filmstrip|Vertical Filmstrip]]
| 4
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 6
| [[#Mode_6:_Model Matrix|Model Matrix]]
| 0
| {{check}}
| {{check}}
| {{check}}
| {{nocheck}}
|-
| 7
| [[#Mode_7:_Cylinder Environment|Cylinder Environment]]
| 2
| {{check}}
| {{check}}
| {{check}}
| {{check}}
|-
| 8
| {{unknown|Unknown mode}}
| 9
| {{nocheck}}
| {{nocheck}}
| {{check}}
| {{check}}
|-
| 10
| {{unknown|[[#Mode_10:_Another_reflection_mode|Another reflection mode]]}}
| 0
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| 11
| {{unknown|Unknown mode}}
| 2
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| 12
| {{unknown|Unknown mode}}
| 2
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
| 13
| {{unknown|Unknown mode}}
| 2
| {{nocheck}}
| {{nocheck}}
| {{nocheck}}
| {{check}}
|-
|}

For all of the following modes, ''s'' refers to ''seconds mod 900''.

==== Mode 0: Inverse ModelView Matrix (No Translation) ====

This mode is commonly used with vertex normals to simulate reflective surfaces using spheremaps that move with the camera. It takes no parameters, and will generate both a texture matrix and a post-transform matrix. Translation is ignored.

The texture matrix is calculated like this. Note that the multiplication of the view matrix by the model matrix should be modified slightly rather than being a straight multiplication to ignore translation on the model matrix. (The game uses a function called MultiplyIgnoreTranslation for this.)

<pre>texmtx = inverse(ViewMatrix) * ModelMatrix;
texmtx[0][3] = texmtx[1][3] = texmtx[2][3] = 0;</pre>

The post-transform matrix is a constant value. The purpose of it is to adjust the normalized texture coordinates so that they range from 0 to 1.

<pre>0.5, 0.0, 0.0, 0.5,
0.0, 0.0, 0.5, 0.5,
0.0, 0.0, 0.0, 1.0</pre>

==== Mode 1: Inverse ModelView Matrix ====

This mode is nearly identical to mode 0; the only difference is that translation is left as-is. The multiplication of the view matrix by the model matrix actually is a straight multiplication in this mode, and the translation values on the texture matrix aren't set to 0.

==== Mode 2: UV Scroll ====

This mode is used to scroll both U and V at the same time. It will only generate a texture matrix. It has four float parameters: ''offsetA'', ''offsetB'', ''scaleA'', and ''scaleB''.

<pre>uOffset = (s * scaleA) + offsetA;
vOffset = (s * scaleB) + offsetB;</pre>

==== Mode 3: Rotation ====

This mode rotates the texture. It will only generate a texture matrix. It has two float parameters: ''offset'' and ''scale''.

<pre>float angle = (s * scale) + offset;
float acos = cos(angle);
float asin = sin(angle);
float translateX = (1.0 - (acos - asin)) * 0.5;
float translateY = (1.0 - (asin + acos)) * 0.5;</pre>

The resulting texture matrix is laid out as:

<pre>acos, -asin, 0.0, translateX,
asin, acos, 0.0, translateY,
0.0, 0.0, 1.0, 0.0</pre>

==== Mode 4/5: Horizontal/Vertical Filmstrip ====

These modes can be used to create a filmstrip-like effect. The texture steps a set distance each animation frame, rather than the scroll being smoothly interpolated every game frame. The same calculation is done for both modes, with the only difference being whether the calculated offset is applied to the U or V coordinate. It will only generate a texture matrix. There are four float parameters: ''scale'', ''numFrames'', ''step'', and ''offset''.

The animation is made up of a number of pseudo-frames, where ''step'' controls the amount that the texture scrolls by each frame, and ''numFrames'' sets how many frames are iterated through before resetting back to 0. ''scale'' roughly controls animation playback speed, and ''offset'' modifies the time input value.

<pre>float value = step * scale * (offset + s);
float uv_offset = (float)(short)(float)(numFrames * fmod(value, 1.0f)) * step;</pre>

==== Mode 6: Model Matrix ====

This mode is similar to modes 0 and 1 in that it simulates reflective surfaces, but it only takes the model matrix into account, which means camera movement doesn't affect the reflection. It takes no parameters and it generates both a texture matrix and a post-transform matrix.

The texture matrix is simply the model matrix, with the translation values set to 0. The post-transform matrix is set to the following:

<pre>0.5, 0.0, 0.0, ModelMatrix[0][3] * 0.050000001,
0.0, 0.0, 0.5, ModelMatrix[1][3] * 0.050000001</pre>

==== Mode 7: Cylinder Environment ====

Mode 7 takes two parameters and generates both a texture matrix and a post-transform matrix, projecting the UVs onto the surface of a cylinder, used almost exclusively on pipes.

The texture matrix is generated the same way as in mode 0; translation is ignored.

<pre>texmtx = inverse(ViewMatrix) * ModelMatrix;
texmtx[0][3] = texmtx[1][3] = texmtx[2][3] = 0;</pre>

The post-transform matrix is where it gets a little complicated. A little math is required to calculate some values:

<pre>float xy = ((ViewMatrix[0][3] + ViewMatrix[1][3]) * 0.025f * ParamB;
xy = (xy - (int) xy); // This truncates the integer portion of the value, leaving only the fractional part (mantissa).

float z = ViewMatrix[2][3] * 0.05f * ParamB;
z = (z - (int) z);

float halfA = ParamA * 0.5f;</pre>

The post-transform matrix is then constructed as:

<pre>halfA, 0.0f, 0.0f, xy,
0.0f, 0.0f, halfA, z,
0.0f, 0.0f, 0.0f, 1.0f</pre>

==== Mode 10: Another reflection mode ====

This one needs more research done, but the only thing the game does with this mode is load this post-transform matrix:

<pre>0.5, 0.0, 0.0, 0.5,
0.0, 0.0, 0.5, 0.5,
0.0, 0.0, 0.0, 1.0</pre>

The function of this matrix is to transform normalized texture coords so that they range from 0 to 1, instead of from -1 to 1. This mode seems to work well with mode 0's settings, though, so it's possible that the game is creating a texture matrix somewhere else. This needs some looking into.

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

ELSC (File Format)

2017-06-11T06:08:55Z

Jackoalan: /* Properties */

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''ELSC''' [[Particle Script|particle script]] format is used to build electrical effects in the ''Metroid Prime'' series.
Electrical effects are commonly used to dynamically draw lightning and electrical arcs.

Whenever a new ''particle instance'' is generated, a [[wikipedia:Bézier curve|Bézier curve]] is subdivided into segments.
The central vertices are then displaced using a [[wikipedia:Fractal|random fractal algorithm]].
The instance's color and line-width is updated over its lifetime.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>ELSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|LIFE|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SLIF|IntElement|Segment Lifetime|Particle Creation|Count of frames for newly generated instance to last|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GRAT|RealElement|Generation Rate|System Update|Count of particles to generate per frame; remainder is accumulated across updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SCNT|IntElement|Instance Count|System Init|Maximum count of particle instances and child generators for system|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSEG|IntElement|Segment Count|System Init|Maximum count of line segments per instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Swoosh Color|Particle Creation and Update|Modulation color evaluated for swoosh-based instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IEMT|EmitterElement|Initial Emitter|Particle Creation|Position source for instance start-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|FEMT|EmitterElement|Final Emitter|Particle Creation|Position source for instance end-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPL|RealElement|Length Amplitude|Particle Creation|Randomized coefficient of fractal displacement as product of recursive segment length|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPD|RealElement|Direct Amplitude|Particle Creation|Separately randomized coefficient of fractal displacement|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD1|RealElement|Line Width 1|Particle Creation and Update|Enables line 1 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD2|RealElement|Line Width 2|Particle Creation and Update|Enables line 2 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD3|RealElement|Line Width 3|Particle Creation and Update|Enables line 3 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL1|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 1's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL2|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 2's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL3|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 3's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh|System Init|Use swoosh system to draw effect; computed fractal points are set into swoosh's history; Omitting LWD* properties will only draw the swoosh|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GPSM|[[PART (File Format)|PART]]|Start Child Particle|System Init|Draw particle system positioned at instance's start-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EPSM|[[PART (File Format)|PART]]|End Child Particle|System Init|Draw particle system positioned at instance's end-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZERY|bool|Zero Y|Particle Creation|Zero Y component of newly created particle vertices|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

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

ELSC (File Format)

2017-06-11T05:55:29Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''ELSC''' [[Particle Script|particle script]] format is used to build electrical effects in the ''Metroid Prime'' series.
Electrical effects are commonly used to dynamically draw lightning and electrical arcs.

Whenever a new ''particle instance'' is generated, a [[wikipedia:Bézier curve|Bézier curve]] is subdivided into segments.
The central vertices are then displaced using a [[wikipedia:Fractal|random fractal algorithm]].
The instance's color and line-width is updated over its lifetime.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>ELSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|LIFE|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SLIF|IntElement|Segment Lifetime|Particle Creation|Count of frames for newly generated instance to last|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GRAT|RealElement|Generation Rate|System Update|Count of particles to generate per frame; remainder is accumulated across updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SCNT|IntElement|Instance Count|System Init|Maximum count of particle instances and child generators for system|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSEG|IntElement|Segment Count|System Init|Maximum count of line segments per instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Swoosh Color|Particle Creation and Update|Modulation color evaluated for swoosh-based instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IEMT|EmitterElement|Initial Emitter|Particle Creation|Position source for instance start-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|FEMT|EmitterElement|Final Emitter|Particle Creation|Position source for instance end-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPL|RealElement|Length Amplitude|Particle Creation|Randomized coefficient of fractal displacement as product of segment count|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPD|RealElement|Direct Amplitude|Particle Creation|Separately randomized coefficient of fractal displacement|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD1|RealElement|Line Width 1|Particle Creation and Update|Enables line 1 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD2|RealElement|Line Width 2|Particle Creation and Update|Enables line 2 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD3|RealElement|Line Width 3|Particle Creation and Update|Enables line 3 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL1|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 1's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL2|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 2's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL3|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 3's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh|System Init|Use swoosh system to draw effect; computed fractal points are set into swoosh's history; Omitting LWD* properties will only draw the swoosh|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GPSM|[[PART (File Format)|PART]]|Start Child Particle|System Init|Draw particle system positioned at instance's start-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EPSM|[[PART (File Format)|PART]]|End Child Particle|System Init|Draw particle system positioned at instance's end-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZERY|bool|Zero Y|Particle Creation|Zero Y component of newly created particle vertices|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

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

ELSC (File Format)

2017-06-11T04:05:57Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''ELSC''' [[Particle Script|particle script]] format is used to build electrical effects in the ''Metroid Prime'' series.
Electrical effects are commonly used to dynamically draw lightning and electrical arcs.

An electrical ''particle instance'' is a single line subdivided into ''segments''. Whenever a new instance is generated, a
[[wikipedia:Bézier curve|Bézier curve]] is subdivided into segments. The central vertices are displaced using
a [[wikipedia:Fractal|random fractal algorithm]]. The instance's color and line-width is updated over its lifetime.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>ELSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|LIFE|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SLIF|IntElement|Segment Lifetime|Particle Creation|Count of frames for newly generated instance to last|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GRAT|RealElement|Generation Rate|System Update|Count of particles to generate per frame; remainder is accumulated across updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SCNT|IntElement|Instance Count|System Init|Maximum count of particle instances and child generators for system|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSEG|IntElement|Segment Count|System Init|Maximum count of line segments per instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Swoosh Color|Particle Creation and Update|Modulation color evaluated for swoosh-based instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IEMT|EmitterElement|Initial Emitter|Particle Creation|Position source for instance start-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|FEMT|EmitterElement|Final Emitter|Particle Creation|Position source for instance end-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPL|RealElement|Length Amplitude|Particle Creation|Randomized coefficient of fractal displacement as product of segment count|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPD|RealElement|Direct Amplitude|Particle Creation|Separately randomized coefficient of fractal displacement|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD1|RealElement|Line Width 1|Particle Creation and Update|Enables line 1 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD2|RealElement|Line Width 2|Particle Creation and Update|Enables line 2 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD3|RealElement|Line Width 3|Particle Creation and Update|Enables line 3 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL1|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 1's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL2|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 2's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL3|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 3's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh|System Init|Use swoosh system to draw effect; computed fractal points are set into swoosh's history; Omitting LWD* properties will only draw the swoosh|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GPSM|[[PART (File Format)|PART]]|Start Child Particle|System Init|Draw particle system positioned at instance's start-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EPSM|[[PART (File Format)|PART]]|End Child Particle|System Init|Draw particle system positioned at instance's end-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZERY|bool|Zero Y|Particle Creation|Zero Y component of newly created particle vertices|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

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

ELSC (File Format)

2017-06-11T04:01:59Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''ELSC''' [[Particle Script|particle script]] format is used to build electrical effects in the ''Metroid Prime'' series.
Electrical effects are commonly used to dynamically draw lightning and electrical arcs.

An electrical ''particle instance'' is a single line subdivided into ''segments''. Whenever a new instance is generated, a
[[wikipedia:Bézier curve|Bézier curve]] is subdivided into segments. The segment's central vertices are displaced using
a [[wikipedia:Fractal|random fractal algorithm]]. The instance's color and line-width is updated over its lifetime.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>ELSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|LIFE|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SLIF|IntElement|Segment Lifetime|Particle Creation|Count of frames for newly generated instance to last|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GRAT|RealElement|Generation Rate|System Update|Count of particles to generate per frame; remainder is accumulated across updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SCNT|IntElement|Instance Count|System Init|Maximum count of particle instances and child generators for system|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSEG|IntElement|Segment Count|System Init|Maximum count of line segments per instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Swoosh Color|Particle Creation and Update|Modulation color evaluated for swoosh-based instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IEMT|EmitterElement|Initial Emitter|Particle Creation|Position source for instance start-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|FEMT|EmitterElement|Final Emitter|Particle Creation|Position source for instance end-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPL|RealElement|Length Amplitude|Particle Creation|Randomized coefficient of fractal displacement as product of segment count|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPD|RealElement|Direct Amplitude|Particle Creation|Separately randomized coefficient of fractal displacement|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD1|RealElement|Line Width 1|Particle Creation and Update|Enables line 1 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD2|RealElement|Line Width 2|Particle Creation and Update|Enables line 2 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD3|RealElement|Line Width 3|Particle Creation and Update|Enables line 3 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL1|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 1's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL2|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 2's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL3|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 3's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh|System Init|Use swoosh system to draw effect; computed fractal points are set into swoosh's history; Omitting LWD* properties will only draw the swoosh|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GPSM|[[PART (File Format)|PART]]|Start Child Particle|System Init|Draw particle system positioned at instance's start-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EPSM|[[PART (File Format)|PART]]|End Child Particle|System Init|Draw particle system positioned at instance's end-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZERY|bool|Zero Y|Particle Creation|Zero Y component of newly created particle vertices|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

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

ELSC (File Format)

2017-06-11T04:01:26Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''ELSC''' [[Particle Script|particle script]] format is used to build electrical effects in the ''Metroid Prime'' series.
Electrical effects are commonly used to dynamically draw lightning and electrical arcs.

An electrical ''particle instance'' is a single line subdivided into ''segments''. Whenever a new instance is generated, a
[[wikipedia:Bézier curve|Bézier curve]] is subdivided into segments. The segment's central vertices are displaced using
a [[wikipedia:Fractal|random fractal algorithm]]. The instance's color and line-width is updated over its lifetime.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>ELSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|LIFE|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SLIF|IntElement|Segment Lifetime|Particle Creation|Count of frames for newly generated instance to last|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GRAT|RealElement|Generation Rate|System Update|Count of particles to generate per frame; remainder is accumulated across updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SCNT|IntElement|Instance Count|System Init|Maximum count of particle instances and child generators for system|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSEG|IntElement|Segment Count|System Init|Maximum count of line segments per instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Swoosh Color|Particle Creation and Update|Modulation color evaluated for swoosh-based instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IEMT|EmitterElement|Initial Emitter|Particle Creation|Position source for instance start-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|FEMT|EmitterElement|Final Emitter|Particle Creation|Position source for instance end-point; Velocity is used to form Bézier points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPL|RealElement|Length Amplitude|Particle Creation|Randomized coefficient of fractal displacement as product of segment count|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPD|RealElement|Direct Amplitude|Particle Creation|Separately randomized coefficient of fractal displacement|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD1|RealElement|Line Width 1|Particle Creation and Update|Enables line 1 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD2|RealElement|Line Width 2|Particle Creation and Update|Enables line 2 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD3|RealElement|Line Width 3|Particle Creation and Update|Enables line 3 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL1|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 1's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL2|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 2's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL3|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 3's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh|System Init|Use swoosh system to draw effect; computed fractal points are set into swoosh's history; Omitting LWD* properties will only draw the swoosh|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GPSM|[[PART (File Format)|PART]]|Start Child Particle|System Init|Draw particle system positioned at instance's start-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EPSM|[[PART (File Format)|PART]]|End Child Particle|System Init|Draw particle system positioned at instance's end-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZERY|bool|Zero Y|Particle Creation|Zero Y component of newly created particle vertices|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

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

ELSC (File Format)

2017-06-11T03:58:33Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''ELSC''' [[Particle Script|particle script]] format is used to build electrical effects in the ''Metroid Prime'' series.
Electrical effects are commonly used to dynamically draw lightning and electrical arcs.

An electrical ''particle instance'' is a single line subdivided into ''segments''. Whenever a new instance is generated, its central
vertices are displaced using a [[wikipedia:Fractal|random fractal algorithm]]. The instance's color and line-width is updated
over its lifetime.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>ELSM</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|LIFE|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SLIF|IntElement|Segment Lifetime|Particle Creation|Count of frames for newly generated instance to last|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GRAT|RealElement|Generation Rate|System Update|Count of particles to generate per frame; remainder is accumulated across updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SCNT|IntElement|Instance Count|System Init|Maximum count of particle instances and child generators for system|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSEG|IntElement|Segment Count|System Init|Maximum count of line segments per instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Swoosh Color|Particle Creation and Update|Modulation color evaluated for swoosh-based instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IEMT|EmitterElement|Initial Emitter|Particle Creation|Position source for instance start-point; Velocity is used to form beziér points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|FEMT|EmitterElement|Final Emitter|Particle Creation|Position source for instance end-point; Velocity is used to form beziér points to curve instance|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPL|RealElement|Length Amplitude|Particle Creation|Randomized coefficient of fractal displacement as product of segment count|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AMPD|RealElement|Direct Amplitude|Particle Creation|Separately randomized coefficient of fractal displacement|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD1|RealElement|Line Width 1|Particle Creation and Update|Enables line 1 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD2|RealElement|Line Width 2|Particle Creation and Update|Enables line 2 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LWD3|RealElement|Line Width 3|Particle Creation and Update|Enables line 3 (overdrawn with same verts) and specifies its width in 480p pixels|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL1|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 1's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL2|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 2's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LCL3|ColorElement|Line Color 1|Particle Creation and Update|Specifies line 3's color|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh|System Init|Use swoosh system to draw effect; computed fractal points are set into swoosh's history; Omitting LWD* properties will only draw the swoosh|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|GPSM|[[PART (File Format)|PART]]|Start Child Particle|System Init|Draw particle system positioned at instance's start-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|EPSM|[[PART (File Format)|PART]]|End Child Particle|System Init|Draw particle system positioned at instance's end-point|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZERY|bool|Zero Y|Particle Creation|Zero Y component of newly created particle vertices|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

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

SWHC (File Format)

2017-06-08T06:24:25Z

Jackoalan: /* Properties */

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''SWHC''' [[Particle Script|particle script]] format is used to build swoosh effects in the ''Metroid Prime'' series.
Swooshes are characterized as dynamically-generated triangles "brushed" into space.

Each swoosh system emits ''particle instances'' once per frame, connecting each new instance with the previous instance.
The system will not render until it has a history of ''at least'' 2 swoosh particles (2 frames of updates). Swoosh cross-sections may
form simple planes through space (<code>SIDE==2</code>) or extruded prism shapes (<code>SIDE>=3</code>).

To smooth out intra-frame geometry, vertices connecting particle instances may be calculated using [[wikipedia:Tricubic interpolation|tricubic interpolation]].
SPLN defines the number of subdivisions with which to perform interpolation.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>SWSH</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|PSLT|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TIME|RealElement|Time Multiplier|Pre Particles Update|Factor that defines number of evaluation frames per real frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LRAD|RealElement|Left Radius|Particle Update|Radius of swoosh cross-section's left side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|RRAD|RealElement|Right Radius|Particle Update|Radius of swoosh cross-section's right side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LENG|IntElement|Length|System Init|Maximum history of swoosh sections to retain (must be at least 2)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Color|Particle Creation and Update|Modulation color of swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SIDE|IntElement|Side Count|System Init|Count of swoosh cross-section sides (2 for plane, 3+ for extruded prism)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IROT|FloatElement|Initial Rotation|Particle Creation|Rotation bias evaluated for new particle instances (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ROTM|FloatElement|Rotation Master|Particle Update|Rotation bias evaluated per particle instance, per frame (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|POFS|VectorElement|Particle Offset|Particle Creation|Local translation bias evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IVEL|VectorElement|Initial Velocity|Particle Creation|Relative velocity evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|NPOS|VectorElement|Next Position|Particle Update|Local translation bias updated per particle instance, per frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VELM|ModVectorElement|Velocity 1|Particle Update|Continuous position and velocity source of particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLM2|ModVectorElement|Velocity 2|Particle Update|Second position and velocity source evaluated after VELM|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SPLN|IntElement|Spline Segments|System Init|Count of intra-frame faces to draw per particle connection, using tricubic spline interpolation|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXR|UVElement|Texture|System Render|Texture and UV source for swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TSPN|IntElement|Texture Span|System Render|Count of particle instances over which to scale UV coordinate cycle|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LLRD|bool|Left Radius for Right|System Init|Use LRAD value for RRAD|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CROS|bool|Cross|System Init|Intersect surfaces across cross-section verts, as opposed to a non-intersecting prism|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS1|bool|Local Velocity 1|System Init|Evaluate VELM in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS2|bool|Local Velocity 2|System Init|Evaluate VLM2 in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SROT|bool|Single Rotation|System Init|Update IROT per particle instance, per frame and ignore ROTM, otherwise once per system update|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|WIRE|bool|Wireframe|System Init|Render surfaces as triangle wireframe|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXW|bool|{{unknown}}|System Init|Unused|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AALP|bool|Additive Alpha|System Init|Draw using additive alpha blending|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZBUF|bool|Z-buffer Update|System Init|Enable Z-buffer updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ORNT|bool|View Orient|System Init|Render surface facing view (2-SIDE only, no SPLN)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CRND|bool|Clock Random|System Init|Use current CPU time for random seed, rather than 99|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

SWHC (File Format)

2017-06-08T06:23:03Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''SWHC''' [[Particle Script|particle script]] format is used to build swoosh effects in the ''Metroid Prime'' series.
Swooshes are characterized as dynamically-generated triangles "brushed" into space.

Each swoosh system emits ''particle instances'' once per frame, connecting each new instance with the previous instance.
The system will not render until it has a history of ''at least'' 2 swoosh particles (2 frames of updates). Swoosh cross-sections may
form simple planes through space (<code>SIDE==2</code>) or extruded prism shapes (<code>SIDE>=3</code>).

To smooth out intra-frame geometry, vertices connecting particle instances may be calculated using [[wikipedia:Tricubic interpolation|tricubic interpolation]].
SPLN defines the number of subdivisions with which to perform interpolation.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>SWSH</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|PSLT|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TIME|RealElement|Time Multiplier|Pre Particles Update|Factor that defines number of evaluation frames per real frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LRAD|RealElement|Left Radius|Particle Update|Radius of swoosh cross-section's left side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|RRAD|RealElement|Right Radius|Particle Update|Radius of swoosh cross-section's right side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LENG|IntElement|Length|System Init|Maximum history of swoosh sections to retain (must be at least 2)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Color|Particle Creation and Update|Modulation color of swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SIDE|IntElement|Side Count|System Init|Count of swoosh cross-section sides (2 for plane, 3+ for extruded prism)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IROT|FloatElement|Initial Rotation|Particle Creation|Rotation bias evaluated for new particle instances (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ROTM|FloatElement|Rotation Master|Particle Update|Rotation bias evaluated per particle instance, per frame (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|POFS|VectorElement|Particle Offset|Particle Creation|Local translation bias evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IVEL|VectorElement|Initial Velocity|Particle Creation|Relative velocity evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|NPOS|VectorElement|Next Position|Particle Update|Local translation bias updated per particle instance, per frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VELM|ModVectorElement|Velocity 1|Particle Update|Continuous position and velocity source of particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLM2|ModVectorElement|Velocity 2|Particle Update|Second position and velocity source evaluated after VELM|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SPLN|IntElement|Spline Segments|System Init|Count of intra-frame faces to draw per particle connection, using tricubic spline interpolation|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXR|UVElement|Texture|System Render|Texture and UV source for swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TSPN|IntElement|Texture Span|System Render|Count of particle instances over which to scale UV coordinate cycle|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LLRD|BoolElement|Left Radius for Right|System Init|Use LRAD value for RRAD|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CROS|BoolElement|Cross|System Init|Intersect surfaces across cross-section verts, as opposed to a non-intersecting prism|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS1|BoolElement|Local Velocity 1|System Init|Evaluate VELM in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS2|BoolElement|Local Velocity 2|System Init|Evaluate VLM2 in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SROT|BoolElement|Single Rotation|System Init|Update IROT per particle instance, per frame and ignore ROTM, otherwise once per system update|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|WIRE|BoolElement|Wireframe|System Init|Render surfaces as triangle wireframe|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXW|BoolElement|{{unknown}}|System Init|Unused|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AALP|BoolElement|Additive Alpha|System Init|Draw using additive alpha blending|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZBUF|BoolElement|Z-buffer Update|System Init|Enable Z-buffer updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ORNT|BoolElement|View Orient|System Init|Render surface facing view (2-SIDE only, no SPLN)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CRND|BoolElement|Clock Random|System Init|Use current CPU time for random seed, rather than 99|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

SWHC (File Format)

2017-06-04T23:47:07Z

Jackoalan:

{{research|1|Properties beyond MP1 need to be discovered and documented}}
The '''SWHC''' [[Effect Script|effect script]] format is used to build swoosh effects in the ''Metroid Prime'' series.
Swooshes are characterized as dynamically-generated triangles "brushed" into space.

Each swoosh system emits ''particle instances'' once per frame, connecting each new instance with the previous instance.
The system will not render until it has a history of ''at least'' 2 swoosh particles (2 frames of updates). Swoosh cross-sections may
form simple planes through space (<code>SIDE==2</code>) or extruded prism shapes (<code>SIDE>=3</code>).

To smooth out intra-frame geometry, vertices connecting particle instances may be calculated using [[wikipedia:Tricubic interpolation|tricubic interpolation]].
SPLN defines the number of subdivisions with which to perform interpolation.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>SWSH</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|PSLT|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TIME|RealElement|Time Multiplier|Pre Particles Update|Factor that defines number of evaluation frames per real frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LRAD|RealElement|Left Radius|Particle Update|Radius of swoosh cross-section's left side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|RRAD|RealElement|Right Radius|Particle Update|Radius of swoosh cross-section's right side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LENG|IntElement|Length|System Init|Maximum history of swoosh sections to retain (must be at least 2)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Color|Particle Creation and Update|Modulation color of swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SIDE|IntElement|Side Count|System Init|Count of swoosh cross-section sides (2 for plane, 3+ for extruded prism)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IROT|FloatElement|Instance Rotation|Particle Creation|Rotation bias evaluated for new particle instances (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ROTM|FloatElement|Rotation Master|Particle Update|Rotation bias evaluated per particle instance, per frame (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|POFS|VectorElement|Particle Offset|Particle Creation|Local translation bias evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IVEL|VectorElement|Particle Offset|Particle Creation|Relative velocity evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|NPOS|VectorElement|Particle Offset|Particle Update|Local translation bias updated per particle instance, per frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VELM|ModVectorElement|Velocity 1|Particle Update|Continuous position and velocity source of particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLM2|ModVectorElement|Velocity 2|Particle Update|Second position and velocity source evaluated after VELM|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SPLN|IntElement|Spline Segments|System Init|Count of intra-frame faces to draw per particle connection, using tricubic spline interpolation|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXR|UVElement|Texture|System Render|Texture and UV source for swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TSPN|IntElement|Texture Span|System Render|Count of particle instances over which to scale UV coordinate cycle|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LLRD|BoolElement|Left Radius for Right|System Init|Use LRAD value for RRAD|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CROS|BoolElement|Cross|System Init|Intersect surfaces across cross-section verts, as opposed to a non-intersecting prism|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS1|BoolElement|Local Velocity 1|System Init|Evaluate VELM in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS2|BoolElement|Local Velocity 2|System Init|Evaluate VLM2 in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SROT|BoolElement|Single Rotation|System Init|Update IROT per particle instance, per frame and ignore ROTM, otherwise once per system update|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|WIRE|BoolElement|Single Rotation|System Init|Render surfaces as triangle wireframe|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXW|BoolElement|{{unknown}}|System Init|Unused|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AALP|BoolElement|Additive Alpha|System Init|Draw using additive alpha blending|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZBUF|BoolElement|Z-buffer Update|System Init|Enable Z-buffer updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ORNT|BoolElement|View Orient|System Init|Render surface facing view (2-SIDE only, no SPLN)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CRND|BoolElement|View Orient|System Init|Use current CPU time for random seed, rather than 99|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

SWHC (File Format)

2017-06-04T23:34:15Z

Jackoalan: /* SWHC Keys */

{{research|2|Key parameters need reverse-engineering}}
The '''SWHC''' [[Effect Script|effect script]] format is used to build swoosh effects in the ''Metroid Prime'' series.
Swooshes are characterized as dynamically-generated, trailing ''triangle-strips'' "brushed" into space.

== Properties ==

Particle generator properties are assembled into a [[Particle Script|particle script]]
file tagged with <code>SWSH</code>. Any of the following properties are loaded into a
''description'' class for constructing an arbitrary number of ''particle generators''.

{| class="wikitable"
! FourCC
! Type
! Description
! Scope
! Notes
! MP1
! MP2
! MP3
! DKCR
! DKCTF
|-
{{ParticlePropertyRow|PSLT|IntElement|Particle System Lifetime|System Init|Count of frames to emit new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TIME|RealElement|Time Multiplier|Pre Particles Update|Factor that defines number of evaluation frames per real frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LRAD|RealElement|Left Radius|Particle Update|Radius of swoosh cross-section's left side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|RRAD|RealElement|Right Radius|Particle Update|Radius of swoosh cross-section's right side|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LENG|IntElement|Length|System Init|Maximum history of swoosh sections to retain (must be at least 2)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|COLR|ColorElement|Color|Particle Creation and Update|Modulation color of swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SIDE|IntElement|Side Count|System Init|Count of swoosh cross-section sides (2 for plane, 3+ for extruded prism)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IROT|FloatElement|Instance Rotation|Particle Creation|Rotation bias evaluated for new particle instances (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ROTM|FloatElement|Rotation Master|Particle Update|Rotation bias evaluated per particle instance, per frame (in degrees)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|POFS|VectorElement|Particle Offset|Particle Creation|Local translation bias evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|IVEL|VectorElement|Particle Offset|Particle Creation|Relative velocity evaluated for new particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|NPOS|VectorElement|Particle Offset|Particle Update|Local translation bias updated per particle instance, per frame|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VELM|ModVectorElement|Velocity 1|Particle Update|Continuous position and velocity source of particle instances|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLM2|ModVectorElement|Velocity 2|Particle Update|Second position and velocity source evaluated after VELM|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SPLN|IntElement|Spline Segments|System Init|Count of intra-frame faces to draw per particle connection, using tricubic spline interpolation|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXR|UVElement|Texture|System Render|Texture and UV source for swoosh surfaces|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TSPN|IntElement|Texture Span|System Render|Count of particle instances over which to scale UV coordinate cycle|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|LLRD|BoolElement|Left Radius for Right|System Init|Use LRAD value for RRAD|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CROS|BoolElement|Cross|System Init|Intersect surfaces across cross-section verts, as opposed to a non-intersecting prism|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS1|BoolElement|Local Velocity 1|System Init|Evaluate VELM in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|VLS2|BoolElement|Local Velocity 2|System Init|Evaluate VLM2 in particle-local space|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|SROT|BoolElement|Single Rotation|System Init|Update IROT per particle instance, per frame and ignore ROTM, otherwise once per system update|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|WIRE|BoolElement|Single Rotation|System Init|Render surfaces as triangle wireframe|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|TEXW|BoolElement|{{unknown}}|System Init|Unused|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|AALP|BoolElement|Additive Alpha|System Init|Draw using additive alpha blending|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ZBUF|BoolElement|Z-buffer Update|System Init|Enable Z-buffer updates|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|ORNT|BoolElement|View Orient|System Init|Render surface facing view (2-SIDE only, no SPLN)|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
{{ParticlePropertyRow|CRND|BoolElement|View Orient|System Init|Use current CPU time for random seed, rather than 99|{{check}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
|}

MAPA (File Format)

2017-04-25T00:57:47Z

Jackoalan: /* Header */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible (Map Universe Area)</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|{{AABox}}
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Mappable Objects ===
A Mappable Object in the Metroid Prime series can include: Elevators, Doors, and Save/Missile Stations. Each Mappable Object entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; See table below for MP1 types
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Map Station or Area Visit</li><li>Visible on Door Visit</li><li>Never Visible</li><li>Visible on Map Station or Area Visit</li></ol>
|{{check}}
|{{check}}
|-
|u32
|'''Editor ID'''; Same ID format as SCLY, indicates associated world object
|{{check}}
|{{nocheck}}
|-
|{{Vector4f}}
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|{{Transform4f}}
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

==== MP1 Types ====
{|class="wikitable"
!Type
!Description
|-
|0
|Normal Door
|-
|1
|Shield Door
|-
|2
|Ice Door
|-
|3
|Wave Door
|-
|4
|Plasma Door
|-
|5
|Big Door
|-
|6
|Big Door 2
|-
|7
|Ice Door Ceiling
|-
|8
|Ice Door Floor
|-
|9
|Wave Door Ceiling
|-
|10
|Wave Door Floor
|-
|11
|Plasma Door Ceiling
|-
|12
|Plasma Door Floor
|-
|13
|Ice Door Floor 2
|-
|14
|Wave Door Floor 2
|-
|15
|Plasma Door Floor 2
|-
|27
|Down Arrow Yellow (Maintenance Tunnel)
|-
|28
|Up Arrow Yellow (Phazon Processing Center)
|-
|29
|Down Arrow Green (Elevator A)
|-
|30
|Up Arrow Green (Elite Control Access)
|-
|31
|Down Arrow Red (Elevator B)
|-
|32
|Up Arrow Red (Fungal Hall Access)
|-
|33
|Elevator
|-
|34
|Save Station
|-
|37
|Missile Station
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|{{Vector3f}}
|'''Normal'''
|-
|{{Vector3f}}
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Border Table Start'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

MAPA (File Format)

2017-04-22T20:55:39Z

Jackoalan: /* Mappable Objects */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|CAABox
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Mappable Objects ===
A Mappable Object in the Metroid Prime series can include: Elevators, Doors, and Save/Missile Stations. Each Mappable Object entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; See table below for MP1 types
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Map Station or Area Visit</li><li>Visible on Door Visit</li><li>Never Visible</li><li>Visible on Map Station or Area Visit</li></ol>
|{{check}}
|{{check}}
|-
|u32
|'''Editor ID'''; Same ID format as SCLY, indicates associated world object
|{{check}}
|{{nocheck}}
|-
|CVector4f
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|CTransform4f
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

==== MP1 Types ====
{|class="wikitable"
!Type
!Description
|-
|0
|Normal Door
|-
|1
|Shield Door
|-
|2
|Ice Door
|-
|3
|Wave Door
|-
|4
|Plasma Door
|-
|5
|Big Door
|-
|6
|Big Door 2
|-
|7
|Ice Door Ceiling
|-
|8
|Ice Door Floor
|-
|9
|Wave Door Ceiling
|-
|10
|Wave Door Floor
|-
|11
|Plasma Door Ceiling
|-
|12
|Plasma Door Floor
|-
|13
|Ice Door Floor 2
|-
|14
|Wave Door Floor 2
|-
|15
|Plasma Door Floor 2
|-
|27
|Down Arrow Yellow (Maintenance Tunnel)
|-
|28
|Up Arrow Yellow (Phazon Processing Center)
|-
|29
|Down Arrow Green (Elevator A)
|-
|30
|Up Arrow Green (Elite Control Access)
|-
|31
|Down Arrow Red (Elevator B)
|-
|32
|Up Arrow Red (Fungal Hall Access)
|-
|33
|Elevator
|-
|34
|Save Station
|-
|37
|Missile Station
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|CVector3f
|'''Normal'''
|-
|CVector3f
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Border Table Start'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

MAPA (File Format)

2017-04-22T20:53:13Z

Jackoalan: /* Mappable Objects */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|CAABox
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Mappable Objects ===
A Mappable Object in the Metroid Prime series can include: Elevators, Doors, and Save/Missile Stations. Each Point of Interest entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; See table below for MP1 types
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Map Station or Area Visit</li><li>Visible on Door Visit</li><li>Never Visible</li><li>Visible on Map Station or Area Visit</li></ol>
|{{check}}
|{{check}}
|-
|u32
|'''Editor ID'''; Same ID format as SCLY, indicates associated world object
|{{check}}
|{{nocheck}}
|-
|CVector4f
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|CTransform4f
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

==== MP1 Types ====
{|class="wikitable"
!Type
!Description
|-
|0
|Normal Door
|-
|1
|Shield Door
|-
|2
|Ice Door
|-
|3
|Wave Door
|-
|4
|Plasma Door
|-
|5
|Big Door
|-
|6
|Big Door 2
|-
|7
|Ice Door Ceiling
|-
|8
|Ice Door Floor
|-
|9
|Wave Door Ceiling
|-
|10
|Wave Door Floor
|-
|11
|Plasma Door Ceiling
|-
|12
|Plasma Door Floor
|-
|13
|Ice Door Floor 2
|-
|14
|Wave Door Floor 2
|-
|15
|Plasma Door Floor 2
|-
|27
|Down Arrow Yellow (Maintenance Tunnel)
|-
|28
|Up Arrow Yellow (Phazon Processing Center)
|-
|29
|Down Arrow Green (Elevator A)
|-
|30
|Up Arrow Green (Elite Control Access)
|-
|31
|Down Arrow Red (Elevator B)
|-
|32
|Up Arrow Red (Fungal Hall Access)
|-
|33
|Elevator
|-
|34
|Save Station
|-
|37
|Missile Station
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|CVector3f
|'''Normal'''
|-
|CVector3f
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Border Table Start'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

MAPA (File Format)

2017-04-22T20:51:08Z

Jackoalan: /* Point of Interest */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|CAABox
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Mappable Objects ===
A Mappable Object in the Metroid Prime series can include: Elevators, Doors, and Save/Map/Missile Stations. Each Point of Interest entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; See table below for MP1 types
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Map Station or Area Visit</li><li>Visible on Door Visit</li><li>Never Visible</li><li>Visible on Map Station or Area Visit</li></ol>
|{{check}}
|{{check}}
|-
|u32
|'''Editor ID'''; Same ID format as SCLY, indicates associated world object
|{{check}}
|{{nocheck}}
|-
|CVector4f
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|CTransform4f
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

==== MP1 Types ====
{|class="wikitable"
!Type
!Description
|-
|0
|Normal Door
|-
|1
|Shield Door
|-
|2
|Ice Door
|-
|3
|Wave Door
|-
|4
|Plasma Door
|-
|5
|Big Door
|-
|6
|Big Door 2
|-
|7
|Ice Door Ceiling
|-
|8
|Ice Door Floor
|-
|9
|Wave Door Ceiling
|-
|10
|Wave Door Floor
|-
|11
|Plasma Door Ceiling
|-
|12
|Plasma Door Floor
|-
|13
|Ice Door Floor 2
|-
|14
|Wave Door Floor 2
|-
|15
|Plasma Door Floor 2
|-
|27
|Down Arrow Yellow (Maintenance Tunnel)
|-
|28
|Up Arrow Yellow (Phazon Processing Center)
|-
|29
|Down Arrow Green (Elevator A)
|-
|30
|Up Arrow Green (Elite Control Access)
|-
|31
|Down Arrow Red (Elevator B)
|-
|32
|Up Arrow Red (Fungal Hall Access)
|-
|33
|Elevator
|-
|34
|Save Station
|-
|37
|Missile Station
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|CVector3f
|'''Normal'''
|-
|CVector3f
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Border Table Start'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

MAPA (File Format)

2017-04-22T20:49:37Z

Jackoalan: /* Point of Interest */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|CAABox
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Point of Interest ===
A Point of Interest in the Metroid Prime series can include: Mission Objectives, Elevators, Doors, Map Stations, and Missile Stations. Each Point of Interest entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; See table below for MP1 types
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Map Station or Area Visit</li><li>Visible on Door Visit</li><li>Never Visible</li><li>Visible on Map Station or Area Visit</li></ol>
|{{check}}
|{{check}}
|-
|u32
|'''Editor ID'''; Same ID format as SCLY, indicates associated world object
|{{check}}
|{{nocheck}}
|-
|CVector4f
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|CTransform4f
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

==== MP1 Types ====
{|class="wikitable"
!Type
!Description
|-
|0
|Normal Door
|-
|1
|Shield Door
|-
|2
|Ice Door
|-
|3
|Wave Door
|-
|4
|Plasma Door
|-
|5
|Big Door
|-
|6
|Big Door 2
|-
|7
|Ice Door Ceiling
|-
|8
|Ice Door Floor
|-
|9
|Wave Door Ceiling
|-
|10
|Wave Door Floor
|-
|11
|Plasma Door Ceiling
|-
|12
|Plasma Door Floor
|-
|13
|Ice Door Floor 2
|-
|14
|Wave Door Floor 2
|-
|15
|Plasma Door Floor 2
|-
|27
|Down Arrow Yellow (Maintenance Tunnel)
|-
|28
|Up Arrow Yellow (Phazon Processing Center)
|-
|29
|Down Arrow Green (Elevator A)
|-
|30
|Up Arrow Green (Elite Control Access)
|-
|31
|Down Arrow Red (Elevator B)
|-
|32
|Up Arrow Red (Fungal Hall Access)
|-
|33
|Elevator
|-
|34
|Save Station
|-
|37
|Missile Station
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|CVector3f
|'''Normal'''
|-
|CVector3f
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Border Table Start'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

MAPA (File Format)

2017-04-20T19:00:42Z

Jackoalan: /* Primitive Headers */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|CAABox
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Point of Interest ===
A Point of Interest in the Metroid Prime series can include: Mission Objectives, Elevators, Doors, Map Stations, and Missile Stations. Each Point of Interest entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; All valid values are not currently known
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{check}}
|{{check}}
|-
|u16
|{{unknown|Unknown}}
|{{check}}
|{{nocheck}}
|-
|u16
|'''ID'''; Which door, elevator etc.
|{{check}}
|{{nocheck}}
|-
|CVector4f
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|CTransform4f
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|CVector3f
|'''Normal'''
|-
|CVector3f
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Border Table Start'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

MAPA (File Format)

2017-04-20T02:56:43Z

Jackoalan: /* Header */

The '''.MAPA file format''' defines the minimap models used in the Metroid Prime series. MAPA or '''MAP A'''rea consists of several sections: The header, Point Of Interest entries, Vertices, Primitive Headers, and the primitives.

{{research|2|A few things are unknown in the header and POI Entries}}

__TOC__
== Format ==
=== Header ===
The header is very straight forward, and has some minor differences depending on version, the unknown values don't seem to do anything, however not much research has been put into them.

{| class="wikitable"
!Type
!Description
!MP1
!MP2
!MP3
|-
|u32
|'''Magic'''; Always 0xDEADD00D
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Version'''; See below
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Type'''; unknown function in MP1/3, specifies whether the area appears on the Light (0) or Dark (1) map in MP2
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Visibility Mode'''; <ol start=0><li>Always Visible</li><li>Visible on Visit or Map Station (most MP1 areas)</li><li>Visible on Visit only (latter areas of Ruins and Phendrana)</li><li>Never Visible</li></ol>
|{{check}}
|{{check}}
|{{check}}
|-
|CAABox
|'''Bounding Box'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''POI Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Vertex Count'''
|{{check}}
|{{check}}
|{{check}}
|-
|u32
|'''Primitive Count'''
|{{check}}
|{{check}}
|{{check}}
|}

==== Version ====
The version value listed above can have the following values:
{|class="wikitable"
!Game
!Value
|-
|Metroid Prime 1
|2
|-
|Metroid Prime 2: Echoes
|3
|-
|Metroid Prime 3: Corruption
|5
|}

=== Point of Interest ===
A Point of Interest in the Metroid Prime series can include: Mission Objectives, Elevators, Doors, Map Stations, and Missile Stations. Each Point of Interest entry consists of the following struct:
{|class="wikitable"
!Type
!Description
!MP1 & MP2
!MP3
|-
|u32
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Type'''; All valid values are not currently known
|{{check}}
|{{check}}
|-
|u32
|{{unknown|Unknown}}
|{{check}}
|{{check}}
|-
|u16
|{{unknown|Unknown}}
|{{check}}
|{{nocheck}}
|-
|u16
|'''ID'''; Which door, elevator etc.
|{{check}}
|{{nocheck}}
|-
|CVector4f
|{{unknown|Unknown}}
|{{nocheck}}
|{{check}}
|-
|u32
|'''Padding'''; always -1
|{{check}}
|{{check}}
|-
|CTransform4f
|'''Tranform Matrix''' The Point of Interest's position in '''world''' space.
|{{check}}
|{{check}}
|-
|u32 * 4
|'''Padding'''; four values of -1
|{{check}}
|{{check}}
|}

=== Vertices ===

Vertices are a simple array of CVector3f. Geometry in MAPAs is, almost always, centered around the origin (0, 0, 0) and are simplified, full sized, versions of the map they replicate. Each vertex is referenced at least twice: once for the primitive, once for the line border.

=== Primitive Headers ===

The Primitive headers are extremely simple, they merely have a bounding box followed by the primitive table start and end point, relative to the end of the current primitive header. In other words: read in the header, seek to the start of the table from the '''current''' position, then read the primitives tables.

{|class="wikitable"
!Type
!Description
|-
|CVector3f
|'''Normal'''
|-
|CVector3f
|'''Center of Mass'''
|-
|u32
|'''Primitive Table Start'''; relative to the end of the header
|-
|u32
|'''Primitive Table End'''; relative to the end of the header
|}

=== Primitive Table ===

The Primitive is also fairly simple, each one consists of two parts: The GX Primitive list, and the Border list.
{|class="wikitable"
!Type
!Description
|-
|u32
|'''Primitive Count (PC)'''
|-
|Primitive * PC
|'''Primitives'''
|-
|u32
|'''Border Count (BC)'''
|-
|Border * (BC)
|'''Borders'''
|}

=== Primitive ===

A primitive in a MAPA is a simple 4 byte aligned list of indices into the vertex list, starting with the GX Primitive type, a count, then an array of indices, each index taking up one byte.

=== Border ===

A border in a MAPA is a simple count followed by a 4 byte aligned list indices into the vertex list, each index taking up one byte. A border is simply drawn using GX_LINESTRIP.

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

VISI (MREA Section)

2017-04-09T19:24:27Z

Jackoalan:

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Total number of area lights encoded in octree leaves.
|-
| u32
| 2nd Layer Light Count
| Lights within total that are in the 2nd BABEDEAD layer.
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective. 2nd layer lights are listed first.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree. '''Note:''' the coordinates of the AABB are in local area space (i.e. inverse-transformed with the matrix in the MREA header).
|-
| u32
| Total visibility object count
| Number of objects per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light object count
| Number of objects within total that are lights.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.

Finally are the bits relating lights in order of the BABEDEAD section of the MREA. The 2nd layer lights are related first. Each light encodes 2-bits apiece,
with the following enum represented:

{| class="wikitable"
! Value
! Description
|-
| 0
| Not Visible
|-
| 1
| Visible
|-
| 2
| Outside Octree Bounds
|}

VISI (MREA Section)

2017-02-26T18:11:49Z

Jackoalan: /* Layout */

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree. '''Note:''' the coordinates of the AABB are in local area space (i.e. inverse-transformed with the matrix in the MREA header).
|-
| u32
| Total visibility object count
| Number of objects per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light object count
| Number of objects within total that are lights.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.

Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Each light encodes 2-bits apiece,
with the following enum represented:

{| class="wikitable"
! Value
! Description
|-
| 0
| Not Visible
|-
| 1
| Visible
|-
| 2
| Outside Octree Bounds
|}

VISI (MREA Section)

2017-02-26T18:11:02Z

Jackoalan: /* Layout */

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree. '''Note:''' the coordinates of the AABB are in local area space (I.e. inverse-transformed with the matrix in the MREA header).
|-
| u32
| Total visibility object count
| Number of objects per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light object count
| Number of objects within total that are lights.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.

Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Each light encodes 2-bits apiece,
with the following enum represented:

{| class="wikitable"
! Value
! Description
|-
| 0
| Not Visible
|-
| 1
| Visible
|-
| 2
| Outside Octree Bounds
|}

VISI (MREA Section)

2017-02-26T18:02:10Z

Jackoalan: /* Layout */

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree.
|-
| u32
| Total visibility object count
| Number of objects per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light object count
| Number of objects within total that are lights.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.

Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Each light encodes 2-bits apiece,
with the following enum represented:

{| class="wikitable"
! Value
! Description
|-
| 0
| Not Visible
|-
| 1
| Visible
|-
| 2
| Outside Octree Bounds
|}

VISI (MREA Section)

2017-02-26T06:27:44Z

Jackoalan: /* Leaf Nodes */

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree.
|-
| u32
| Total visibility bit count
| Number of bits per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light bit count
| Number of bits after visibility bits that indicate in-bounds/out-of-bounds state of each light.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.

Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Each light encodes 2-bits apiece,
with the following enum represented:

{| class="wikitable"
! Value
! Description
|-
| 0
| Not Visible
|-
| 1
| Visible
|-
| 2
| Outside Octree Bounds
|}

VISI (MREA Section)

2017-02-26T06:00:29Z

Jackoalan: /* Leaf Nodes */

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree.
|-
| u32
| Total visibility bit count
| Number of bits per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light bit count
| Number of bits after visibility bits that indicate in-bounds/out-of-bounds state of each light.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA sections. Next are bits relating the scripted entities in the VISI entities table.
Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Following these is another
set of bits for each light indicating if it's in-bounds of the octree or not.

VISI (MREA Section)

2017-02-26T05:59:52Z

Jackoalan: /* Octree Nodes */

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree.
|-
| u32
| Total visibility bit count
| Number of bits per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light bit count
| Number of bits after visibility bits that indicate in-bounds/out-of-bounds state of each light.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major, depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA section. Next are bits relating the scripted entities in the VISI entities table.
Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Following these is another
set of bits for each light indicating if it's in-bounds of the octree or not.

MREA (Metroid Prime)

2017-02-26T05:57:33Z

Jackoalan:

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

The '''MREA format''' defines areas (rooms) in Metroid Prime. It's a massive format that contains tons of different data, including terrain geometry, collision, objects, lights, and more.

{{todo|There's a LOT of sections that are mostly known, but need some documentation written up. SCLY and collision need separate articles (although the unique parts of the collision format, like the octree, could maybe be documented here). The rest should probably stay on this page.}}
{{research|minor|Discounting unknowns within the actual data sections, the main thing that still isn't known is what the unknown data section is for.}}

== Format ==

Like [[CMDL (Metroid Prime)|CMDL]], MREA files are split up into a number of 32-byte aligned sections. Every section both starts and ends on a 32-byte boundary. These are used to separate different parts of the file; different types of sections typically indicate different sets of data. The header declares the section count and the size of each one; using these is the only way to navigate the file.

These are the sections that appear in each MREA file, in the order they appear in the file:

{| class="wikitable"
! Identifier
! Name
|-
| {{none}}
| [[#World Geometry|World Geometry]]
|-
| <code>AROT</code>
| [[#Area Octree|Area Octree]]
|-
| <code>SCLY</code>
| [[#Script Layers|Script Layers]]
|-
| <code>0xDEAFBABE</code>
| [[#Collision|Collision]]
|-
| {{none}}
| {{unknown|[[#Unknown Section|Unknown]]}}
|-
| <code>0xBABEDEAD</code>
| [[#Lights|Lights]]
|-
| <code>VISI</code>
| [[#Visibility Tree|Visibility Tree]]
|-
| {{none}}
| [[#Path|Path]]
|}

=== Header ===

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| u32
| 1
| '''Magic'''
| Always <code>0xDEADBEEF</code>.
|-
| 0x4
| u32
| 1
| '''Version'''
| See [[MREA (File Format)|hub article]] for a list of possible version numbers.
|-
| 0x8
| float
| 12
| '''Area Transform'''
| Matrix that represents the area's transform from the origin. Most area data is pre-transformed, so this matrix is only used occasionally.
|-
| 0x38
| u32
| 1
| '''World Model Count'''
| Number of world models in this area.
|-
| 0x3C
| u32
| 1
| '''Data Section Count'''
| Number of data sections in the file.
|-
| 0x40
| u32
| 1
| '''World Geometry Section'''
| Section index for [[#World Geometry|world geometry data]]. Always 0; starts on materials.
|-
| 0x44
| u32
| 1
| '''Script Layers Section'''
| Section index for [[#Script Layers|script layer data]].
|-
| 0x48
| u32
| 1
| '''Collision Section'''
| Section index for [[#Collision|collision data]].
|-
| 0x4C
| u32
| 1
| '''Unknown Section'''
| Section index for [[#Unknown Section|unknown data]].
|-
| 0x50
| u32
| 1
| '''Lights Section'''
| Section index for [[#Lights|light data]].
|-
| 0x54
| u32
| 1
| '''Visibility Tree Section'''
| Section index for [[#Visibility Tree|visibility tree data]].
|-
| 0x58
| u32
| 1
| '''Path Section'''
| Section index for [[#Path|path data]].
|-
| 0x5C
| u32
| 1
| '''Area Octree Section'''
| Section index for [[#Area Octree|area octree data]].
|-
| 0x60
| u32
| ''Data Section Count''
| '''Data Section Sizes'''
| Array containing the size of each data section in the file. Every size is always a multiple of 32.
|-
| colspan=5 {{unknown|End of header; pad to 32 bytes before first data section begins}}
|}

=== World Geometry ===

''See [[Materials (Metroid Prime)]] and [[Geometry (Metroid Prime)]]''

MREA files have one material section, followed by a number of world models, each of which has its own set of geometry sections. There's couple small differences you'll usually see on world models compared to regular CMDL ones:

* Normals are ''always'' shorts, so vertex format 0 is never used.
* Most world models use lightmaps, so normally the first UV coordinate on each vertex will read from the short UV array. This isn't always the case, though; you need to make sure you check the material so you know where to read from.
* Surfaces will usually have a bounding box in the extra data in the surface header. This bounding box is used for depth sorting.
* Each world model starts with an extra header section which is formatted like this:

{| class="wikitable"
! Offset
! Type
! Count
! Name
! Notes
|-
| 0x0
| [[#Visor Flags|Visor Flags]]
| 1
| '''Visor Flags'''
| 32-bit bitfield that sets parameters controlling how the mesh renders in different visors.
|-
| 0x4
| float
| 12
| '''World Model Transform'''
| World model's transform from the area's local origin. The geometry data is pre-transformed, so this matrix can largely be ignored.
|-
| 0x34
| float
| 6
| '''World Model Bounding Box'''
| Pre-transformed axis-aligned bounding box for this model.
|-
| 0x4C
| colspan=4 {{unknown|End of mesh header section}}
|}

==== Visor Flags ====

{| class="wikitable"
! Bit
! Hex
! Description
|-
| 0
| 0x1
| {{unknown|Unknown}}
|-
| 1
| 0x2
| Disable rendering in Combat/Scan Visor
|-
| 2
| 0x4
| Disable rendering in Thermal Visor
|-
| 3
| 0x8
| Disable rendering in X-Ray Visor
|-
| 4-5
| 0x30
| Thermal heat level.
* 0 - Cool
* 1 - Hot
* 2 - Warm
|}

=== Area Octree ===

{{main|AROT (MREA Section)}}

The AROT section stores the area's octree, accelerating back-to-front rendering of contained meshes. It is also used for spacial queries such as collision.

=== Script Layers ===

{{todo|Format known, needs documentation written up.}}

The SCLY section contains data for objects.

=== Collision ===

''Main article: [[Area Collision (File Format)]]''

=== Unknown Section ===

This one is sandwiched between collision and lights, and usually just contains a single 32-bit "1". Purpose is unknown. In the Prime 3/DKCR MREA format, this section is labelled <code>LLTE</code>.

=== Lights ===

This section is for dynamic lights. See the [[Lights_(Metroid_Prime)|Light]] article for details.

=== Visibility Tree ===

{{main|VISI (MREA Section)}}

This section is a PVS octree labeled "VISI". Some areas don't have visibility octrees; in that case this section will be completely empty and listed with a size of 0.

=== Path ===

This is the final section in the file; its only value is a single [[PATH (File Format)|PATH]] file ID.

{| class="wikitable"
! Offset
! Type
! Name
|-
| 0x0
| Asset ID
| '''Area PATH Resource'''
|-
| 0x4
| colspan=2 {{unknown|End of section}}
|}

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

VISI (MREA Section)

2017-02-26T05:56:19Z

Jackoalan: Created page with "Within MREA resources, the '''VISI section''' stores a PVS indexed into an octree. This PVS..."

Within [[MREA (File Format)|MREA]] resources, the '''VISI section''' stores a [[wikipedia:Potentially_visible_set|PVS]]
indexed into an [[wikipedia:Octree|octree]]. This PVS is used to determine visibility/occlusion between cubic sections of
the area and models, scripting entities, and lights in the scene.

=== Layout ===

{| class="wikitable"
! Data Type
! Description
! Notes
|-
| FourCC
| <code>VISI</code> magic
|
|-
| u32
| VISI Version
| 0x2 in ''Metroid Prime''.
|-
| bool
| Unknown 1
|
|-
| bool
| Unknown 2
|
|-
| u32
| Feature count
| Number of static MREA meshes + script entities encoded in octree.
|-
| u32
| Light count
| Number of area lights encoded in octree leaves.
|-
| u32
| Unknown 3
|
|-
| u32
| Entity count
| Number of script entities encoded in octree.
|-
| u32
| Leaf size
| Size of octree leaf node in bytes.
|-
| u32
| Light visibility node count
| Count of leaf nodes from light perspectives (matches light count).
|-
| u32[entityCount]
| Entity array
| Array of entity IDs mapping the octree bits to the lower 16-bits of the SCLY editor IDs.
|-
| u8[lightVisibilityNodeCount][leafSize]
| Light visibility node array
| Array of [[#Leaf Nodes|leaf node data]] indicating visibility of other objects from light's perspective.
|-
| float[2][3]
| Octree AABB
| Total bounds subdivided by octree.
|-
| u32
| Total visibility bit count
| Number of bits per-leaf that indicate visibility from the selected octree region (static + entities + lights).
|-
| u32
| Total light bit count
| Number of bits after visibility bits that indicate in-bounds/out-of-bounds state of each light.
|-
| u32
| Octree length
| Size of octree in bytes.
|-
| u8[octreeLength]
| Octree data
| Byte-packed PVS octree data described below.
|}

=== Octree Nodes ===

The octree data is arranged in a Z-major depth-first hierarchy embedded with variable-length pointers to skip over
children, permitting rapid child selection. Each node of the octree starts with a 1-byte header
of classification bits. If at least one subdivide bit is set, the node is a branch and contains 1-7 pointers, addressed
relative to the position after the pointers. One subdivision will have 1 pointer, two subdivisions will have 3 pointers,
and three subdivisions will have 7 pointers. The first child pointer is implied to be 0x0. Pointer data type is specified
in the header (8, 16, or 24 bits).

{| class="wikitable"
! Bit (from LSB)
! Description
|-
| 0
| Branch Subdivide X
|-
| 1
| Branch Subdivide Y
|-
| 2
| Branch Subdivide Z
|-
| 3-4
| Node type <ol><li>Out of bounds (not used)</li><li>End of hierarchy (indicates nothing is visible)</li><li>Regular node (followed by branch pointers or leaf bits)</li></ol>
|-
| 5-6
| Branch pointer type <ol start=0><li>16-bit pointers</li><li>8-bit pointers</li><li>24-bit pointers</li></ol>
|}

=== Leaf Nodes ===

Instead of child pointers, leaf nodes contain byte-packed bits indicating visibility.
The bits are arranged from LSB to MSB per-byte. First are the bits relating static MREA geometry
in-order of the first MREA section. Next are bits relating the scripted entities in the VISI entities table.
Finally are the bits relating lights in order of the BABEDEAD section of the MREA. Following these is another
set of bits for each light indicating if it's in-bounds of the octree or not.

Metroid Prime 3: Corruption

2016-12-13T18:52:29Z

Jackoalan: /* Builds */

'''Metroid Prime 3: Corruption''' is the third and final game in the Metroid Prime trilogy.

__TOC__

== Builds ==

{| class="wikitable"
! Build
! Date/Time
! Version
|-
| v3.068
| 3/2/2006 14:55:13
| E3 2006 Prototype
|-
| v3.436
| 2007/07/27 13:13
| Wii NTSC (Original Release)
|-
| v3.453
| 2007/08/24 16:52
| Wii PAL
|-
| v3.495
| 2007/11/12 14:15
| Wii NTSC-J
|-
| v3.593
| 2008/08/21 17:09
| Metroid Prime: Trilogy NTSC
|-
| v3.629
| 2009/01/15 14:08
| Metroid Prime: Trilogy PAL
|}

== Formats ==

{| class="wikitable"
! Format
! Contents
|-
| [[ANIM (File Format)|ANIM]]
| Animation
|-
| [[ATBL (File Format)|ATBL]]
| Audio Lookup Table
|-
| [[BFRC (File Format)|BFRC]]
| Burst Fire Data
|-
| [[CAAD (File Format)|CAAD]]
| {{unknown|Unknown}}
|-
| [[CAUD (File Format)|CAUD]]
| Audio Manager Macro
|-
| [[CHAR (File Format)|CHAR]]
| Character
|-
| [[CINF (File Format)|CINF]]
| Skeleton
|-
| [[CMDL (Metroid Prime)|CMDL]]
| Model
|-
| [[CRSC (File Format)|CRSC]]
| Collision Response Particle System
|-
| [[CSKR (File Format)|CSKR]]
| Skin Rules
|-
| [[CSMP (File Format)|CSMP]]
| Audio Sample
|-
| [[DCLN (File Format)|DCLN]]
| Dynamic Collision
|-
| [[DGRP (File Format)|DGRP]]
| Dependency Group
|-
| [[DPSC (File Format)|DPSC]]
| Decal Particle System
|-
| [[DUMB (File Format)|DUMB]]
| Binary Data
|-
| [[EGMC (File Format)|EGMC]]
| Editor Object to Static Geometry Map
|-
| [[ELSC (File Format)|ELSC]]
| Electric Particle System
|-
| [[FONT (File Format)|FONT]]
| Font
|-
| [[FRME (File Format)|FRME]]
| GUI Frame
|-
| [[FSM2 (File Format)|FSM2]]
| Finite State Machine 2
|-
| [[HINT (File Format)|HINT]]
| Hint System
|-
| [[MAPA (File Format)|MAPA]]
| Area Map
|-
| [[MAPW (File Format)|MAPW]]
| World Map
|-
| [[MLVL (File Format)|MLVL]]
| World
|-
| [[MREA (File Format)|MREA]]
| Area
|-
| [[NTWK (File Format)|NTWK]]
| Tweaks
|-
| [[PAK (Metroid Prime)|PAK]]
| Package
|-
| [[PART (File Format)|PART]]
| Particle System
|-
| [[PATH (File Format)|PATH]]
| Pathfinding
|-
| [[RSO (File Format)|RSO]]
| Shared Object
|-
| [[RULE (File Format)|RULE]]
| Rule Set
|-
| [[SAND (File Format)|SAND]]
| Source Animation Data
|-
| [[SAVA (File Format)|SAVA]]
| Area Save Info
|-
| [[SAVW (File Format)|SAVW]]
| World Save Info
|-
| [[SCAN (Metroid Prime 2)|SCAN]]
| Scannable Object Info
|-
| [[SPSC (File Format)|SPSC]]
| Spawn Particle System
|-
| [[STRG (File Format)|STRG]]
| String Table
|-
| [[STRM (File Format)|STRM]]
| Streamed Audio
|-
| [[SWHC (File Format)|SWHC]]
| Swoosh Particle System
|-
| [[THP (File Format)|THP]]
| Video
|-
| [[TXTR (Metroid Prime)|TXTR]]
| Texture
|-
| [[USRC (File Format)|USRC]]
| User Evaluator Data
|-
| [[WPSC (File Format)|WPSC]]
| Weapon Particle System
|}

[[Category:Games]]
[[Category:Metroid Prime 3: Corruption]]

Metroid Prime

2016-12-13T18:45:56Z

Jackoalan: /* Builds */

'''Metroid Prime''' is the first game developed by Retro Studios.

__TOC__

== Builds ==

{| class="wikitable"
! Build
! Date/Time
! Version
|-
| {{none}}
| Jul 24 2002 14:11:18
| Multi-Game Demo Disc v7-9
|-
| v1.028
| 10/29/2002 2:21:25
| GameCube 0-00 NTSC (Original Release)
|-
| v1.101
| 1/14/2003 17:57:24
| EUR Interactive Multi-Game Demo Disc: February 2003
|-
| v1.110
| 2/4/2003 22:16:07
| GameCube PAL
|-
| v1.111
| 2/11/2003 10:03:22
| GameCube 0-00 NTSC-J (Original JP Release)
|-
| v1.111
| 3/10/2003 17:56:21
| GameCube 0-02 NTSC (Player's Choice)
|-
| v3.570
| 2008/07/22 12:23
| Wii de Asobu
|-
| v3.593
| 2008/08/21 17:09
| Metroid Prime: Trilogy NTSC
|-
| v3.629
| 2009/01/15 14:08
| Metroid Prime: Trilogy PAL
|}

== Formats ==

{| class="wikitable"
! Format
! Contents
|-
| [[AFSM (File Format)|AFSM]]
| AI Finite State Machine
|-
| [[AGSC (File Format)|AGSC]]
| Audio Group Set
|-
| [[ANCS (File Format)|ANCS]]
| Animation/Character Set
|-
| [[ANIM (File Format)|ANIM]]
| Animation
|-
| [[ATBL (File Format)|ATBL]]
| Audio Lookup Table
|-
| [[CINF (File Format)|CINF]]
| Skeleton
|-
| [[CMDL (Metroid Prime)|CMDL]]
| Model
|-
| [[CRSC (File Format)|CRSC]]
| Collision Response Particle System
|-
| [[CSKR (File Format)|CSKR]]
| Skin Rules
|-
| [[CSNG (File Format)|CSNG]]
| MusyX MIDI File
|-
| [[CTWK (File Format)|CTWK]]
| Tweaks
|-
| [[DCLN (File Format)|DCLN]]
| Dynamic Collision
|-
| [[DGRP (File Format)|DGRP]]
| Dependency Group
|-
| [[DPSC (File Format)|DPSC]]
| Decal Particle System
|-
| [[DSP (File Format)|DSP]]
| Music
|-
| [[DUMB (File Format)|DUMB]]
| Binary Data
|-
| [[ELSC (File Format)|ELSC]]
| Electric Particle System
|-
| [[EVNT (File Format)|EVNT]]
| Animation Event Data
|-
| [[FONT (File Format)|FONT]]
| Font
|-
| [[FRME (File Format)|FRME]]
| GUI Frame
|-
| [[HINT (File Format)|HINT]]
| Hint System
|-
| [[MAPA (File Format)|MAPA]]
| Area Map
|-
| [[MAPU (File Format)|MAPU]]
| Universe Map
|-
| [[MAPW (File Format)|MAPW]]
| World Map
|-
| [[MLVL (File Format)|MLVL]]
| World
|-
| [[MREA (Metroid Prime)|MREA]]
| Area
|-
| [[PAK (Metroid Prime)|PAK]]
| Package
|-
| [[PART (File Format)|PART]]
| Particle System
|-
| [[PATH (File Format)|PATH]]
| Pathfinding
|-
| [[REL (File Format)|REL]]
| Relocatable Module
|-
| [[SAVW (File Format)|SAVW]]
| World Save Info
|-
| [[SCAN (Metroid Prime)|SCAN]]
| Scannable Object Info
|-
| [[STRG (File Format)|STRG]]
| String Table
|-
| [[SWHC (File Format)|SWHC]]
| Swoosh Particle System
|-
| [[THP (File Format)|THP]]
| Video
|-
| [[TXTR (Metroid Prime)|TXTR]]
| Texture
|-
| [[WPSC (File Format)|WPSC]]
| Weapon Particle System
|}

[[Category:Games]]
[[Category:Metroid Prime]]

AGSC (File Format)

2016-08-31T05:52:22Z

Jackoalan: /* Curves */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID''':

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Sound object type''' <ol start="0"><li>SoundMacro</li><li>Table</li><li value=4>Keymap</li><li value=8>Layer</li></ol>
|-
| 0x1
| 1
| '''Unique ID''' (per type namespacing)
|-
| 0x2
| colspan=2 {{unknown|End of ObjectID}}
|}

'''Note:''' This is the ID structure produced by MusyX data export tool used for ''Metroid Prime''
(which allocates all group ObjectIDs on export). The ObjectID structure is actually an arbitrary 16-bits in MusyX
(limited to 14-bit uniqueness). Based on findings from other games, this upper-byte type source is not 100% reliable,
since Factor5 updated the tool during the console's lifetime.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x34
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x35
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x36
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x37
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values (although typically in MIDI range [0,127])

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 2
| '''Definite Key'''; The default pitch (usually 0x3C00... the second byte may possibly be the MIDI channel)
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Parax will dump all sound effects contained in a given AGSC file.

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

AGSC (File Format)

2016-08-31T05:50:34Z

Jackoalan: /* ADSR */

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/". Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID''':

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Sound object type''' <ol start="0"><li>SoundMacro</li><li>Table</li><li value=4>Keymap</li><li value=8>Layer</li></ol>
|-
| 0x1
| 1
| '''Unique ID''' (per type namespacing)
|-
| 0x2
| colspan=2 {{unknown|End of ObjectID}}
|}

'''Note:''' This is the ID structure produced by MusyX data export tool used for ''Metroid Prime''
(which allocates all group ObjectIDs on export). The ObjectID structure is actually an arbitrary 16-bits in MusyX
(limited to 14-bit uniqueness). Based on findings from other games, this upper-byte type source is not 100% reliable,
since Factor5 updated the tool during the console's lifetime.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x34
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x35
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x36
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x37
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Attack time'''; in milliseconds
|-
| 0x2
| 2
| '''Decay time'''; in milliseconds
|-
| 0x4
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0x6
| 2
| '''Release time'''; in milliseconds
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 2
| '''Definite Key'''; The default pitch (usually 0x3C00... the second byte may possibly be the MIDI channel)
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Parax will dump all sound effects contained in a given AGSC file.

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

ANIM (Metroid Prime)

2016-08-27T21:16:00Z

Jackoalan: /* Layout */

''This article is for the ANIM format used in ''Metroid Prime'' and ''Metroid Prime 2: Echoes''. See [[ANIM (File Format)]] for the other revisions of this format.''

The '''ANIM format''' is used in conjunction with [[CINF (File Format)|CINF]] + [[CSKR (File Format)|CSKR]] rigging to animate [[CMDL (Metroid Prime)|CMDL meshes]]. The format is largely the same between the two games, with the main difference being that starting in ''Metroid Prime 2'', support for animating scale was added.

There are two versions of the ANIM format (indicated by the file's first u32 value), one with compressed animations and one with uncompressed ones:

{| class="wikitable"
!Version
!Description
|-
|0x0
|[[#Quaternion Array Format (Uncompressed)|Quaternion Array Format (Uncompressed)]]
|-
|0x2
|[[#Rotation Vector Bitstream Format (Compressed)|Rotation Vector Bitstream Format (Compressed)]]
|}

== Quaternion Array Format (Uncompressed) ==

The '''Quaternion Array Format''' (0x0) is a less common animation format. In ''Metroid Prime'', it only appears in a Ridley intro animation and the rotating pirate data artifact hologram above the Impact Crater, as well as some unused Samus animations, while in ''Metroid Prime 2'', it only seems to show up in some draft/test animations not used in the final game.

This format stores uncompressed animations by mapping animation channels to bones, supplying rotations as an array of [[wikipedia:Quaternion|quaternion]] (WXYZ) keys and translations/scales as an array of XYZ keys. Translations may be specified for a subset of bones as an array of XYZ keys. In ''Metroid Prime'', rotation keys are required on every channel, while translations may be specified for a subset of bones. In ''Metroid Prime 2'', all three transform components are opt-in.

=== Layout ===

{| class="wikitable"
!Offset
!Type
!style="width: 215px;"|Element Count
!style="width: 240px;"|Name
!Notes
!MP1
!MP2
|-
|0x4
|float
|1
|'''Duration'''
|'''[1/2 in CCharAnimTime]''' Time in seconds that the animation plays for
|{{check}}
|{{check}}
|-
|0x8
|u32
|1
|'''Differential State Enum'''
|'''[2/2 in CCharAnimTime]''' State of ''Duration'' time point for proper integration control <ol start="0"><li>Non Zero</li><li>Zero Increasing</li><li>Zero Steady</li><li>Zero Decreasing</li><li>Infinity</li></ol>
|{{check}}
|{{check}}
|-
|0xC
|float
|1
|'''Key Interval'''
|'''[1/2 in CCharAnimTime]''' Time in seconds between keys of each bone channel (reciprocal of frame-rate)
|{{check}}
|{{check}}
|-
|0x10
|u32
|1
|'''Differential State Enum'''
|'''[2/2 in CCharAnimTime]''' State of ''Key Interval'' time point for proper integration control
|{{check}}
|{{check}}
|-
|0x14
|u32
|1
|'''Key Count'''
|Count of keys for each bone channel (keys are set for every frame of the animation)
|{{check}}
|{{check}}
|-
|0x18
|u32
|1
|'''Root Bone ID'''
|ID of the root bone in this ANIM
|{{check}}
|{{check}}
|-
|0x1C
|u32
|1
|'''Bone Channel Count'''
|Count of bone channel indices in the next array. Always 100.
|{{check}}
|{{check}}
|-
|0x20
|u8
|''Bone Channel Count''
|'''Bone Channel Index Array'''
|This table maps each bone to a bone channel, with the index-position corresponding to a ''Bone ID'' in the associated [[CINF (File Format)|CINF]], while the value corresponds to a bone channel index. The value is 0xFF if the bone is not animated by this ANIM.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Rotation Channel Index Count'''
|Count of rotation channel indices in the next array. Matches the number of valid bone channels.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u8
|''Rotation Channel Index Count''
|'''Rotation Channel Index Array'''
|This table maps each bone channel to a rotation channel, with the index-position corresponding to an entry in the ''Bone Channel Index Array'' above (disregarding 0xFF entries), while the value corresponds to the index of a rotation channel. The value is 0xFF if the bone is not rotated by this ANIM. '''Note:''' In ''Metroid Prime'', every bone channel always has rotations, so this array is omitted.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Translation Channel Index Count'''
|Count of translation channel indices in the next array. Matches the number of valid bone channels.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u8
|''Translation Channel Index Count''
|'''Translation Channel Index Array'''
|This table maps each bonechannel to a translation channel, with the index-position corresponding to an entry in the ''Bone Channel Index Array'' above (disregarding 0xFF entries), while the value corresponds to the index of a translation channel. The value is 0xFF if the bone is not translated by this ANIM.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Scale Channel Index Count'''
|Count of scale channel indices in the next array. Matches the number of valid bone channels.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u8
|''Scale Channel Index Count''
|'''Scale Channel Index Array'''
|This table maps each bone channel to a scale channel, with the index-position corresponding to an entry in the ''Bone Channel Index Array'' above (disregarding 0xFF entries), while the value corresponds to the index of a scale channel. The value is 0xFF if the bone is not scaled by this ANIM.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Scale Key Count'''
|Count of elements in ''Scale Key Array'' below
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|float3
|''Scale Key Count''
|'''Scale Key Array'''
|The scale keys are interleaved as such (bone-major):
<pre>
|------------|------------|-----|------------|
| bone0/key0 | bone0/key1 | ... | bone0/keyN |
| bone1/key0 | bone1/key1 | ... | bone1/keyN |
| .......... | .......... | ... | .......... |
| boneN/key0 | boneN/key1 | ... | boneN/keyN |
|------------|------------|-----|------------|
</pre>
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Rotation Key Count'''
|Count of elements in ''Rotation Key Array'' below
|{{check}}
|{{check}}
|-
|{{unknown|}}
|float4
|''Rotation Key Count''
|'''Rotation Key Array'''
|The rotation keys are interleaved the same way as the scale keys. In ''Metroid Prime 2'', any bone channels that were marked 0xFF in the ''Rotation Channel Index Array'' are skipped.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Translation Key Count'''
|Count of elements in ''Translation Key Array'' below
|{{check}}
|{{check}}
|-
|{{unknown|}}
|float3
|''Translation Key Count''
|'''Translation Key Array'''
|The translation keys are interleaved the same way as the scale keys. Any bone channels that were marked 0xFF in the ''Translation Channel Index Array'' are skipped.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|[[EVNT (File Format)|EVNT]]
|1
|'''EVNT Ref'''
|ID for this ANIM's [[EVNT (File Format)|EVNT]] resource, or 0xFFFFFFFF if no events triggered
|{{check}}
|{{nocheck}}
|}

== Rotation Vector Bitstream Format (Compressed) ==

The '''Rotation Vector Bitstream Format''' (0x2) is the most widely used animation format.
The format uses a compressed [[wikipedia:Bitstream|bitstream]] to store keys that have been
[[wikipedia:Delta encoding|delta encoded]] and [[wikipedia:Quantization (signal processing)|quantized]]
to make for a very compact, compressed animation. The data is processed sequentially to reconstruct the
uncompressed bone channel data as quaternions.

In addition to the bitstream quantization, the format includes a bitmap specifying which frames of the animation have
keys added. Consequently, the runtime generates missing keys via interpolation (reducing animation size further).

=== Key Values ===
When decoding the animation, each bone's attribute values are initialized to the ''Initial *''
values in the ''bone channel descriptors''. For every frame of every bone channel, the key value in the bitstream is ''added''
with the previous key value (to resolve the delta encoding).

Once resolved, rotation components are divided by ''Rotation Divisor'', resulting in an axis-angle
[[wikipedia:Axis–angle_representation#Rotation_vector|rotation vector]]. This rotation vector is converted
to quaternion imaginary components with the W component derived via normalized-difference and a ''sign-bit''
packed into the bitstream:

<pre>
q = π / 2.0 / rotation_divisor
X = sin(rx * q)
Y = sin(ry * q)
Z = sin(rz * q)
W = sqrt(MAX((1.0 - (X*X + Y*Y + Z*Z)), 0.0))
W = sign_bit ? -W : W
</pre>

Translation components are multiplied by ''Translation Multiplier'', and scale components are multiplied by ''Scale Multiplier''.

=== Layout ===

{| class="wikitable"
!Type
!style="width: 220px;"|Element Count
!style="width: 240px;"|Name
!Notes
!MP1
!MP2
|-
|u32
|1
|'''Scratch Size'''
|Amount of memory that the animation system needs to allocate to process animation
|{{check}}
|{{check}}
|-
|[[EVNT (File Format)|EVNT]]
|1
|'''EVNT Ref'''
|ID for this ANIM's [[EVNT (File Format)|EVNT]] resource, or 0xFFFFFFFF if no events triggered
|{{check}}
|{{nocheck}}
|-
|u32
|1
|{{unknown|Unknown 1}}
|Always 0x1
|{{check}}
|{{nocheck}}
|-
|u16
|1
|{{unknown|Unknown 2}}
|
|{{nocheck}}
|{{check}}
|-
|float
|1
|'''Duration'''
|Time in seconds that the animation plays for
|{{check}}
|{{check}}
|-
|float
|1
|'''Interval'''
|Time in seconds between frames (reciprocal of frame-rate, typically 30-fps)
|{{check}}
|{{check}}
|-
|u32
|1
|'''Root Bone ID'''
|ID of the root bone in this ANIM
|{{check}}
|{{check}}
|-
|u32
|1
|'''Looping Flag'''
|When non-zero, engine identifies this ANIM as looping
|{{check}}
|{{check}}
|-
|u32
|1
|'''Rotation Divisor'''
|Rotation vectors are divided by this value before being applied
|{{check}}
|{{check}}
|-
|float
|1
|'''Translation Multiplier'''
|Translation vectors are multiplied by this value before being applied
|{{check}}
|{{check}}
|-
|float
|1
|'''Scale Multiplier'''
|Scale vectors are multiplied by this value before being applied
|{{nocheck}}
|{{check}}
|-
|u32
|1
|'''Bone Channel Count'''
|Count of bone channels present in ANIM
|{{check}}
|{{check}}
|-
|u32
|1
|{{unknown|Unknown 4}}
|Always 0x1
|{{check}}
|{{check}}
|-
|u32
|1
|'''Key Bitmap Length'''
|Number of bits in ''Key Bitmap''
|{{check}}
|{{check}}
|-
|u32
|round_up(''Key Bitmap Length'' / 32)
|'''Key Bitmap'''
|Word-packed bitmap. Each word is read from least-significant to most-significant bit. A set bit indicates the frame at the bit's position has keys for each bone channel. If the bit is unset, the keys must be generated via interpolation.
|{{check}}
|{{check}}
|-
|u32
|1
|'''Bone Channel Count'''
|Count of animated bone channels (matches the previous bone channel count)
|{{check}}
|{{nocheck}}
|-
|u32
|1
|'''Bone Channel Descriptor Count'''
|Count of bone channel descriptors in ''Bone Channel Descriptor Table''. Matches the ''Bone Channel Counts''.
|{{check}}
|{{check}}
|-
|[[#Bone Channel Descriptor|Bone Channel Descriptor]]
|''Bone Channel Descriptor Count''
|'''Bone Channel Descriptor Table'''
|Table describing animated bone channels
|{{check}}
|{{check}}
|-
|u32
|<remainder of file>
|'''Key Bitstream'''
|Word-packed bitstream laid out as described by the descriptor table. The bitstream is unpacked just like ''Key Bitmap'' (least-significant to most-significant).
Key values are tightly-packed, quantized integers whose bit-depth is specified by the ''* Bits'' values in the descriptor table.
Each bone-channel key-set starts with a single bit providing the ''W sign-bit'' (1 for negative, 0 for positive).

The key integers are signed using [[wikipedia:Two's complement|Two's complement]] representation.

The keys are interleaved as such (key-major):
<pre>
|------------|------------|-----|------------|
| bone0/key0 | bone1/key0 | ... | boneN/key0 |
| bone0/key1 | bone1/key1 | ... | boneN/key1 |
| .......... | .......... | ... | .......... |
| bone0/keyN | bone1/keyN | ... | boneN/keyN |
|------------|------------|-----|------------|
</pre>
|{{check}}
|{{check}}
|}

=== Bone Channel Descriptor ===

{| class="wikitable"
!Offset
!Type
!Name
!Notes
!MP1
!MP2
|-
|0x0
|u32
|'''Bone ID'''
|''Bone ID'' in the associated [[CINF (File Format)|CINF]] for this bone channel
|{{check}}
|{{check}}
|-
|0x4
|u16
|'''Rotation Key Count'''
|Number of rotation keys in the bitstream for this bone channel.
'''In MP2, if this value is 0, the remaining Rotation fields aren't present'''
|{{check}}
|{{check}}
|-
|0x6
|s16
|'''Initial Rotation X'''
|Initial X value of bone's rotation vector
|{{check}}
|{{check}}
|-
|0x8
|u8
|'''Rotation Bits X'''
|Number of bits allocated to bone's rotation delta X in bitstream
|{{check}}
|{{check}}
|-
|0x9
|s16
|'''Initial Rotation Y'''
|Initial Y value of bone's rotation vector
|{{check}}
|{{check}}
|-
|0xB
|u8
|'''Rotation Bits Y'''
|Number of bits allocated to bone's rotation delta Y in bitstream
|{{check}}
|{{check}}
|-
|0xC
|s16
|'''Initial Rotation Z'''
|Initial Z value of bone's rotation vector
|{{check}}
|{{check}}
|-
|0xE
|u8
|'''Rotation Bits Z'''
|Number of bits allocated to bone's rotation delta Z in bitstream
|{{check}}
|{{check}}
|-
|0xF
|u16
|'''Translation Key Count'''
|If this bone channel has an animated translation, its value will match ''Rotation Key Count''; otherwise the value will be 0.
'''If the value is 0, the remaining Translation fields aren't present'''
|{{check}}
|{{check}}
|-
|0x11
|s16
|'''Initial Translation X'''
|Initial X value of bone's translation vector
|{{check}}
|{{check}}
|-
|0x13
|u8
|'''Translation Bits X'''
|Number of bits allocated to bone's translation delta X in bitstream
|{{check}}
|{{check}}
|-
|0x14
|s16
|'''Initial Translation Y'''
|Initial Y value of bone's translation vector
|{{check}}
|{{check}}
|-
|0x16
|u8
|'''Translation Bits Y'''
|Number of bits allocated to bone's translation delta Y in bitstream
|{{check}}
|{{check}}
|-
|0x17
|s16
|'''Initial Translation Z'''
|Initial Z value of bone's translation vector
|{{check}}
|{{check}}
|-
|0x19
|u8
|'''Translation Bits Z'''
|Number of bits allocated to bone's translation delta Z in bitstream
|{{check}}
|{{check}}
|-
|0x1A
|u16
|'''Scale Key Count'''
|If this bone channel has an animated scale, its value will match ''Scale Key Count''; otherwise the value will be 0.
'''If the value is 0, the remaining Scale fields aren't present'''
|{{nocheck}}
|{{check}}
|-
|0x1C
|s16
|'''Initial Scale X'''
|Initial X value of bone's scale vector
|{{nocheck}}
|{{check}}
|-
|0x1E
|u8
|'''Scale Bits X'''
|Number of bits allocated to bone's scale delta X in bitstream
|{{nocheck}}
|{{check}}
|-
|0x1F
|s16
|'''Initial Scale Y'''
|Initial Y value of bone's scale vector
|{{nocheck}}
|{{check}}
|-
|0x21
|u8
|'''Scale Bits Y'''
|Number of bits allocated to bone's scale delta Y in bitstream
|{{nocheck}}
|{{check}}
|-
|0x22
|s16
|'''Initial Scale Z'''
|Initial Z value of bone's scale vector
|{{nocheck}}
|{{check}}
|-
|0x24
|u8
|'''Scale Bits Z'''
|Number of bits allocated to bone's scale delta Z in bitstream
|{{nocheck}}
|{{check}}
|-
|0x25
|colspan=5 {{unknown|End of descriptor}}
|}

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

ANIM (Metroid Prime)

2016-08-27T21:15:29Z

Jackoalan: /* Layout */

''This article is for the ANIM format used in ''Metroid Prime'' and ''Metroid Prime 2: Echoes''. See [[ANIM (File Format)]] for the other revisions of this format.''

The '''ANIM format''' is used in conjunction with [[CINF (File Format)|CINF]] + [[CSKR (File Format)|CSKR]] rigging to animate [[CMDL (Metroid Prime)|CMDL meshes]]. The format is largely the same between the two games, with the main difference being that starting in ''Metroid Prime 2'', support for animating scale was added.

There are two versions of the ANIM format (indicated by the file's first u32 value), one with compressed animations and one with uncompressed ones:

{| class="wikitable"
!Version
!Description
|-
|0x0
|[[#Quaternion Array Format (Uncompressed)|Quaternion Array Format (Uncompressed)]]
|-
|0x2
|[[#Rotation Vector Bitstream Format (Compressed)|Rotation Vector Bitstream Format (Compressed)]]
|}

== Quaternion Array Format (Uncompressed) ==

The '''Quaternion Array Format''' (0x0) is a less common animation format. In ''Metroid Prime'', it only appears in a Ridley intro animation and the rotating pirate data artifact hologram above the Impact Crater, as well as some unused Samus animations, while in ''Metroid Prime 2'', it only seems to show up in some draft/test animations not used in the final game.

This format stores uncompressed animations by mapping animation channels to bones, supplying rotations as an array of [[wikipedia:Quaternion|quaternion]] (WXYZ) keys and translations/scales as an array of XYZ keys. Translations may be specified for a subset of bones as an array of XYZ keys. In ''Metroid Prime'', rotation keys are required on every channel, while translations may be specified for a subset of bones. In ''Metroid Prime 2'', all three transform components are opt-in.

=== Layout ===

{| class="wikitable"
!Offset
!Type
!style="width: 215px;"|Element Count
!style="width: 240px;"|Name
!Notes
!MP1
!MP2
|-
|0x4
|float
|1
|'''Duration'''
|'''[1/2 in CCharAnimTime]''' Time in seconds that the animation plays for
|{{check}}
|{{check}}
|-
|0x8
|u32
|1
|'''Differential State Enum'''
|'''[2/2 in CCharAnimTime]''' State of ''Duration'' time point for proper integration control <ol start="0"><li>Non Zero</li><li>Zero Increasing</li><li>Zero Steady</li><li>Zero Decreasing</li><li>Infinity</li></ol>
|{{check}}
|{{check}}
|-
|0xC
|float
|1
|'''Key Interval'''
|'''[1/2 in CCharAnimTime]''' Time in seconds between keys of each bone channel (reciprocal of frame-rate)
|{{check}}
|{{check}}
|-
|0x10
|u32
|1
|'''Differential State Enum'''
|'''[2/2 in CCharAnimTime]''' State of ''Key Interval'' time point for proper integration control
|{{check}}
|{{check}}
|-
|0x14
|u32
|1
|'''Key Count'''
|Count of keys for each bone channel (keys are set for every frame of the animation)
|{{check}}
|{{check}}
|-
|0x18
|u32
|1
|'''Root Bone ID'''
|ID of the root bone in this ANIM
|{{check}}
|{{check}}
|-
|0x1C
|u32
|1
|'''Bone Channel Count'''
|Count of bone channel indices in the next array. Always 100.
|{{check}}
|{{check}}
|-
|0x20
|u8
|''Bone Channel Count''
|'''Bone Channel Index Array'''
|This table maps each bone to a bone channel, with the index-position corresponding to a ''Bone ID'' in the associated [[CINF (File Format)|CINF]], while the value corresponds to a bone channel index. The value is 0xFF if the bone is not animated by this ANIM.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Rotation Channel Index Count'''
|Count of rotation channel indices in the next array. Matches the number of valid bone channels.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u8
|''Rotation Channel Index Count''
|'''Rotation Channel Index Array'''
|This table maps each bone channel to a rotation channel, with the index-position corresponding to an entry in the ''Bone Channel Index Array'' above (disregarding 0xFF entries), while the value corresponds to the index of a rotation channel. The value is 0xFF if the bone is not rotated by this ANIM. '''Note:''' In ''Metroid Prime'', every bone channel always has rotations, so this array is omitted.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Translation Channel Index Count'''
|Count of translation channel indices in the next array. Matches the number of valid bone channels.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u8
|''Translation Channel Index Count''
|'''Translation Channel Index Array'''
|This table maps each bonechannel to a translation channel, with the index-position corresponding to an entry in the ''Bone Channel Index Array'' above (disregarding 0xFF entries), while the value corresponds to the index of a translation channel. The value is 0xFF if the bone is not translated by this ANIM.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Scale Channel Index Count'''
|Count of scale channel indices in the next array. Matches the number of valid bone channels.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u8
|''Scale Channel Index Count''
|'''Scale Channel Index Array'''
|This table maps each bone channel to a scale channel, with the index-position corresponding to an entry in the ''Bone Channel Index Array'' above (disregarding 0xFF entries), while the value corresponds to the index of a scale channel. The value is 0xFF if the bone is not scaled by this ANIM.
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Scale Key Count'''
|Count of elements in ''Scale Key Array'' below
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|float3
|''Scale Key Count''
|'''Scale Key Array'''
|The scale keys are interleaved as such (bone-major):
<pre>
|------------|------------|-----|------------|
| bone0/key0 | bone0/key1 | ... | bone0/keyN |
| bone1/key0 | bone1/key1 | ... | bone1/keyN |
| .......... | .......... | ... | .......... |
| boneN/key0 | boneN/key1 | ... | boneN/keyN |
|------------|------------|-----|------------|
</pre>
|{{nocheck}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Rotation Key Count'''
|Count of elements in ''Rotation Key Array'' below
|{{check}}
|{{check}}
|-
|{{unknown|}}
|float4
|''Rotation Key Count''
|'''Rotation Key Array'''
|The rotation keys are interleaved the same way as the scale keys. In ''Metroid Prime 2'', any bone channels that were marked 0xFF in the ''Rotation Channel Index Array'' are skipped.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|u32
|1
|'''Translation Key Count'''
|Count of elements in ''Translation Key Array'' below
|{{check}}
|{{check}}
|-
|{{unknown|}}
|float3
|''Translation Key Count''
|'''Translation Key Array'''
|The translation keys are interleaved the same way as the scale keys. Any bone channels that were marked 0xFF in the ''Translation Channel Index Array'' are skipped.
|{{check}}
|{{check}}
|-
|{{unknown|}}
|[[EVNT (File Format)|EVNT]]
|1
|'''EVNT Ref'''
|ID for this ANIM's [[EVNT (File Format)|EVNT]] resource, or 0xFFFFFFFF if no events triggered
|{{check}}
|{{nocheck}}
|}

== Rotation Vector Bitstream Format (Compressed) ==

The '''Rotation Vector Bitstream Format''' (0x2) is the most widely used animation format.
The format uses a compressed [[wikipedia:Bitstream|bitstream]] to store keys that have been
[[wikipedia:Delta encoding|delta encoded]] and [[wikipedia:Quantization (signal processing)|quantized]]
to make for a very compact, compressed animation. The data is processed sequentially to reconstruct the
uncompressed bone channel data as quaternions.

In addition to the bitstream quantization, the format includes a bitmap specifying which frames of the animation have
keys added. Consequently, the runtime generates missing keys via interpolation (reducing animation size further).

=== Key Values ===
When decoding the animation, each bone's attribute values are initialized to the ''Initial *''
values in the ''bone channel descriptors''. For every frame of every bone channel, the key value in the bitstream is ''added''
with the previous key value (to resolve the delta encoding).

Once resolved, rotation components are divided by ''Rotation Divisor'', resulting in an axis-angle
[[wikipedia:Axis–angle_representation#Rotation_vector|rotation vector]]. This rotation vector is converted
to quaternion imaginary components with the W component derived via normalized-difference and a ''sign-bit''
packed into the bitstream:

<pre>
q = π / 2.0 / rotation_divisor
X = sin(rx * q)
Y = sin(ry * q)
Z = sin(rz * q)
W = sqrt(MAX((1.0 - (X*X + Y*Y + Z*Z)), 0.0))
W = sign_bit ? -W : W
</pre>

Translation components are multiplied by ''Translation Multiplier'', and scale components are multiplied by ''Scale Multiplier''.

=== Layout ===

{| class="wikitable"
!Type
!style="width: 220px;"|Element Count
!style="width: 240px;"|Name
!Notes
!MP1
!MP2
|-
|u32
|1
|'''Scratch Size'''
|Amount of memory that the animation system needs to allocate to process animation
|{{check}}
|{{check}}
|-
|[[EVNT (File Format)|EVNT]]
|1
|'''EVNT Ref'''
|ID for this ANIM's [[EVNT (File Format)|EVNT]] resource, or 0xFFFFFFFF if no events triggered
|{{check}}
|{{nocheck}}
|-
|u32
|1
|{{unknown|Unknown 1}}
|Always 0x1
|{{check}}
|{{nocheck}}
|-
|u16
|1
|{{unknown|Unknown 2}}
|
|{{nocheck}}
|{{check}}
|-
|float
|1
|'''Duration'''
|Time in seconds that the animation plays for
|{{check}}
|{{check}}
|-
|float
|1
|'''Interval'''
|Time in seconds between frames (reciprocal of frame-rate, typically 30-fps)
|{{check}}
|{{check}}
|-
|u32
|1
|'''Root Bone ID'''
|ID of the root bone in this ANIM
|{{check}}
|{{check}}
|-
|u32
|1
|'''Looping flag'''
|When non-zero, engine identifies this ANIM as looping
|{{check}}
|{{check}}
|-
|u32
|1
|'''Rotation Divisor'''
|Rotation vectors are divided by this value before being applied
|{{check}}
|{{check}}
|-
|float
|1
|'''Translation Multiplier'''
|Translation vectors are multiplied by this value before being applied
|{{check}}
|{{check}}
|-
|float
|1
|'''Scale Multiplier'''
|Scale vectors are multiplied by this value before being applied
|{{nocheck}}
|{{check}}
|-
|u32
|1
|'''Bone Channel Count'''
|Count of bone channels present in ANIM
|{{check}}
|{{check}}
|-
|u32
|1
|{{unknown|Unknown 4}}
|Always 0x1
|{{check}}
|{{check}}
|-
|u32
|1
|'''Key Bitmap Length'''
|Number of bits in ''Key Bitmap''
|{{check}}
|{{check}}
|-
|u32
|round_up(''Key Bitmap Length'' / 32)
|'''Key Bitmap'''
|Word-packed bitmap. Each word is read from least-significant to most-significant bit. A set bit indicates the frame at the bit's position has keys for each bone channel. If the bit is unset, the keys must be generated via interpolation.
|{{check}}
|{{check}}
|-
|u32
|1
|'''Bone Channel Count'''
|Count of animated bone channels (matches the previous bone channel count)
|{{check}}
|{{nocheck}}
|-
|u32
|1
|'''Bone Channel Descriptor Count'''
|Count of bone channel descriptors in ''Bone Channel Descriptor Table''. Matches the ''Bone Channel Counts''.
|{{check}}
|{{check}}
|-
|[[#Bone Channel Descriptor|Bone Channel Descriptor]]
|''Bone Channel Descriptor Count''
|'''Bone Channel Descriptor Table'''
|Table describing animated bone channels
|{{check}}
|{{check}}
|-
|u32
|<remainder of file>
|'''Key Bitstream'''
|Word-packed bitstream laid out as described by the descriptor table. The bitstream is unpacked just like ''Key Bitmap'' (least-significant to most-significant).
Key values are tightly-packed, quantized integers whose bit-depth is specified by the ''* Bits'' values in the descriptor table.
Each bone-channel key-set starts with a single bit providing the ''W sign-bit'' (1 for negative, 0 for positive).

The key integers are signed using [[wikipedia:Two's complement|Two's complement]] representation.

The keys are interleaved as such (key-major):
<pre>
|------------|------------|-----|------------|
| bone0/key0 | bone1/key0 | ... | boneN/key0 |
| bone0/key1 | bone1/key1 | ... | boneN/key1 |
| .......... | .......... | ... | .......... |
| bone0/keyN | bone1/keyN | ... | boneN/keyN |
|------------|------------|-----|------------|
</pre>
|{{check}}
|{{check}}
|}

=== Bone Channel Descriptor ===

{| class="wikitable"
!Offset
!Type
!Name
!Notes
!MP1
!MP2
|-
|0x0
|u32
|'''Bone ID'''
|''Bone ID'' in the associated [[CINF (File Format)|CINF]] for this bone channel
|{{check}}
|{{check}}
|-
|0x4
|u16
|'''Rotation Key Count'''
|Number of rotation keys in the bitstream for this bone channel.
'''In MP2, if this value is 0, the remaining Rotation fields aren't present'''
|{{check}}
|{{check}}
|-
|0x6
|s16
|'''Initial Rotation X'''
|Initial X value of bone's rotation vector
|{{check}}
|{{check}}
|-
|0x8
|u8
|'''Rotation Bits X'''
|Number of bits allocated to bone's rotation delta X in bitstream
|{{check}}
|{{check}}
|-
|0x9
|s16
|'''Initial Rotation Y'''
|Initial Y value of bone's rotation vector
|{{check}}
|{{check}}
|-
|0xB
|u8
|'''Rotation Bits Y'''
|Number of bits allocated to bone's rotation delta Y in bitstream
|{{check}}
|{{check}}
|-
|0xC
|s16
|'''Initial Rotation Z'''
|Initial Z value of bone's rotation vector
|{{check}}
|{{check}}
|-
|0xE
|u8
|'''Rotation Bits Z'''
|Number of bits allocated to bone's rotation delta Z in bitstream
|{{check}}
|{{check}}
|-
|0xF
|u16
|'''Translation Key Count'''
|If this bone channel has an animated translation, its value will match ''Rotation Key Count''; otherwise the value will be 0.
'''If the value is 0, the remaining Translation fields aren't present'''
|{{check}}
|{{check}}
|-
|0x11
|s16
|'''Initial Translation X'''
|Initial X value of bone's translation vector
|{{check}}
|{{check}}
|-
|0x13
|u8
|'''Translation Bits X'''
|Number of bits allocated to bone's translation delta X in bitstream
|{{check}}
|{{check}}
|-
|0x14
|s16
|'''Initial Translation Y'''
|Initial Y value of bone's translation vector
|{{check}}
|{{check}}
|-
|0x16
|u8
|'''Translation Bits Y'''
|Number of bits allocated to bone's translation delta Y in bitstream
|{{check}}
|{{check}}
|-
|0x17
|s16
|'''Initial Translation Z'''
|Initial Z value of bone's translation vector
|{{check}}
|{{check}}
|-
|0x19
|u8
|'''Translation Bits Z'''
|Number of bits allocated to bone's translation delta Z in bitstream
|{{check}}
|{{check}}
|-
|0x1A
|u16
|'''Scale Key Count'''
|If this bone channel has an animated scale, its value will match ''Scale Key Count''; otherwise the value will be 0.
'''If the value is 0, the remaining Scale fields aren't present'''
|{{nocheck}}
|{{check}}
|-
|0x1C
|s16
|'''Initial Scale X'''
|Initial X value of bone's scale vector
|{{nocheck}}
|{{check}}
|-
|0x1E
|u8
|'''Scale Bits X'''
|Number of bits allocated to bone's scale delta X in bitstream
|{{nocheck}}
|{{check}}
|-
|0x1F
|s16
|'''Initial Scale Y'''
|Initial Y value of bone's scale vector
|{{nocheck}}
|{{check}}
|-
|0x21
|u8
|'''Scale Bits Y'''
|Number of bits allocated to bone's scale delta Y in bitstream
|{{nocheck}}
|{{check}}
|-
|0x22
|s16
|'''Initial Scale Z'''
|Initial Z value of bone's scale vector
|{{nocheck}}
|{{check}}
|-
|0x24
|u8
|'''Scale Bits Z'''
|Number of bits allocated to bone's scale delta Z in bitstream
|{{nocheck}}
|{{check}}
|-
|0x25
|colspan=5 {{unknown|End of descriptor}}
|}

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

CSNG (File Format)

2016-06-22T03:57:25Z

Jackoalan: /* Region Data */

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 3 types of commands
in SNG: ''note'', ''control change'', and ''program change''.

=====Delta Time RLE=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a custom
[[wikipedia:Run-length encoding|RLE scheme]] to adaptively scale the value's precision
to reduce the value's size.

The RLE operates on 16-bit words, with the value 0xffff triggering a continuation,
then a 'dead' 16-bit word skipped over, then the 0xffff is summed with the following RLE value,
looping the decode algorithm.

In Python, decoding works like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTimeRLE(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
if term == 0xffff:
total += 0xffff
dummy = streamIn.ReadU16()
continue
total += term
return total
</syntaxhighlight>

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bits of both bytes are ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====Program Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''program change command'''.

See the [https://www.midi.org/specifications/item/gm-level-1-sound-set standard MIDI program numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Padding'''; always zero
|-
| 0x2
| colspan=2 {{unknown|End of program change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of RLE-compressed
(delta-tick, delta-value) pairs, decoding to signed 16-bit precision. The decoder must track
the absolute time and value, summing each consecutive update for the current time/values.

The algorithm for this RLE is different than the delta-time one for commands. It may
scale down to a single byte if able.

<syntaxhighlight lang="python" line="1">
def DecodeRLE(streamIn):
# high-bit shift-trigger RLE, limited to 2 bytes
term = streamIn.ReadU8()
total = term & 0x7f
if term & 0x80:
total = total * 256 + streamIn.ReadU8()
return total

def DecodeContinuousRLE(streamIn, isValue):
total = 0
while True:
# 1-2 byte RLE accumulated within continuable RLE
term = DecodeRLE(streamIn)
if term == 0x8000:
total += 0xffff
dummy = streamIn.ReadU8()
continue
total += term

# values are signed deltas;
# extending into the high-half of 15-bit precision
if isValue:
if total >= 0x4000:
return total - 0xffff
else:
return total

# times are always forward-deltas
return total
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

CSNG (File Format)

2016-06-20T20:13:18Z

Jackoalan: Multi-track SNG clarifications

The '''CSNG format''' contains MIDI data. It appears in Metroid Prime 1 and 2. It is essentially MusyX's GameCube SNG music format, with a custom header.

__TOC__

== Format ==

All offsets are relative to the start of the main header (after the custom header).

Overall, SNG functions similar to a Type-1 (multi-track) MIDI file, with (up to) 64 tracks
merging their events into 16 General-MIDI sequencer channels. In addition to the multi-track
structure, SNG supports storing MIDI regions as indexed ''patterns'', so songs with repetitive
refrains can save on memory by referencing patterns more than once.

Timings are represented in ''ticks''. Unlike MIDI, the tick-resolution is fixed at 384
ticks per beat (e.g. 120 beats-per-minute works out to <code>384 * 120 / 60 = 768</code> ticks-per-second).

=== Custom Header ===

This 0x14-byte header isn't part of the MusyX format; it appears at the start of the file. After parsing this the rest of the file is copied into a buffer and then passed to the MusyX functions.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Magic'''; (always 0x2)
|-
| 0x4
| 4
| '''MIDI Setup ID'''
|-
| 0x8
| 4
| '''SongGroup ID'''
|-
| 0xC
| 4
| '''[[AGSC (File Format)|AGSC]] ID'''
|-
| 0x10
| 4
| '''SNG File Length'''
|-
| 0x14
| colspan=2 {{unknown|MusyX data starts}}
|}

=== Header ===

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Track Index Offset'''; usually 0x18 for GCN games
|-
| 0x4
| 4
| '''Region Data Index Offset'''
|-
| 0x8
| 4
| '''Channel Map Offset'''
|-
| 0xC
| 4
| '''Tempo Table Offset'''; 0x0 if tempo doesn't change
|-
| 0x10
| 4
| '''Initial Tempo'''; (commonly 0x78 or 120 beats per minute)
|-
| 0x14
| 4
| {{unknown|'''Unknown'''}}
|-
| 0x18
| colspan=2 {{unknown|End of header}}
|}

===Region Info===

The ''track index'' has offsets relating the first '''region info''' for each track.

There is a sequence of at least 2 region info structures populating each track, last one acting as terminator:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Start Tick'''; time-point to begin executing region data
|-
| 0x4
| 4
| {{unknown|'''Unknown'''}}; commonly 0xffff0000
|-
| 0x8
| 2
| '''Region Data Index'''; used to select region data via the ''region data index''; value is negative on a dummy ''region info'' to terminate track regions
|-
| 0xA
| 2
| {{unknown|'''Unknown'''}}
|-
| 0xC
| colspan=2 {{unknown|End of region info}}
|}

===Region Data===

Here begins a free-form blob of indexed region data. It starts with a variable-length
'''u32 array''' of SNG offsets for each region, then the region data itself.

====Region Data Header====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Region Data Header Size'''; size of the header ''after'' this field (always 0x8)
|-
| 0x4
| 4
| '''Pitch Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no pitch-wheel messages in region
|-
| 0x8
| 4
| '''Mod Wheel Data Offset'''; (absolute SNG-offset) 0x0 if no mod-wheel messages in region
|-
| 0xC
| colspan=2 {{unknown|End of region data}}
|}

====Region Commands====

After the region data header, the actual playback commands begin. There are only 2 types of commands
in SNG: ''note'' and ''control change''.

=====Delta Time RLE=====

Just like MIDI, each command starts with a '''delta time''' value telling the sequencer
how many ticks to wait after the previous command. Unlike MIDI, Factor5 uses a custom
[[wikipedia:Run-length encoding|RLE scheme]] to adaptively scale the value's precision
to reduce the value's size.

The RLE operates on 16-bit words, with the value 0xffff triggering a continuation,
then a 'dead' 16-bit word skipped over, then the 0xffff is summed with the following RLE value,
looping the decode algorithm.

In Python, decoding works like so:

<syntaxhighlight lang="python" line="1">
def DecodeDeltaTimeRLE(streamIn):
total = 0
while True:
term = streamIn.ReadU16()
if term == 0xffff:
total += 0xffff
dummy = streamIn.ReadU16()
continue
total += term
return total
</syntaxhighlight>

=====Note Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''unset'',
this is a '''note command'''.

Unlike MIDI, which has separate commands for note-on/note-off, SNG attaches a ''note length'' value
to a note-on command, which is then able to track its own lifetime.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Note'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Velocity'''; AND with 0x7f for the value
|-
| 0x2
| 2
| '''Note Length'''; count of ticks before note-off issued by sequencer
|-
| 0x4
| colspan=2 {{unknown|End of note}}
|}

=====Control Change Command=====

When the two bytes following the delta-time != 0xffff, and the high-bit of the first byte is ''set'',
this is a '''control change command'''.

See the [https://www.midi.org/specifications/item/table-3-control-change-messages-data-bytes-2 standard MIDI control numbers] for details.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Value'''; AND with 0x7f for the value
|-
| 0x1
| 1
| '''Control'''; AND with 0x7f for the value
|-
| 0x2
| colspan=2 {{unknown|End of control change}}
|}

=====End Of Region=====

When the two bytes following the delta-time == 0xffff, this region has no more commands.

====Continuous Pitch / Modulation Data====

If the pitch or mod offsets in a region are non-zero, they point to a buffer of RLE-compressed
(delta-tick, delta-value) pairs, decoding to signed 16-bit precision. The decoder must track
the absolute time and value, summing each consecutive update for the current time/values.

The algorithm for this RLE is different than the delta-time one for commands. It may
scale down to a single byte if able.

<syntaxhighlight lang="python" line="1">
def DecodeRLE(streamIn):
# high-bit shift-trigger RLE, limited to 2 bytes
term = streamIn.ReadU8()
total = term & 0x7f
if term & 0x80:
total = total * 256 + streamIn.ReadU8()
return total

def DecodeContinuousRLE(streamIn, isValue):
total = 0
while True:
# 1-2 byte RLE accumulated within continuable RLE
term = DecodeRLE(streamIn)
if term == 0x8000:
total += 0xffff
dummy = streamIn.ReadU8()
continue
total += term

# values are signed deltas;
# extending into the high-half of 15-bit precision
if isValue:
if total >= 0x4000:
return total - 0xffff
else:
return total

# times are always forward-deltas
return total
</syntaxhighlight>

===Channel Map===

This is a simple '''u8 table''' mapping 64 SNG tracks to 16 MIDI channels for instrument selection via the [[AGSC (File Format)#MIDI Setup Entry|SongGroup MIDI-Setup]].

===Tempo Table===

When the SNG has a non-zero tempo table offset, this song features tempo changes.
The change events are simple absolute-tick / BPM pairs.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Tick'''; absolute time-point to perform tempo change
|-
| 0x4
| 4
| '''Tempo'''; new tempo in BPM
|-
| 0x2
| colspan=2 {{unknown|End of tempo change}}
|}

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

AGSC (File Format)

2016-05-31T00:57:12Z

Jackoalan:

'''AGSC''' is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are essentially just embedded MusyX files.

The audio codec used in AGSC is the standard GameCube DSP-ADPCM codec, but MusyX itself also offers uncompressed PCM as an option.

{{todo|Better descriptions for how SoundMacros work and a description for what each command does.}}
{{research|minor|The proj and sdir chunks have a couple unknowns left.}}

__TOC__

== Format ==

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

=== Header ===

==== Metroid Prime ====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| '''D'''
| '''Audio Directory'''. Always "Audio/." Zero-terminated.
|-
| 0x0 + D
| '''N'''
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x0 + D + N
|colspan=2 {{unknown|End of header}}
|}

==== Metroid Prime 2 ====

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| {{unknown|'''Unknown'''; always 1}}
|-
| 0x4
| D
| '''Audio Group Name'''. Zero-terminated.
|-
| 0x4 + D
| 2
| '''Group ID'''; 0xFFFF if unspecified
|-
| 0x6 + D
| 4
| '''Pool size'''
|-
| 0xA + D
| 4
| '''Project size'''
|-
| 0xE + D
| 4
| '''Sample directory size'''
|-
| 0x12 + D
| 4
| '''Sample size'''
|-
| 0x16 + D
| colspan=2 {{unknown|End of header}}
|}

=== Pool ===

The Pool chunk contains sub-chunk tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''SoundMacros Offset''' (always 0x10)
|-
| 0x4
| 4
| '''Tables Offset'''
|-
| 0x8
| 4
| '''Keymaps Offset'''
|-
| 0xC
| 4
| '''Layers Offset'''
|-
| 0x10
| colspan=2 {{unknown|End of entry}}
|}

==== ObjectID ====

After this are four tables of objects. Each object is identified with a 16-bit '''ObjectID''':

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Sound object type''' <ol start="0"><li>SoundMacro</li><li>Table</li><li value=4>Keymap</li><li value=8>Layer</li></ol>
|-
| 0x1
| 1
| '''Unique ID''' (per type namespacing)
|-
| 0x2
| colspan=2 {{unknown|End of ObjectID}}
|}

'''Note:''' This is the ID structure produced by MusyX data export tool used for ''Metroid Prime''
(which allocates all group ObjectIDs on export). The ObjectID structure is actually an arbitrary 16-bits in MusyX
(limited to 14-bit uniqueness). Based on findings from other games, this upper-byte type source is not 100% reliable,
since Factor5 updated the tool during the console's lifetime.

==== SoundMacros ====

The first Pool table denotes MusyX's '''SoundMacros''', small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size''' ''(note: includes the size value itself)''
|-
| 0x4
| 2
| '''SoundMacro ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| 0x8
| colspan=2 {{unknown|Commands begin}}
|}

On the commands, each 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped. Each command is 8 bytes, and is structured as follows:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Command ID''' (varies; there are 79 known commands in the MusyX audio engine.)
|-
| 0x1
| 7
| '''Command arguments''' (varies between commands)
|-
| 0x8
| colspan=2 {{unknown|End of entry}}
|}

The SoundMacro will continue with commands until it terminates when the END command is executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it.

These are the possible commands:

{| class="wikitable"
! width="2%" | ID
! width="7%" | Name
! colspan="91%" | Arguments
|-
| 0x1
| STOP
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
| width="13%" {{unknown|}}
|-
| 0x2
| SPLITKEY
| Keynumber
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x3
| SPLITVEL
| Velocity
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x4
| WAIT_TICKS
| Keyoff
| Random
| Sampleend
| Absolute
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x5
| LOOP
| Keyoff
| Random
| Sampleend
| colspan="2" | SoundMacro step
| colspan="2" | Times
|-
| 0x6
| GOTO
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x7
| WAIT_MS
| Keyoff
| Random
| Sample end
| Absolute
| {{unknown|}}
| colspan="2" | Millisec.
|-
| 0x8
| PLAYMACRO
| Addnote
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| Priority
| MaxVoices
|-
| 0x9
| SENDKEYOFF
| Variable
| Last started
| colspan="5" {{unknown|}}
|-
| 0xA
| SPLITMOD
| Mod value
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0xB
| PIANOPAN
| Scale
| Centerkey
| Centerpan
| colspan="4" {{unknown|}}
|-
| 0xC
| SETADSR
| colspan="2" | Table-ID (ADSR)
| DLS mode
| colspan="4" {{unknown|}}
|-
| 0xD
| SCALEVOLUME
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0xE
| PANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0xF
| ENVELOPE
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| Org vol
| colspan="2" {{unknown|}}
|-
| 0x10
| STARTSAMPLE
| colspan="2" | Sample-ID
| Mode
| colspan="4" | Offset
|-
| 0x11
| STOPSAMPLE
| colspan="7" {{unknown|}}
|-
| 0x12
| KEYOFF
| colspan="7" {{unknown|}}
|-
| 0x13
| SPLITRND
| RND
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x14
| FADE-IN
| Scale
| Add
| colspan="2" | Table-ID (Curve)
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x15
| SPANNING
| Pan position
| colspan="2" | Time ms
| Width
| colspan="3" {{unknown|}}
|-
| 0x16
| SETADSRCTRL
| Attack
| Decay
| Sustain
| Relase
| colspan="3" {{unknown|}}
|-
| 0x17
| RNDNOTE
| Note Lo
| Detune
| Note Hi
| Fixed/Free
| Abs/Rel
| colspan="2" {{unknown|}}
|-
| 0x18
| ADDNOTE
| Add
| Detune
| org key
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x19
| SETNOTE
| Key
| Detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1A
| LASTNOTE
| Add
| detune
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1B
| PORTAMENTO
| Port. State
| Port. Type
| colspan="2" {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1C
| VIBRATO
| Level note
| Level fine
| Modwheel flag
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1D
| PITCHSWEEP1
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1E
| PITCHSWEEP2
| Times
| colspan="2" | Add
| {{unknown|}}
| ms switch
| colspan="2" | Ticks/Millisec.
|-
| 0x1F
| SETPITCH
| colspan="3" | Frequency (Hz)
| colspan="2" | Fine
| colspan="2" {{unknown|}}
|-
| 0x20
| SETPITCHADSR
| colspan="2" | Table-ID (ADSR)
| {{unknown|}}
| Note range
| Detune range
| colspan="2" {{unknown|}}
|-
| 0x21
| SCALEVOLUME DLS
| colspan="2" | Scale
| Org vol
| colspan="4" {{unknown|}}
|-
| 0x22
| MOD2VIBRANGE
| Key range
| Cent range
| colspan="5" {{unknown|}}
|-
| 0x23
| SETUP TREMOLO
| colspan="2" | Tremolo scale
| {{unknown|}}
| colspan="2" | Modw. add scale
| colspan="2" {{unknown|}}
|-
| 0x24
| RETURN
| colspan="7" {{unknown|}}
|-
| 0x25
| GOSUB
| {{unknown|}}
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x28
| TRAP_EVENT
| Event
| colspan="2" | SoundMacro ID
| colspan="2" | SoundMacro step
| colspan="2" {{unknown|}}
|-
| 0x29
| UNTRAP_EVENT
| Event
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
| colspan="2" {{unknown|}}
|-
| 0x2A
| SEND_MESSAGE
| IsVar
| colspan="2" | Macro
| VID
| Variable
| colspan="2" {{unknown|}}
|-
| 0x2B
| GET_MESSAGE
| Variable
| colspan="6" {{unknown|}}
|-
| 0x2C
| GET_VID
| Variable
| PLAY_MACRO
| colspan="5" {{unknown|}}
|-
| 0x30
| ADDAGECOUNT
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x31
| SETAGECOUNT
| {{unknown|}}
| colspan="2" | Counter
| colspan="4" {{unknown|}}
|-
| 0x32
| SENDFLAG
| Flag-ID
| Value
| colspan="5" {{unknown|}}
|-
| 0x33
| PITCHWHEELR
| Range up
| Range down
| colspan="5" {{unknown|}}
|-
| 0x34
| SETPRIORITY
| Prio
| colspan="6" {{unknown|}}
|-
| 0x35
| ADDPRIORITY
| {{unknown|}}
| colspan="2" | Add
| colspan="4" {{unknown|}}
|-
| 0x36
| AGECNTSPEED
| colspan="3" {{unknown|}}
| colspan="4" | Time
|-
| 0x37
| AGECNTVEL
| {{unknown|}}
| colspan="2" | AGE Base
| colspan="2" | AGE Scale
| colspan="2" {{unknown|}}
|-
| 0x40
| VOL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x41
| PAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x42
| PitchW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x43
| ModW_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x44
| PEDAL_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x45
| PORTA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x46
| REVERB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x47
| SPAN_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x48
| DOPPLER_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x49
| TREMOLO_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4A
| PREA_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4B
| PREB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4C
| POSTB_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4D
| AUXAFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x4E
| AUXBFX_SELECT
| MIDI Contr.
| colspan="2" | Scaling percentage
| Combine
| is var.
| Fine scaling
| {{unknown|}}
|-
| 0x50
| SETUP_LFO
| LFO Nr.
| colspan="2" | Period in ms
| colspan="4" {{unknown|}}
|-
| 0x58
| MODE_SELECT
| DLS vol
| ITD
| colspan="5" {{unknown|}}
|-
| 0x59
| SET_KEYGROUP
| group
| kill
| colspan="5" {{unknown|}}
|-
| 0x5A
| SRCMODE_SELECT
| SRC type
| Type 0 SRC filter
| colspan="5" {{unknown|}}
|-
| 0x60
| ADD_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x61
| SUB_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B -
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x62
| MUL_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B *
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x63
| DIV_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B /
| Var/Ctrl
| C
| {{unknown|}}
|-
| 0x64
| ADDI_VARS
| Var/Ctrl
| A =
| Var/Ctrl
| B +
| colspan="2" | Immediate
| {{unknown|}}
|-
| 0x70
| IF_EQUAL
| Ctrl
| A ==
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x71
| IF_LESS
| Ctrl
| A <
| Ctrl
| B
| Not
| colspan="2" | SoundMacro Step
|-
| 0x0
| END
| colspan="7" {{unknown|}}
|}

After the last soundmacro, the table terminated by a value of 0xFFFF.

==== Tables ====

'''Tables''' have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

The tables continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Table ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|ADSR/Curve data}}
|}

===== ADSR =====

When the size of the table data is exactly 8, it may represent ADSR envelopes with this structure:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Attack time (0-255 milliseconds)'''; no multiplication is done to the value
|-
| 0x1
| 1
| '''Attack time (0-65280 milliseconds)'''; multiply value by 256
|-
| 0x2
| 1
| '''Decay time (0-255 milliseconds)'''; no multiplication is done to the value
|-
| 0x3
| 1
| '''Decay time (0-65280 milliseconds)'''; multiply value by 256
|-
| 0x4
| 1
| '''Sustain (percentage)'''; multiply value by 0.0244
|-
| 0x5
| 1
| '''Sustain (percentage)'''; multiply value by 6.25
|-
| 0x6
| 1
| '''Release time (0-255 milliseconds)'''; no multiplication is done to the value
|-
| 0x7
| 1
| '''Release time (0-65280 milliseconds)'''; multiply value by 256
|-
| 0x8
| colspan=2 {{unknown|End of ADSR}}
|}

===== DLS ADSR =====

MusyX can also express more advanced envelopes using a modified [[wikipedia:DLS format|DLS]] representation.
This representation includes scaling coefficients to respond to played note and velocity
(so slamming down a key harder plays longer).

The attack and decay members are expressed in ''time-cents''. This may be converted to seconds using:
<code>2timecents / (1200.0 * 65536.0)</code>

The attack and decay scale members are expressed as 0.1% increments in 16.16 fixed-point.
This may be converted to a normalized factor using:
<code>scale / (1000.0 * 65536.0)</code>

'''Note:''' All fields of the envelope are ''little endian''.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Attack time'''; in time-cents
|-
| 0x4
| 4
| '''Decay time'''; in time-cents
|-
| 0x8
| 2
| '''Sustain'''; percentage mapped between [0x0,0x1000]
|-
| 0xA
| 2
| '''Release'''; in milliseconds
|-
| 0xC
| 4
| '''Velocity to Attack Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x10
| 4
| '''Key to Decay Scale'''; 0.1% increments as 16.16 fixed-point
|-
| 0x14
| colspan=2 {{unknown|End of DLS ADSR}}
|}

===== Curves =====

To express a volume curve, the table data is simply an arbitrarily-sized table of <code>uint8_t</code> values

==== Keymaps ====

'''Keymaps''' are swappable, fixed-length tables mapping 128 MIDI keys to sound-producing objects.

The keymaps continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''; (usually 0x1032)
|-
| 0x4
| 2
| '''Keymap ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|128 Keymap entries}}
|}

===== Keymap Entry =====

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Transpose'''
|-
| 0x3
| 1
| '''Pan'''
|-
| 0x4
| 1
| '''Priority Offset'''
|-
| 0x8
| colspan=2 {{Unknown|Padded to 8 bytes}}
|}

==== Layers ====

'''Layers''' are one-to-many, ranged keyboard mappings to sound-producing objects.

The layers continue until 0xffffffff terminator is reached.

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Chunk Size'''
|-
| 0x4
| 2
| '''Layer ObjectID'''
|-
| 0x6
| 2
| '''Padding'''
|-
| Chunk Size
| colspan=2 {{Unknown|Layer data}}
|}

===== Layer Data =====

Within the layer data, there is a '''u32 count''' of layer range structs:

{| class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Key Lo'''
|-
| 0x3
| 1
| '''Key Hi'''
|-
| 0x4
| 1
| '''Transpose'''
|-
| 0x5
| 1
| '''Volume'''
|-
| 0x6
| 1
| '''Priority Offset'''
|-
| 0x7
| 1
| '''Surround Pan'''; (0: extreme forward, 64: center, 127: extreme rearward)
|-
| 0x8
| 1
| '''Pan'''; (0: extreme left, 64: center, 127: extreme right)
|-
| 0xC
| colspan=2 {{Unknown|Padded to 12 bytes}}
|}

The entire Pool chunk is terminated by a value of 0xFFFF.

=== Project ===

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Structurally, the Project is the root of the Audio Group tree, defining one or more ''Song Groups'' or ''SFX Groups''

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 4
| '''Group end offset''' (points to next group in project)
|-
| 0x2
| 2
| '''Group ID'''
|-
| 0x4
| 2
| '''Group Type'''; 0 for SongGroup (for use with [[CSNG (File Format)|CSNG]]), 1 for SFXGroup.
|-
| 0x8
| 4
| '''SoundMacro ID table offset'''
|-
| 0xC
| 4
| '''Sample ID table offset'''
|-
| 0x10
| 4
| '''Tables table offset'''
|-
| 0x14
| 4
| '''Keymaps table offset'''
|-
| 0x18
| 4
| '''Layers table offset'''
|-
| 0x1C
| 4
| '''Normal page table''' (SongGroup) / '''SFX table offset''' (SFXGroup)
|-
| 0x20
| 4
| '''Drum page table offset''' (SongGroup)
|-
| 0x24
| 4
| '''MIDI Setup table offset''' (SongGroup)
|-
| 0x20
| colspan=2 {{unknown|End of group header}}
|}

After the header are a number of data tables.

==== SoundMacro ID Table ====

This is a ranged-table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Contiguous ranges are expressed by IDs with most-significant bit set (0x8000). The range begins on the marked ID and incrementally reaches the next ID in the list, including that ID. All other IDs are singular.

==== Sample ID / Table / Keymap / Layer Tables ====

These function the same way as the SoundMacro ID table, but indexes other types of entities instead.

==== Normal / Drum Page Entry ====

Used to map [https://www.midi.org/specifications/item/gm-level-1-sound-set General MIDI program numbers] (instruments)
to sound entities (macros, keymaps, layers)

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''ObjectID'''
|-
| 0x2
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x3
| 1
| '''Max number of voices'''
|-
| 0x4
| 1
| '''GM Program Number'''
|-
| 0x5
| 1
| '''Padding'''
|}

==== SFX Entry ====

Used to map auto-generated <code>#define</code> IDs (used by game code) to sound entities (macros, keymaps, layers)

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''DefineID'''; referenced by game code
|-
| 0x2
| 2
| '''ObjectID'''
|-
| 0x4
| 1
| '''Priority'''; voices are limited, so priority is used to play more important sounds over others
|-
| 0x5
| 1
| '''Max number of voices'''
|-
| 0x6
| 1
| '''Definite Velocity'''; volume (usually 7F)
|-
| 0x7
| 1
| '''Panning'''
|-
| 0x8
| 2
| '''Definite Key'''; The default pitch (usually 0x3C00... the second byte may possibly be the MIDI channel)
|}

==== MIDI Setup Entry ====

Table of fixed-length tables to map all 16 MIDI channels to program numbers
(in-turn resolving to sound entities via the page table).

Multiple MIDI Setups may be created to support Song data requiring totally different
banks of instruments.

Each MIDI Setup starts with a u16 '''MIDI-Setup-ID''', then 16-bits padding, then 16 entries of the following structure (one for each channel):

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 1
| '''Program Number'''
|-
| 0x1
| 1
| '''Volume'''
|-
| 0x2
| 1
| '''Panning'''
|-
| 0x3
| 1
| '''Reverb'''
|-
| 0x4
| 1
| '''Chorus'''
|}

MIDI setups continue until the ''group end offset'' is reached.

=== Sample ===

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a [[DSP (File Format)|DSP]] file. Each sound's size is padded to 32 bytes before the next sound's data begins.

=== Sample Directory ===

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

==== Table A ====

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| '''Sound ID'''
|-
| 0x2
| 2
| '''Padding'''; always 0
|-
| 0x4
| 4
| '''Sound start offset''', relative to the start of the ADPCM chunk
|-
| 0x8
| 4
| {{unknown|'''Unknown'''}}
|-
| 0xC
| 1
| '''Base Note'''; Corresponds to the MIDI note played in the sample, at the native sample-rate (which MusyX obtains from the INST chunk of .aiff files or SMPL chunk of .wav files, along with looping info). To play at a specified pitch in [[wikipedia:Cent (music)|cents]], set the playback sample rate using this formula: <code>sampleRate * 2((pitch - baseNote * 100) / 1200.0)</code>
|-
| 0xD
| 1
| '''Padding'''; always 0
|-
| 0xE
| 2
| '''Sample rate'''
|-
| 0x10
| 1
| '''Audio format''' <ol start="0"><li>DSP-ADPCM</li><li>DSP-ADPCM (Drum Sample)</li><li>PCM</li><li>N64-VADPCM (Legacy Format)</li></ol>
|-
| 0x11
| 3
| '''Number of samples'''
|-
| 0x14
| 4
| '''Loop start sample'''
|-
| 0x18
| 4
| '''Loop length''', in samples. To get the loop end sample, add this to the start sample and subtract 1.
|-
| 0x1C
| 4
| '''Table B entry offset''', relative to the start of the sound metadata chunk
|-
| 0x20
| colspan=2 {{unknown|End of entry}}
|}

==== Table B ====

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

{|class="wikitable"
! Offset
! Size
! Description
|-
| 0x0
| 2
| {{unknown|'''Unknown'''; always 8}}
|-
| 0x2
| 1
| '''Initial predictor/scale''' (matches first frame header)
|-
| 0x3
| 1
| '''Loop predictor/scale''' (matches loop start frame header)
|-
| 0x4
| 2
| '''Loop context sample history 2'''
|-
| 0x6
| 2
| '''Loop context sample history 1'''
|-
| 0x8
| 2 × 16
| '''Decode coefficients'''
|-
| 0x28
| colspan=2 {{unknown|End of entry}}
|}

== Tools ==

* [https://drive.google.com/file/d/0B9MLV21H7SDvemgwN1daYnliSjA/view?usp=sharing Prime Audio Decoder] by Parax will dump all sound effects contained in a given AGSC file.

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