AINB

From EPD Wiki
Revision as of 02:53, 1 December 2023 by Dt12345 (talk | contribs) (added child node info)
Jump to navigation Jump to search

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

  1. 0x74-Byte File Header
  2. Commands
  3. Nodes
  4. Local Blackboard Parameters
  5. Node Bodies
  6. Attachment Parameters
  7. Immediate Parameters
  8. Input/Output Parameters
  9. Multi-Parameters
  10. Resident Update Array
  11. 0x50 Section (Unused in TotK)
  12. Precondition Nodes
  13. Expression Binary
  14. Embedded AINB Files
  15. Entry Strings
  16. File Hashes
  17. Child Replacement Table
  18. 0x6C Section
  19. Enum Resolve Array
  20. 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.

File Header
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.

Command Entry
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.

Node Entry
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.

Node Types
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.

Node Type Descriptions
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)
Node Flags
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.

Section Header Entry
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
Local Blackboard Parameter Entry
Offset Size Type Description
0x00 0x04 bitfield Name Offset and Flags
0x04 0x04 u32 String Offset (Notes)
Name Offset Flags
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.

File Reference Entry
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
Child Node Section Header
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.

Child Node Entry
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.

Element_F32Selector Condition Entry
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.