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

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.

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.