AINB
AINB (AI Node Binary) is a file format used for AI and logic on Tears of the Kingdom as well as other recent Nintendo EPD games. This article is primarily aimed at the version that appears in Tears of the Kingdom and Super Mario Bros. Wonder (v0x0407). AINB files can be found in the AI, Logic, and Sequence folders of the romfs as well as within various packs.
File Structure
AINB is a little endian format similar to most Switch file formats. An AINB file consists of a set of interconnected nodes which act like a syntax tree and control the behavior of actors. These nodes can also be calls to external AINB files, allowing AINB files to form entire trees of files. The root file of the tree will have .root.ainb as their extension while each module in the tree will have the extension .module.ainb. There are three primary categories of AINB files in TotK: AI, Logic, and Sequence. For AI and Sequence files, the file's entry point is one or more commands which is linked to one or two child nodes. All nodes are accessed by their index (references to precondition nodes will use their precondition node index which is local to the amount of precondition nodes in the file).
All string offsets in the file are relative to the beginning of the string pool and name hashes are 32-bit murmur3 hashes. There are six possible types for AINB parameters: int (signed 32-bit integer), bool, float (32-bit), vector3f, and pointer. Pointer parameters are pointers to objects.
Section Order
- 0x74-Byte File Header
- Commands
- Nodes
- Local Blackboard Parameters
- Node Bodies
- Attachment Parameters
- Immediate Parameters
- Input/Output Parameters
- Multi-Parameters
- Resident Update Array
- 0x50 Section (Unused in TotK)
- Precondition Nodes
- Expression Binary
- Embedded AINB Files
- Entry Strings
- File Hashes
- Child Replacement Table
- 0x6C Section
- Enum Resolve Array
- String Pool
File Header
AINB files begin with a 0x74 byte header. If the offset for a given section is empty, that section is not present in the file.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | char[4] | Magic - “AIB “ |
| 0x04 | 0x04 | u32 | Version (0x0407 in TotK, 0x0404 in S3 and NSS) |
| 0x08 | 0x04 | u32 | Filename Offset |
| 0x0C | 0x04 | u32 | Command Count |
| 0x10 | 0x04 | u32 | Node Count |
| 0x14 | 0x04 | u32 | Precondition Node Count |
| 0x18 | 0x04 | u32 | Attachment Parameter Count |
| 0x1C | 0x04 | u32 | Output Node Count |
| 0x20 | 0x04 | u32 | Local Blackboard Parameters Offset |
| 0x24 | 0x04 | u32 | String Pool Offset |
| 0x28 | 0x04 | u32 | Enum Resolve Array Offset |
| 0x2C | 0x04 | u32 | Immediate Parameters Offset |
| 0x30 | 0x04 | u32 | Resident Update Array Offset |
| 0x34 | 0x04 | u32 | Input/Output Parameters Offset |
| 0x38 | 0x04 | u32 | Multi-Parameters Array Offset |
| 0x3C | 0x04 | u32 | Attachment Parameters Offset |
| 0x40 | 0x04 | u32 | Attachment Parameters Index Array Offset |
| 0x44 | 0x04 | u32 | Expression Binary Section Offset |
| 0x48 | 0x04 | u32 | Child Replacement Table Offset |
| 0x4C | 0x04 | u32 | Precondition Node Array Offset |
| 0x50 | 0x04 | u32 | Unknown (unused in TotK, always the same as the Resident Update Array Offset) |
| 0x54 | 0x04 | u32 | Unknown (always 0) |
| 0x58 | 0x04 | u32 | Unknown (always 0, used in Splatoon 3/Nintendo Switch Sports) |
| 0x5C | 0x04 | u32 | Embedded AINB Files Offset |
| 0x60 | 0x04 | u32 | File Category Name Offset |
| 0x64 | 0x04 | u32 | File Category (0 = AI, 1 = Logic, 2 = Sequence) - only TotK |
| 0x68 | 0x04 | u32 | Entry Strings Offset (purpose unknown) |
| 0x6C | 0x04 | u32 | Unknown (Unused in TotK) |
| 0x70 | 0x04 | u32 | File Identification Hashes Offset (Purpose Unknown) |
Command Array
The command array immediately follows the file header and is an array of all commands in the file.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | u32 | Command Name Offset |
| 0x04 | 0x10 | u32 | GUID |
| u16 | |||
| u16 | |||
| u16 | |||
| u8[6] | |||
| 0x14 | 0x02 | u16 | Left Node Index |
| 0x16 | 0x02 | u16 | Right Node Index (one greater than the corresponding node index) |
Command GUIDs are only used for debug messages. Right Node Index will be -1 if the command only has one child node.
Node Array
The node array immediately follows the command array and is an array of all nodes in the file.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x02 | u16 | Node Type Enum (see below) |
| 0x02 | 0x02 | u16 | Node Index |
| 0x04 | 0x02 | u16 | Attachment Parameters Count |
| 0x06 | 0x01 | bitfield | Node Flags |
| 0x07 | 0x01 | u8 | |
| 0x08 | 0x04 | u32 | Node Type Name Offset (for UserDefined nodes) |
| 0x0C | 0x04 | u32 | Name Hash (version 0x407 only) |
| 0x10 | 0x04 | u32 | |
| 0x14 | 0x04 | u32 | Node Body Offset (relative to the start of the file) |
| 0x18 | 0x02 | u16 | EXB Function Count |
| 0x1A | 0x02 | u16 | EXB Input/Output Field Size |
| 0x1C | 0x02 | u16 | Multi-Param Count |
| 0x1E | 0x02 | u16 | |
| 0x20 | 0x04 | u32 | Base Attachment Parameter Index |
| 0x24 | 0x02 | u16 | Base Precondition Node |
| 0x26 | 0x02 | u16 | Precondition Node Count |
| 0x28 | 0x02 | u16 | 0x58 Section Entry Offset (relative to the start of the file) |
| 0x2A | 0x02 | u16 | |
| 0x2C | 0x10 | u32 | GUID |
| u16 | |||
| u16 | |||
| u16 | |||
| u8[6] |
Just like with commands, node GUIDs are only used for debug messages. The 0x58 section entry offset will be empty if unused.
| Value (Hex) | Value (Dec) | Node Type |
|---|---|---|
| 0x00 | 0 | UserDefined |
| 0x01 | 1 | Element_S32Selector |
| 0x02 | 2 | Element_Sequential |
| 0x03 | 3 | Element_Simultaneous |
| 0x04 | 4 | Element_F32Selector |
| 0x05 | 5 | Element_StringSelector |
| 0x06 | 6 | Element_RandomSelector |
| 0x07 | 7 | Element_BoolSelector |
| 0x08 | 8 | Element_Fork |
| 0x09 | 9 | Element_Join |
| 0x0A | 10 | Element_Alert |
| 0x14 | 20 | Element_Expression |
| 0x64 | 100 | Element_ModuleIF_Input_S32 |
| 0x65 | 101 | Element_ModuleIF_Input_F32 |
| 0x66 | 102 | Element_ModuleIF_Input_Vec3f |
| 0x67 | 103 | Element_ModuleIF_Input_String |
| 0x68 | 104 | Element_ModuleIF_Input_Bool |
| 0x69 | 105 | Element_ModuleIF_Input_Ptr |
| 0xC8 | 200 | Element_ModuleIF_Output_S32 |
| 0xC9 | 201 | Element_ModuleIF_Output_F32 |
| 0xCA | 202 | Element_ModuleIF_Output_Vec3f |
| 0xCB | 203 | Element_ModuleIF_Output_String |
| 0xCC | 204 | Element_ModuleIF_Output_Bool |
| 0xCD | 205 | Element_ModuleIF_Output_Ptr |
| 0x012C | 300 | Element_ModuleIF_Child |
| 0x0190 | 400 | Element_StateEnd |
| 0x01F4 | 500 | Element_SplitTiming |
Node type names are official. For UserDefined nodes, node definitions can be found in a node definition files. This file is located at NodeDefinition/Node.Product.[ver].aidefn.byml.zs in the corresponding file category folder.
| Type | Description |
|---|---|
| UserDefined | Custom node type, definition in NodeDefinition |
| Element_S32Selector | Conditionally links to a node depending on the value of a signed int |
| Element_Sequential | Links to nodes sequentially in the order listed |
| Element_Simultaneous | Links simultaneously to multiple nodes |
| Element_F32Selector | Conditionally links to a node depending on the value of 32-bit float |
| Element_StringSelector | Conditionally links to a node depending on the value of a string |
| Element_RandomSelector | Links to a node randomly |
| Element_BoolSelector | Conditionally links to a node depending on the value of a bool |
| Element_Fork | See Resident Update Array |
| Element_Join | See Resident Update Array |
| Element_Alert | Displays a debug message |
| Element_Expression | Passes values to and from EXB commands |
| Element_ModuleIF_Input_S32 | Passes a signed int as output to another node as input |
| Element_ModuleIF_Input_F32 | Passes a 32-bit float as output to another node as input |
| Element_ModuleIF_Input_Vec3f | Passes a vector3f as output to another node as input |
| Element_ModuleIF_Input_String | Passes a string as output to another node as input |
| Element_ModuleIF_Input_Bool | Passes a boolean int as output to another node as input |
| Element_ModuleIF_Input_Ptr | Passes a pointer as output to another node as input |
| Element_ModuleIF_Output_S32 | Passes a signed int as output to another node as output |
| Element_ModuleIF_Output_F32 | Passes a 32-bit float as output to another node as output |
| Element_ModuleIF_Output_Vec3f | Passes a vector3f as output to another node as output |
| Element_ModuleIF_Output_String | Passes a string as output to another node as output |
| Element_ModuleIF_Output_Bool | Passes a boolean int as output to another node as output |
| Element_ModuleIF_Output_Ptr | Passes a pointer as output to another node as output |
| Element_ModuleIF_Child | Unsure, appears to just be a node connected to a ModuleIF node as a child node |
| Element_StateEnd | Termination node |
| Element_SplitTiming | Changes when child nodes are run (Enter - first time visiting a node, Update - every frame, Leave - ran upon leaving the node) |
| Bits | Description |
|---|---|
| 1 | Is Precondition Node |
| 1 | Is External AINB File |
| 1 | Is Resident Node |
| 5 |
Local Blackboard Parameters
This section contains an array of the Blackboard parameters used by file. These parameters may be sourced from external Blackboards or parameter files. The section begins with a 0x30 byte section header followed by the array of parameters, an array of default values of said parameters, and an array of file references if applicable. The order of parameters is in the order of string, int, float, bool, vector3f, and pointer. The section header contains six entries, one for each type.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x02 | u16 | Number of Entries of the Corresponding Data Type |
| 0x02 | 0x02 | u16 | Parameter Index of the First Entry of the Corresponding Data Type |
| 0x04 | 0x02 | u16 | Relative Offset of the First Entry of the Corresponding Data Type |
| 0x06 | 0x02 | u16 |
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | bitfield | Name Offset and Flags |
| 0x04 | 0x04 | u32 | String Offset (Notes) |
| Bits | Description |
|---|---|
| 22 | Name Offset |
| 1 | |
| 1 | Does Not Have File Reference |
| 7 | File Reference Index |
| 1 | Is File Reference Valid |
The default value entries vary based on the parameter's data type. For int and float parameters, the entry is a four byte immediate value. String entries are a four byte string value offset. Bool entries are a single byte immediate value and vector3f entries are 12 bytes. Note that pointer parameters do not have default value entries and do not have default values.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | u32 | File Path Offset |
| 0x04 | 0x04 | u32 | File Path Hash |
| 0x08 | 0x04 | u32 | Unknown Hash |
| 0x0C | 0x04 | u32 | Unknown Hash |
Node Bodies
Each node body is composed of two parts: a 0x90 byte parameter section and a 0x14 child node section header followed by said section if applicable. The child node section contains information about the child node and specific connection types. The following parameter indices are indices into the parameter array for that specific type and data type.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | u32 | Int Immediate Parameter Base Index |
| 0x04 | 0x04 | u32 | Int Immediate Parameter Count |
| 0x08 | 0x04 | u32 | Bool Immediate Parameter Base Index |
| 0x0C | 0x04 | u32 | Bool Immediate Parameter Count |
| 0x10 | 0x04 | u32 | Float Immediate Parameter Base Index |
| 0x14 | 0x04 | u32 | Float Immediate Parameter Count |
| 0x18 | 0x04 | u32 | String Immediate Parameter Base Index |
| 0x1C | 0x04 | u32 | String Immediate Parameter Count |
| 0x20 | 0x04 | u32 | Vector3f Immediate Parameter Base Index |
| 0x24 | 0x04 | u32 | Vector3f Immediate Parameter Count |
| 0x28 | 0x04 | u32 | Pointer Immediate Parameter Base Index |
| 0x2C | 0x04 | u32 | Pointer Immediate Parameter Count |
| 0x30 | 0x04 | u32 | Int Input Parameter Base Index |
| 0x34 | 0x04 | u32 | Int Input Parameter Count |
| 0x38 | 0x04 | u32 | Int Output Parameter Base Index |
| 0x3C | 0x04 | u32 | Int Output Parameter Count |
| 0x40 | 0x04 | u32 | Bool Input Parameter Base Index |
| 0x44 | 0x04 | u32 | Bool Input Parameter Count |
| 0x48 | 0x04 | u32 | Bool Output Parameter Base Index |
| 0x4C | 0x04 | u32 | Bool Output Parameter Count |
| 0x50 | 0x04 | u32 | Float Input Parameter Base Index |
| 0x54 | 0x04 | u32 | Float Input Parameter Count |
| 0x58 | 0x04 | u32 | Float Output Parameter Base Index |
| 0x5C | 0x04 | u32 | Float Output Parameter Count |
| 0x60 | 0x04 | u32 | String Input Parameter Base Index |
| 0x64 | 0x04 | u32 | String Input Parameter Count |
| 0x68 | 0x04 | u32 | String Output Parameter Base Index |
| 0x6C | 0x04 | u32 | String Output Parameter Count |
| 0x70 | 0x04 | u32 | Vector3f Input Parameter Base Index |
| 0x74 | 0x04 | u32 | Vector3f Input Parameter Count |
| 0x78 | 0x04 | u32 | Vector3f Output Parameter Base Index |
| 0x7C | 0x04 | u32 | Vector3f Output Parameter Count |
| 0x80 | 0x04 | u32 | Pointer Input Parameter Base Index |
| 0x84 | 0x04 | u32 | Pointer Input Parameter Count |
| 0x88 | 0x04 | u32 | Pointer Output Parameter Base Index |
| 0x8C | 0x04 | u32 | Pointer Output Parameter Count |
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x01 | u8 | Bool/float Input Source Node/Output Source Node Count |
| 0x01 | 0x01 | u8 | Bool/float Input Source Node/Output Source Node Base Index |
| 0x02 | 0x01 | u8 | Unknown Connection Type Count (Unused in TotK) |
| 0x03 | 0x01 | u8 | Unknown Connection Type Base Index (Unused TotK) |
| 0x04 | 0x01 | u8 | Standard Child Node Count |
| 0x05 | 0x01 | u8 | Standard Child Node Base Index |
| 0x06 | 0x01 | u8 | Resident Update Node Count |
| 0x07 | 0x01 | u8 | Resident Update Base Index |
| 0x08 | 0x01 | u8 | String Input Source Node Count |
| 0x09 | 0x01 | u8 | String Input Source Node Base Index |
| 0x0A | 0x01 | u8 | Int Input Source Node Count |
| 0x0B | 0x01 | u8 | Int Input Source Node Base Index |
| 0x0C | 0x01 | u8 | Unknown Connection Type Count (Unused in TotK) |
| 0x0D | 0x01 | u8 | Unknown Connection Type Base Index (Unused TotK) |
| 0x0E | 0x01 | u8 | Unknown Connection Type Count (Unused in TotK) |
| 0x0F | 0x01 | u8 | Unknown Connection Type Base Index (Unused TotK) |
| 0x10 | 0x01 | u8 | Unknown Connection Type Count (Unused in TotK) |
| 0x11 | 0x01 | u8 | Unknown Connection Type Base Index (Unused TotK) |
| 0x12 | 0x01 | u8 | Unknown Connection Type Count (Unused in TotK) |
| 0x13 | 0x01 | u8 | Unknown Connection Type Base Index (Unused TotK) |
If the node has any child nodes, the section header is followed by an array of u32 offsets to each of the child node entries. For most nodes, each entry is eight bytes.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | u32 | Child Node Index |
| 0x04 | 0x04 | u32 | Value |
The interpretation of the value depends on the connection type. For input or output connections, the value is a string offset to the parameter name. For standard connections, the value is a string offset to the connection name. For resident update connections, the value is an index into the resident update array. Certain node/connection types will also extend the entry length. Selector-type nodes excluding Element_BoolSelector and Element_F32Selector will have an extra four bytes which stores the condition for to link to the child node. For Element_S32Selector, this is an immediate value. For Element_RandomSelector, this is a weight and for Element_StringSelector it is a u32 string offset. The condition for Element_BoolSelector is the entry's value string. Element_F32Selector adds 24 bytes to each entry, consisting of four eight-byte sub-entries.
| Offset | Size | Type | Description |
|---|---|---|---|
| 0x00 | 0x04 | u32 | Local Blackboard Parameter Index and Flags |
| 0x04 | 0x04 | float | Condition Value |
The first two bytes of the four bytes at offset 0x00 are the local blackboard parameter index while the last bit is whether or not the index is used or not. The first entry for Element_F32Selector is the minimum value condition while the second entry is the maximum value condition. The last two entries appear to be unused. The last child node entry for Selector-type nodes is the default case. The condition for this case is either a string offset to the string その他 ("Other") or 0 (in the case of Element_S32Selector). Input nodes that are Selector-type nodes also appear to have an additional eight bytes (purpose unknown). Element_Expression have an additional eight bytes per input node (16 bytes in the case of vector3f entries). The purpose of these bytes is unknown.
Attachment Parameters
Immediate Parameters
Input/Output Parameters
Multi-Parameters
Resident Update Array
0x50 Section
Precondition Nodes Array
Expression Binary Section
The EXB (Expression Binary) section is a completely self-contained section that stores custom instructions for a simple command processor. These instructions are grouped into functions that can be called by nodes to perform calculations.
Embedded AINB Files
Entry Strings
Child Replacement Table
0x6C Section
Enum Resolve Array
String Pool
The string pool is an array of null-terminated strings encoded with UTF-8. All string offsets in the file are relative to the first byte of this section.