BYAML (File Format)

From MK8
Jump to: navigation, search

The BYAML file format is a generic data container format used in Mario Kart 8. It is similar in some ways to XML, but it is a binary data format. Like XML files, BYAML files are somewhat self describing making it easier to understand and edit them than unformated binary data. In Mario Kart 8 they're used to describe course control information such as layout and checkpointing, as well as describing game-wide settings such as objects and AIs.

Format

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 up to four special nodes: the node name table node; the string value table node; the path value node and finally the root node.

Header

The BYAML file format starts with a 0x14 byte header structure.

Offset Size Description
0x00 2 String "BY" in ASCII (file identifier).
0x02 2 Version 0x0001 in Mario Kart 8.
0x04 4 Node name table node Offset to the node name table node, relative to start (usually 0x014). Unknown if this can ever be 0. Must be a string value node (0xc2).
0x08 4 String value table node Offset to the string value table node, relative to start. May be 0 if string values unused. Must be a string value node (0xc2).
0x0c 4 Path value table node Offset to the path value table node, relative to start. May be 0 if path values unused. Must be a path value node (0xc3).
0x10 4 Root node Offset to the root node, relative to start. Must be either an array node (0xc0) or a dictionary node (0xc1).
0x14 End of file header

Nodes

Every node format has a unique one byte identifier as follows. Some nodes are considered value nodes as indicated below. The full 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.

Identifier Type Description
0xa0 Value (Index) String. Value is an index into the string value table.
0xa1 Value (Index) Path. Value is an index into the path value table.
0xc0 Full Array. Node is an array of nodes, typically, though not necessarily, all of the same format.
0xc1 Full Dictionary. Node is a mapping from strings in the node name table to other nodes.
0xc2 Full (Special Purpose) String table. Special purpose node type only seen in the node name table and the string value table.
0xc3 Full (Special Purpose) Path table. Special purpose node type only seen in the path value table.
0xd0 Value Boolean. Node is 1 or 0 representing true or false respectively.
0xd1 Value Integer. Node is a signed integer value.
0xd2 Value Float. Node is a 32 bit floating point value.

Value Nodes

Value nodes can only be encoded as children of other nodes. Each value node has a direct four byte encoding. For string and path values, this encoding is simply a four byte index into the string or path tables respectively.

0xc0 - Array Node

An array node begins with the following header.

Offset Size Description
0x00 1 0xc0 node type.
0x01 3 N= Count number of entries in array.
0x04 N Variable length array of node types; the type of each element in the array.
0x04+N End of node header

There then follows padding bytes up to the nearest 4 bytes. After the padding is the variable length array of N node values. For value nodes this is the four byte node value. For full nodes this is an offset to the node relative to the start of the file.

0xc1 - Dictionary Node

Dictionary nodes are used to encode name value collections. The order of entries in the dictionary does not seem to matter. A dictionary node begins with the following header.

Offset Size Description
0x00 1 0xc1 node type.
0x01 3 N= Count number of entries in dictionary.
0x04 End of node header

What then follows is a variable length array of N dictionary entries. Each entry has the following structure.

Offset Size Description
0x00 3 Name. Index into the node name value table for the name of this entry.
0x03 1 Node type. One of the node type constants.
0x04 4 Value. For value nodes this is the four byte node value. For full nodes this is an offset to the node relative to the start of the file.
0x08 End of entry

0xc2 - String Table Node

A string table node begins with the following header.

Offset Size Description
0x00 1 0xc2 node type.
0x01 3 N= Count number of entries in string value table.
0x04 4*(N+1) Offsets. Variable length array of 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+4*(N+1) End of node header

Immediately following the node header are the string values at the positions indicated by the offsets. Despite the length being clear from the table, the string values are null terminated, perhaps for ease of decoding. They are always stored in alphabetical order.

0xc3 - Path Table Node

A path table node begins with the following header.

Offset Size Description
0x00 1 0xc3 node type.
0x01 3 N= Count number of entries in path value table.
0x04 4*(N+1) Offsets. Variable length array of offsets to each path relative to the start of the node. The last entry is an offset to the end of the last path.
0x04+4*(N+1) End of node header

Immediately following the header are the paths at the positions indicated by the offsets. The length of each path is implicit; subtract the offset to the next path from the offset to this path. Each path consists of multiple points. Each point is a structure as follows.

Offset Size Description
0x00 12 Posiition three floating point values, x, y and z.
0x0c 12 Normal three floating point values, x, y and z.
0x18 4 Unknown.
0x1c End of point

Uses

Since the BYAML format is a generic data container, this format specification cannot detail what structure a particular BYAML file ought to have. The following table links to articles on specific instances of BYAML files.

File(s) Description
/content/ai/AIRivalTable.byaml Sets up your rivals based on the character you choose at random, but your character is set to -1 so it's not loaded as an AI. Seems harcoded.
/content/race_common/ai/AIConfuseTable.byaml unknown
/content/race_common/ai/AICourseTable_GP.byaml Has floats for each course assigned to it, categorized through CC...range is 1 to -1.
/content/race_common/ai/AICourseTable_VS.byaml unknown
/content/race_common/ai/AIItemTable.byaml Contains AI data for throwing items, and holds a percentage value to each CC. (EASY, NORMAL, HARD, EXPERT) to see how accurate they are.
/content/race_common/ai/AILevelTable.byaml Seems it contains speed data for CPUs...adds "speed ratios" depending on the CC.
/content/race_common/ai/AIProbability_Drift_Table.byaml CPU chances of them drifting during a race, used to sort out difficulty.
/content/race_common/ai/AIProbability_JumpAction_Table.byaml CPU chances of them tricking on ramps, used to sort out difficulty.
/content/race_common/ai/AIProbability_RocketStart_Table.byaml CPU chances of getting the max start of a race, used to sort out difficulty.
/content/race_common/ai/AIProbability_WheelSpin_Table.byaml unknown
/content/race_common/ai/AIItemTable.byaml unknown
/content/race_common/item/ItemSlotTable.byaml unknown
/content/course/*/battle_muunt.byaml Parameters for the battle such as spawn location.
/content/course/*/course_muunt.byaml Parameters for the course such as lap path, gravity and object placement.
/content/data/objflow.byaml Object paramters such as hit box, resource list, animation, id.

Tools

The following tools can handle BYAML files.