BYML is a simplified, binary form of YAML.
Only the version 2 and 3 formats are documented in this article.
The file is broken up into a node structure, with possible interlinking between the nodes. Each node has a one byte format identifier. The File begins with a header which points to three special nodes; the hash key table; the string table node and the root node.
|0x00||2||String “BY” (big endian) or “YB” (little endian) in ASCII (file identifier).|
|0x02||2||Version 0x0002 in Breath of the Wild. Values of 1 and 3 are accepted as well.|
|0x04||4||Offset to the hash key table, relative to start (usually 0x010). May be 0 if no hash nodes are used. Must be a string value node (0xc2).|
|0x08||4||Offset to the string table, relative to start. May be 0 if no strings are used. Must be a string value node (0xc2).|
|0x0c||4||Offset to the root node, relative to start. May be 0 if the document is totally empty. Must be either an array node (0xc0) or a hash node (0xc1).|
Every node format has a unique one byte identifier as follows. Some nodes are considered value nodes as indicated below. The container nodes have a longer encoding in the file, which must be four byte aligned. The order of encoding full nodes within the file does not seem to matter.
|0xA0||Value (Index)||String. Value is an index into the string table.|
|0xC0||Container||Array. Node is an array of nodes, typically, though not necessarily, all of the same format.|
|0xC1||Container||Hash. Node is a mapping from strings in the hash key table to other nodes.|
|0xC2||Container (Special)||String table. Special purpose node type only seen in the hash key table and the string table.|
|0xD0||Value||Bool. Node is 1 or 0 representing true or false respectively.|
|0xD1||Value||Int. Node is a signed 32 bit integer value.|
|0xD2||Value||Float. Node is a binary32 floating-point number.|
|0xD3||Value||UInt. Node is an unsigned 32 bit integer value. The game uses this for some CRC32 hashes and for masks.|
|0xD4||Value (Special)||Int64. Node is a 64 bit integer value. Not seen in Breath of the Wild.|
|0xD5||Value (Special)||UInt64. Node is an unsigned 64 bit integer value. Not seen in Breath of the Wild.|
|0xD6||Value (Special)||Double. Node is a binary64 floating-point number. Not seen in Breath of the Wild.|
|0xFF||Value||Null. Value is always 0. Not seen in Breath of the Wild.|
Value nodes can only be encoded as children of container nodes. Each value node has a direct four byte encoding.
For string nodes, this encoding is simply a four byte index into the string table respectively.
For special value nodes, the value is an offset to a 64 bit integer / floating-point number relative to the start of the file.
0xC0 - Array Node
|0x00||1||0xC0 node type.|
|0x01||3||Number of entries in array.|
|0x04||N||Array of N node types; the type of each element in the array.|
|0x04 + N’||4*N||Array of N node values. For regular value nodes, this is a 4 byte node value. For other nodes, this is a 4 byte offset to the node relative to the start of the file.|
N’ is N rounded up to the nearest multiple of 4.
0xC1 - Hash Node
Hash / dictionary nodes are used to encode name value collections. Entries must be lexicographically sorted.
|0x00||1||0xC1 node type.|
|0x01||3||Number of entries in dictionary.|
What then follows is a variable length array of dictionary entries. Each entry has the following structure.
|0x00||3||Name. Value is an index in the hash key table.|
|0x03||1||The node type.|
|0x04||4||Value. For regular value nodes, this is the 4 byte node value. For other nodes, this is a 4 byte offset to the node relative to the start of the file.|
0xC2 - String Table Node
|0x00||1||0xC2 node type.|
|0x01||3||Number of entries in the string table.|
|0x04||Y=4*(N+1)||Array of N+1 offsets to each string relative to the start of the node. The last entry is an offset to the end of the last string.|
|0x04+Y’||variable||Array of N null-terminated strings stored in alphabetical order.|
Y’ is Y rounded up to the nearest multiple of 4.
Usage in Nintendo games
|Breath of the Wild (Wii U)||Big endian||2||Uses SMO's library (in al::)|
|Breath of the Wild (Switch)||Little endian||2||Uses SMO's library (in al::), but with unused code and support for big endian eliminated|
|Super Mario Odyssey (Switch)||Little endian (supports big endian as well)||2 or 3|
|Splatoon 2 (Switch)||Little endian (supports big endian as well)||2 or 3||Uses SMO's library, but in the Lp::Utl:: namespace|
The v3 format seems to be identical to v2 but with the 64-bit node types added.
This article was adapted from documentation in the handsomematt/botw-modding repo.
- Nintendo's BYML library performs a binary search when looking up items by key in a hash node.