Primer on Named Binary Tags
Chris Cheng
NBT - Named Binary Tags - is essentially an organized binary file that doesn’t necessarily need to be read from front to back, in order. It instead works a bit like a tree - like the files and folders that reside on your computer.
Tags are made of four parts:
/--------+-------------+---------------+-------------\
| ID | Name Length | String: Name | Payload |
| 1 Byte | 2 Bytes | <len> Bytes | <var> Bytes |
\--------+-------------+---------------+-------------/
The ID indicates what type of tag this is. More on the types later.
Name Length is a single two-byte integer indicating how long the name is. This means that there can be at most 65,535 characters in the name.
Name is how to identify each individual tag.
Payload is the data that this individual tag contains. The length of this varies, depending on the type of tag it is.
There’s 11 different types of tags:
0. END: Indicates the tail end of the innermost Compound Tag. See 10.
1. BYTE: Holds a single signed byte, -128 to 127.
2. SHORT: Holds a two-byte integer, -32,768 to 32,767.
3. INT: Holds a four-byte integer, -2,147,483,648 to 2,147,483,647.
4. LONG: Holds an eight-byte integer.
5. FLOAT
6. DOUBLE
7. BYTE ARRAY: The first four bytes indicate how many items there are in the tag (max roughly 2 billion), followed by an array of bytes.
8. STRING: Duplicates the Name detail of the tag, for data.
9. LIST: This is a list of unorganized tags, without names. They’re all of a single type. First byte indicates the ID of the tag, then the next four indicate how many tags there are. Then the payloads only of the tags in the list are listed.
10. COMPOUND: Following the “file-folder” idea, Compound Tags are NBT’s folders. The payload is a listing of complete tags, ending in an End Tag.
11. INT ARRAY: Like a byte array, except it’s an array of four-byte integers.
Example:
10 0 4 ‘N’ ‘A’ ‘M’ ‘E’ 8 0 6 ‘S’ ‘T’ ‘R’ ‘I’ ‘N’ ‘G’ 0 5 ‘S’ ‘T’ ‘U’ ‘F’ ‘F’ 0
Compound Tag “NAME”
String Tag “STRING” containing “STUFF”