AAMP: Difference between revisions

From ZeldaMods (Breath of the Wild)
Jump to navigation Jump to search
VisualWikitext
imported>BravelyPeculiar
(Created page with "'''AAMP''' files are parameter files that are used in many recent Nintendo games such as ''Breath of the Wild''. == Structure == The basic structure of AAMP files is document...")
 
(→‎Structure: fix struct definitions (offsets and counts are packed as a single u32; they are not separate fields))
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''AAMP''' files are parameter files that are used in many recent Nintendo games such as ''Breath of the Wild''.
<onlyinclude>
'''AAMP'''s are parameter files (officially: binary resource parameter archives).
</onlyinclude>
Only version 2 is documented in this article since this is what ''Breath of the Wild'' and recent Nintendo games use.


== Structure ==
== Structure ==
The basic structure of AAMP files is documented on the [[mk8:AAMP (File Format)|MK8 wiki]].
AAMP is a (typically) little endian format.
 
Unlike some other file formats, AAMP files in ''Breath of the Wild'' have the exact same structure and endianness on Wii U and Switch, so these files are interchangeable between the consoles.
 
=== Introduction ===
* Parameters are a key-value pair. In the binary form, the key is a CRC32 hash.
* Parameter Objects are dicts that contain Parameters.
* Parameter Lists are structures that contain Parameter Objects and Parameter Lists.
* The root parameter list is called the Parameter IO. It is associated with a version and type string in the header which is checked by the AAMP library.
 
=== Section order ===
* Header
* Parameter lists
* Parameter objects
* Parameters
* Data section (to store parameter data)
* String section (to store strings)
* Unknown uint32 section (unused?)
 
For more information on the ordering, refer to the [https://github.com/zeldamods/oead/blob/v0.9.0-2/src/aamp.cpp#L262 oead source code].
 
=== Header ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x0 || char[4] || Magic ("AAMP")
|-
| 0x4 || u32 || Version (2)
|-
| 0x8 || u32 || Flags (LittleEndian: 1 << 0, UTF8: 1 << 1)
|-
| 0xc || u32 || File size
|-
| 0x10 || u32 || Parameter IO version
|-
| 0x14 || u32 || Offset to parameter IO relative to 0x30
|-
| 0x18 || u32 || Number of lists (including parameter IO)
|-
| 0x1c || u32 || Number of objects
|-
| 0x20 || u32 || Number of parameters
|-
| 0x24 || u32 || Data section size
|-
| 0x28 || u32 || String section size
|-
| 0x2c || u32 || Unknown: number of uint32s after the string section
|-
| 0x30 || char[] || Parameter IO type (typically <code>xml</code>)
|}
 
=== Parameter list ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x0 || u32 || Name CRC32
|-
| 0x4 || u32 ||
* Bits 0-15: Offset to child lists, divided by 4 and relative to parameter list start
* Bits 16-31: Number of child lists
|-
| 0x8 || u32 ||
* Bits 0-15: Offset to child objects, divided by 4 and relative to parameter list start
* Bits 16-31: Number of child objects
|}
 
=== Parameter object ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x0 || u32 || Name CRC32
|-
| 0x4 || u32 ||
* Bits 0-15: Offset to child parameters, divided by 4 and relative to parameter object start
* Bits 16-31: Number of child parameters
|}
 
=== Parameter ===
{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x0 || u32 || Name CRC32
|-
| 0x4 || u32 ||
* Bits 0-23: Offset to data, divided by 4 and relative to parameter start.<br>For strings, this points to a string in the string section. For other parameter types, this points to the data section.
* Bits 24-31: Parameter type
|}
 
=== ParameterType ===
The following parameter type and class names are ''official'' and come from Nintendo's AAMP library.
 
{| class="wikitable"
! ID
! Type
! Parameter type
|-
| 0 
| bool
| <code>agl::utl::Parameter<bool></code>
|-
| 1 
| f32 
| <code>agl::utl::Parameter<float></code>
|-
| 2 
| int 
| <code>agl::utl::Parameter<int></code>
|-
| 3 
| vec2
| <code>agl::utl::Parameter<sead::Vector2<float>></code>
|-
| 4 
| vec3
| <code>agl::utl::Parameter<sead::Vector3<float>></code>
|-
| 5 
| vec4
| <code>agl::utl::Parameter<sead::Vector4<float>></code>
|-
| 6 
| color
| <code>agl::utl::Parameter<sead::Color4f></code>
|-
| 7 
| string32
| <code>agl::utl::Parameter<sead::FixedSafeString<32>></code>
|-
| 8 
| string64
| <code>agl::utl::Parameter<sead::FixedSafeString<64>></code>
|-
| 9 
| curve1
| <code>agl::utl::ParameterCurve<1u></code>
|-
| 10
| curve2
| <code>agl::utl::ParameterCurve<2u></code>
|-
| 11
| curve3
| <code>agl::utl::ParameterCurve<3u></code> (unused in BotW?)
|-
| 12
| curve4
| <code>agl::utl::ParameterCurve<4u></code>
|-
| 13
| buffer_int
| <code>agl::utl::ParameterBuffer<int></code>
|-
| 14
| buffer_f32
| <code>agl::utl::ParameterBuffer<float></code>
|-
| 15
| string256
| <code>agl::utl::Parameter<sead::FixedSafeString<256>></code>
|-
| 16
| quat
| <code>agl::utl::Parameter<sead::Quat<float>></code>
|-
| 17
| u32
| <code>agl::utl::Parameter<uint></code>
|-
| 18
| buffer_u32
| <code>agl::utl::ParameterBuffer<unsigned int></code>
|-
| 19
| buffer_binary
| <code>agl::utl::ParameterBuffer<unsigned char></code>
|-
| 20
| stringRef
| <code>agl::utl::Parameter<sead::SafeStringBase<char>></code>
|-
| 21
| (none, special)
| <code>agl::utl::Parameter<int *></code>, <code>agl::utl::Parameter<float *></code>, <code>agl::utl::Parameter<unsigned int *></code>, <code>agl::utl::Parameter<unsigned char *></code>
|}


== Usage in ''Breath of the Wild'' ==
== Usage in ''Breath of the Wild'' ==
AAMP files are used in ''Breath of the Wild'' to store parameters that define the game's behaviour. They are very frequently used inside .sbactorpack archives, where they define most of an Actor's characteristics.
AAMP files are used in ''Breath of the Wild'' to store parameters that define the game's behaviour. They are very frequently used inside [[actor pack]] archives, where they define most of an Actor's characteristics.
 
=== Naming conventions for arrays ===
Nintendo works around the lack of lists/arrays in the AAMP format by using parameter lists/objects and numbered names for children.
 
By convention, if the parent name is <code>{parent name}</code>, children will typically have one of the following names:
* <code>{singular parent name}_%d</code>
* <code>{singular parent name}_%02d</code>
* <code>{singular parent name}_%03d</code>
* <code>{singular parent name}%d</code>
* <code>{singular parent name}%02d</code>
* <code>{singular parent name}%03d</code>
 
This is of course not the case for all documents and there are in fact many exceptions.


=== Extensions ===
=== Extensions ===
AAMP files have a wide range of extensions. The file format is the same regardless of the extension, but the parameters defines inside it differ depending on the extension.
AAMP files have a wide range of extensions. The file format is the same regardless of the extension, but the parameters defines inside it differ depending on the extension.


The following extensions are used in the game:
{{#dpl:
* [[.bxml]]
|category = File extensions (AAMP)
* [[.baiprog]]
|columns=5
* UNFINISHED
|rowcolformat=width=100%
}}
 
=== Internal usage ===
Parameter classes (e.g. Bdmgparam) inherit from agl::utl::IParameterIO -> agl::utl::IParameterList.
 
In their constructors or in an init function, agl::utl::Parameter objects are created and initialised by passing the key name, the description and help strings (see <code>agl::utl::ParameterBase::initializeListNode</code>). The CRC32 for the keys are stored and then the Parameter object is added to a agl::utl::IParameterObj list.
 
Finally, to actually load the AAMP binary data into all the parameter objects, the game constructs a agl::utl::ResParameterArchive::ResParameterArchive and then passes it to <code>applyResParameterArchive()</code>.
 
==== Structures ====
agl::utl::ResParameterArchive holds a pointer to agl::utl::ResParameterArchiveData (which is the AAMP header structure).
 
Elements like param_root are parameter lists (agl::utl::IParameterList, tag: <code>param_list</code>). The binary structure for lists is agl::utl::ResParameterList.
 
A param list holds parameter objects (agl::utl::IParameterObj, tag: <code>param_array</code>) or other parameter lists. The binary structure for objects is agl::utl::ResParameterObj.
 
Param objects store parameters (agl::utl::ParameterBase, tag: <code>param</code>). The binary structure for parameters is agl::utl::ResParameter.
 
=== Parameter list name ===
agl::utl::IParameterIO (in Nintendo's AAMP library) automatically sets the 'parameter list name' / tag name to <code>param_root</code>.
 
== al::Parameter ==
''Super Mario Odyssey'''s al::Parameter classes are extremely similar to the agl::utl::Parameter utils and appear to be an improved version. They share most of the public interface, presumably because Nintendo wanted to make switching to al:: easier.
 
The human readable format is YAML instead of XML and the binary format uses BYML. Key names are stored in plain text unlike agl::utl::Parameter which stores only the hashes of the key strings.
 
* Parameters have the same purpose as in the agl:: implementation.
* ParameterLists are dicts (key-value mapping, with keys being strings) that contain Parameters, ParameterObjects, ParameterArrays and ParameterLists.
* ParameterObjects are dicts that contain Parameters and ParameterArrays.
* ParameterArrays are arrays of ParameterObjects. This is a new structure. 
 
== Tools ==
The following tools can be used to convert AAMP files to an editable format, and back again:
{{Tool table|category=Tools (AAMP)}}
[[Category:File formats]]

Latest revision as of 21:34, 1 September 2020

AAMPs are parameter files (officially: binary resource parameter archives).

Only version 2 is documented in this article since this is what Breath of the Wild and recent Nintendo games use.

Structure

AAMP is a (typically) little endian format.

Unlike some other file formats, AAMP files in Breath of the Wild have the exact same structure and endianness on Wii U and Switch, so these files are interchangeable between the consoles.

Introduction

  • Parameters are a key-value pair. In the binary form, the key is a CRC32 hash.
  • Parameter Objects are dicts that contain Parameters.
  • Parameter Lists are structures that contain Parameter Objects and Parameter Lists.
  • The root parameter list is called the Parameter IO. It is associated with a version and type string in the header which is checked by the AAMP library.

Section order

  • Header
  • Parameter lists
  • Parameter objects
  • Parameters
  • Data section (to store parameter data)
  • String section (to store strings)
  • Unknown uint32 section (unused?)

For more information on the ordering, refer to the oead source code.

Header

Offset Type Description
0x0 char[4] Magic ("AAMP")
0x4 u32 Version (2)
0x8 u32 Flags (LittleEndian: 1 << 0, UTF8: 1 << 1)
0xc u32 File size
0x10 u32 Parameter IO version
0x14 u32 Offset to parameter IO relative to 0x30
0x18 u32 Number of lists (including parameter IO)
0x1c u32 Number of objects
0x20 u32 Number of parameters
0x24 u32 Data section size
0x28 u32 String section size
0x2c u32 Unknown: number of uint32s after the string section
0x30 char[] Parameter IO type (typically xml)

Parameter list

Offset Type Description
0x0 u32 Name CRC32
0x4 u32
  • Bits 0-15: Offset to child lists, divided by 4 and relative to parameter list start
  • Bits 16-31: Number of child lists
0x8 u32
  • Bits 0-15: Offset to child objects, divided by 4 and relative to parameter list start
  • Bits 16-31: Number of child objects

Parameter object

Offset Type Description
0x0 u32 Name CRC32
0x4 u32
  • Bits 0-15: Offset to child parameters, divided by 4 and relative to parameter object start
  • Bits 16-31: Number of child parameters

Parameter

Offset Type Description
0x0 u32 Name CRC32
0x4 u32
  • Bits 0-23: Offset to data, divided by 4 and relative to parameter start.
    For strings, this points to a string in the string section. For other parameter types, this points to the data section.
  • Bits 24-31: Parameter type

ParameterType

The following parameter type and class names are official and come from Nintendo's AAMP library.

ID Type Parameter type
0 bool agl::utl::Parameter<bool>
1 f32 agl::utl::Parameter<float>
2 int agl::utl::Parameter<int>
3 vec2 agl::utl::Parameter<sead::Vector2<float>>
4 vec3 agl::utl::Parameter<sead::Vector3<float>>
5 vec4 agl::utl::Parameter<sead::Vector4<float>>
6 color agl::utl::Parameter<sead::Color4f>
7 string32 agl::utl::Parameter<sead::FixedSafeString<32>>
8 string64 agl::utl::Parameter<sead::FixedSafeString<64>>
9 curve1 agl::utl::ParameterCurve<1u>
10 curve2 agl::utl::ParameterCurve<2u>
11 curve3 agl::utl::ParameterCurve<3u> (unused in BotW?)
12 curve4 agl::utl::ParameterCurve<4u>
13 buffer_int agl::utl::ParameterBuffer<int>
14 buffer_f32 agl::utl::ParameterBuffer<float>
15 string256 agl::utl::Parameter<sead::FixedSafeString<256>>
16 quat agl::utl::Parameter<sead::Quat<float>>
17 u32 agl::utl::Parameter<uint>
18 buffer_u32 agl::utl::ParameterBuffer<unsigned int>
19 buffer_binary agl::utl::ParameterBuffer<unsigned char>
20 stringRef agl::utl::Parameter<sead::SafeStringBase<char>>
21 (none, special) agl::utl::Parameter<int *>, agl::utl::Parameter<float *>, agl::utl::Parameter<unsigned int *>, agl::utl::Parameter<unsigned char *>

Usage in Breath of the Wild

AAMP files are used in Breath of the Wild to store parameters that define the game's behaviour. They are very frequently used inside actor pack archives, where they define most of an Actor's characteristics.

Naming conventions for arrays

Nintendo works around the lack of lists/arrays in the AAMP format by using parameter lists/objects and numbered names for children.

By convention, if the parent name is {parent name}, children will typically have one of the following names:

  • {singular parent name}_%d
  • {singular parent name}_%02d
  • {singular parent name}_%03d
  • {singular parent name}%d
  • {singular parent name}%02d
  • {singular parent name}%03d

This is of course not the case for all documents and there are in fact many exceptions.

Extensions

AAMP files have a wide range of extensions. The file format is the same regardless of the extension, but the parameters defines inside it differ depending on the extension.

Internal usage

Parameter classes (e.g. Bdmgparam) inherit from agl::utl::IParameterIO -> agl::utl::IParameterList.

In their constructors or in an init function, agl::utl::Parameter objects are created and initialised by passing the key name, the description and help strings (see agl::utl::ParameterBase::initializeListNode). The CRC32 for the keys are stored and then the Parameter object is added to a agl::utl::IParameterObj list.

Finally, to actually load the AAMP binary data into all the parameter objects, the game constructs a agl::utl::ResParameterArchive::ResParameterArchive and then passes it to applyResParameterArchive().

Structures

agl::utl::ResParameterArchive holds a pointer to agl::utl::ResParameterArchiveData (which is the AAMP header structure).

Elements like param_root are parameter lists (agl::utl::IParameterList, tag: param_list). The binary structure for lists is agl::utl::ResParameterList.

A param list holds parameter objects (agl::utl::IParameterObj, tag: param_array) or other parameter lists. The binary structure for objects is agl::utl::ResParameterObj.

Param objects store parameters (agl::utl::ParameterBase, tag: param). The binary structure for parameters is agl::utl::ResParameter.

Parameter list name

agl::utl::IParameterIO (in Nintendo's AAMP library) automatically sets the 'parameter list name' / tag name to param_root.

al::Parameter

Super Mario Odyssey's al::Parameter classes are extremely similar to the agl::utl::Parameter utils and appear to be an improved version. They share most of the public interface, presumably because Nintendo wanted to make switching to al:: easier.

The human readable format is YAML instead of XML and the binary format uses BYML. Key names are stored in plain text unlike agl::utl::Parameter which stores only the hashes of the key strings.

  • Parameters have the same purpose as in the agl:: implementation.
  • ParameterLists are dicts (key-value mapping, with keys being strings) that contain Parameters, ParameterObjects, ParameterArrays and ParameterLists.
  • ParameterObjects are dicts that contain Parameters and ParameterArrays.
  • ParameterArrays are arrays of ParameterObjects. This is a new structure. 

Tools

The following tools can be used to convert AAMP files to an editable format, and back again:

Tool Cross-platform Setup Known issues
aamptool Yes

Download the tool from GitHub (note: builds are only provided for Windows).

  • Non-root parameter lists: Parameter lists are not handled correctly at this moment, which causes files (baiprogs for instance) that rely on nested lists to have a strange structure in their XML representation.
  • Parameter names with leading numbers: Nintendo sometimes starts parameter structure names with numbers. aamptool converts structures into XML tags; however leading numbers in tag names are explicitly disallowed by the XML specification. As a result files with such nodes cannot be converted back from XML into AAMP correctly. aamptool will either crash or fail to convert the affected parameter nodes.
  • Incomplete parameter type support: Esoteric parameter types such as curves and buffers are not supported. This is problematic because a conversion into XML will only keep one byte of the original data, leading to data loss when converting back to AAMP.
aamp Yes

Install the aamp package. [CLI help]

  • Incomplete parameter type support: Esoteric parameter types (buffers) are not fully supported: currently the tool can display files that use buffers correctly but cannot convert them back to AAMP.
Wild Bits Yes
  1. Ensure you have a 64 bit version of Python 3.7+ before continuing. Windows users must also install the latest x64 Visual C++ redistributable. You will not be able to install or launch Wild Bits otherwise. See Help:Setting_up_tools.
  2. (Optional) For best results on Windows, install cefpython3. [CLI help]
  3. Install the wildbits package. [CLI help]

On some system configurations, launching with wildbits doesn't work and you must use python -m wildbits instead.

Switch Toolbox No
  • Simply download the latest compiled release from GitHub, unzip, and launch the exe. Note that the latest release has an old date, but it is current, as it automatically rebuilds with each commit.
Retrieved from "https://zeldamods.org/w_botw/index.php?title=AAMP&oldid=10879"