Minecraft NBT Format
Named Binary Tag (NBT) is the tree-structured data format used by Minecraft to store game data in save files and to pass structured data in commands.
Detection
File patterns: *.dat, *.nbt, level.dat, *.snbt
Keywords: NBT, SNBT, Named Binary Tag, TAG_Byte, TAG_Compound, TAG_List, TAG_End
SNBT patterns: Curly-brace data in Minecraft commands (e.g., {Health:20f,Inventory:[...]})
Binary patterns: GZip-compressed files containing tag ID bytes (0x00-0x0C)
Contexts: Minecraft commands (/data, /execute, /summon, /give), save file parsing
Routing
| When you need to... |
Read |
| Understand what NBT is and how it's used |
basics.md |
| Work with SNBT (the string/text format used in commands) |
snbt.md |
| Parse or write binary NBT data |
binary-format.md |
| See real-world NBT examples from Minecraft commands |
examples.md |
Two Faces of NBT
NBT exists in two forms:
- Binary NBT — The on-disk format used in save files (
.dat, .nbt, chunk data). A tree of typed tags with numeric IDs, usually GZip-compressed.
- SNBT (Stringified NBT) — The text format used in Minecraft commands and data generators (
.snbt files). Human-readable JSON-like syntax.
Quick Reference
Tag Types (Binary IDs)
| ID |
Tag |
Payload |
| 0 |
TAG_End |
None (marks end of compound) |
| 1 |
TAG_Byte |
1 byte, signed |
| 2 |
TAG_Short |
2 bytes, signed, big-endian |
| 3 |
TAG_Int |
4 bytes, signed, big-endian |
| 4 |
TAG_Long |
8 bytes, signed, big-endian |
| 5 |
TAG_Float |
4 bytes, IEEE 754 binary32 |
| 6 |
TAG_Double |
8 bytes, IEEE 754 binary64 |
| 7 |
TAG_Byte_Array |
Int size + bytes |
| 8 |
TAG_String |
Unsigned short size + UTF-8 bytes |
| 9 |
TAG_List |
Byte tag ID + int size + payloads |
| 10 |
TAG_Compound |
Fully formed tags until TAG_End |
| 11 |
TAG_Int_Array |
Int size + int payloads |
| 12 |
TAG_Long_Array |
Int size + long payloads |
SNBT Type Suffixes
| Type |
Suffix |
Example |
| Byte |
b/B |
34B, -20b |
| Short |
s/S |
31415s |
| Int |
(none) or i/I |
31415926 |
| Long |
l/L |
31415926l |
| Float |
f/F |
3.14f |
| Double |
(none) or d/D |
3.1415926 |
Key SNBT Rules
- Compound keys can be unquoted if they match
[a-zA-Z0-9_\-.+]+ and don't start with a digit/-/./+
- String values can be unquoted with same rules; otherwise use
"..." or '...'
- Arrays vs Lists:
[B;1b,2b,3b] is a byte array; [1b,2b,3b] is a list — they are different types
- Heterogeneous lists: SNBT allows
[1, "abc"]; when saved to binary NBT, non-compound entries become compounds with empty-key {"":value}
- Numbers: Support hex (
0x), binary (0b), E notation, underscore separators, signedness suffixes (u/s)
- Boolean: NBT has no boolean —
true/false in SNBT become 1b/0b
Key Binary Rules
- Java Edition: All multi-byte numbers are big-endian
- Bedrock Edition: All multi-byte numbers are little-endian
- TAG_End has no name (just a single
0x00 byte)
- Root tag is always a compound (Java) or compound/list (Bedrock), usually with empty string name
- Nesting limit: 512 levels deep for List and Compound
- Files: Usually GZip-compressed; some are uncompressed or zlib-compressed
Partial Matching (Testing)
When testing NBT with commands like /execute if data or target selector nbt=:
- Compounds: Extra tags in target still match (subset match).
{} matches anything.
- Lists: Order and count ignored — as long as every requested element is present, it matches. Empty list only matches empty list.
- Arrays (byte/int/long): Order and count ARE checked.
- Types must match exactly:
1 (int) ≠ 1d (double)
- Namespaces required:
"stone" ≠ "minecraft:stone"
Java vs Bedrock
| Feature |
Java |
Bedrock |
| Endianness |
Big-endian |
Little-endian |
| level.dat |
GZip-compressed |
Uncompressed + 8-byte header |
| Heterogeneous lists |
Supported in SNBT |
N/A |
Dependencies
No external tools required. For working with NBT files, common tools include:
- NBTExplorer / NBT Studio — GUI NBT file viewer/editor
- webNBT — Online NBT viewer
- Vanilla data generator — Converts
.snbt ↔ .nbt
Validation Patterns
When validating SNBT:
- Check that all tags have a valid type suffix
- Verify compound keys are properly quoted if they contain special characters
- Ensure arrays use the correct prefix (
B;, I;, L;)
- Confirm numbers are within their type's range
- Check for balanced brackets and braces
- Verify escape sequences in strings are valid
- Ensure namespaces are present in resource location strings when testing matches
1---2name: minecraft-nbt3description: To understand Minecraft NBT (Named Binary Tag) format. Use when: (1) user references NBT, SNBT, or Named Binary Tag, (2) user works with Minecraft commands using data tags (curly-brace syntax), (3) user mentions .dat, .nbt, level.dat, or Minecraft save files, (4) user needs to parse, generate, or validate NBT/SNBT data, (5) user asks about NBT tag types like TAG_Byte, TAG_Compound, etc., (6) code or context contains NBT-format binary data or SNBT strings4---56# Minecraft NBT Format78Named Binary Tag (NBT) is the tree-structured data format used by Minecraft to store game data in save files and to pass structured data in commands.910## Detection1112**File patterns:** `*.dat`, `*.nbt`, `level.dat`, `*.snbt`13**Keywords:** `NBT`, `SNBT`, `Named Binary Tag`, `TAG_Byte`, `TAG_Compound`, `TAG_List`, `TAG_End`14**SNBT patterns:** Curly-brace data in Minecraft commands (e.g., `{Health:20f,Inventory:[...]}`)15**Binary patterns:** GZip-compressed files containing tag ID bytes (0x00-0x0C)16**Contexts:** Minecraft commands (`/data`, `/execute`, `/summon`, `/give`), save file parsing1718## Routing1920| When you need to... | Read |21|---|---|22| Understand what NBT is and how it's used | [basics.md](basics.md) |23| Work with SNBT (the string/text format used in commands) | [snbt.md](snbt.md) |24| Parse or write binary NBT data | [binary-format.md](binary-format.md) |25| See real-world NBT examples from Minecraft commands | [examples.md](examples.md) |2627## Two Faces of NBT2829NBT exists in two forms:30311. **Binary NBT** — The on-disk format used in save files (`.dat`, `.nbt`, chunk data). A tree of typed tags with numeric IDs, usually GZip-compressed.322. **SNBT (Stringified NBT)** — The text format used in Minecraft commands and data generators (`.snbt` files). Human-readable JSON-like syntax.3334## Quick Reference3536### Tag Types (Binary IDs)3738| ID | Tag | Payload |39|----|-----|---------|40| 0 | TAG_End | None (marks end of compound) |41| 1 | TAG_Byte | 1 byte, signed |42| 2 | TAG_Short | 2 bytes, signed, big-endian |43| 3 | TAG_Int | 4 bytes, signed, big-endian |44| 4 | TAG_Long | 8 bytes, signed, big-endian |45| 5 | TAG_Float | 4 bytes, IEEE 754 binary32 |46| 6 | TAG_Double | 8 bytes, IEEE 754 binary64 |47| 7 | TAG_Byte_Array | Int size + bytes |48| 8 | TAG_String | Unsigned short size + UTF-8 bytes |49| 9 | TAG_List | Byte tag ID + int size + payloads |50| 10 | TAG_Compound | Fully formed tags until TAG_End |51| 11 | TAG_Int_Array | Int size + int payloads |52| 12 | TAG_Long_Array | Int size + long payloads |5354### SNBT Type Suffixes5556| Type | Suffix | Example |57|------|--------|---------|58| Byte | `b`/`B` | `34B`, `-20b` |59| Short | `s`/`S` | `31415s` |60| Int | (none) or `i`/`I` | `31415926` |61| Long | `l`/`L` | `31415926l` |62| Float | `f`/`F` | `3.14f` |63| Double | (none) or `d`/`D` | `3.1415926` |6465### Key SNBT Rules6667- **Compound keys** can be unquoted if they match `[a-zA-Z0-9_\-.+]+` and don't start with a digit/`-`/`.`/`+`68- **String values** can be unquoted with same rules; otherwise use `"..."` or `'...'`69- **Arrays** vs **Lists**: `[B;1b,2b,3b]` is a byte array; `[1b,2b,3b]` is a list — they are different types70- **Heterogeneous lists**: SNBT allows `[1, "abc"]`; when saved to binary NBT, non-compound entries become compounds with empty-key `{"":value}`71- **Numbers**: Support hex (`0x`), binary (`0b`), E notation, underscore separators, signedness suffixes (`u`/`s`)72- **Boolean**: NBT has no boolean — `true`/`false` in SNBT become `1b`/`0b`7374### Key Binary Rules7576- **Java Edition**: All multi-byte numbers are **big-endian**77- **Bedrock Edition**: All multi-byte numbers are **little-endian**78- **TAG_End** has no name (just a single `0x00` byte)79- **Root tag** is always a compound (Java) or compound/list (Bedrock), usually with empty string name80- **Nesting limit**: 512 levels deep for List and Compound81- **Files**: Usually GZip-compressed; some are uncompressed or zlib-compressed8283### Partial Matching (Testing)8485When testing NBT with commands like `/execute if data` or target selector `nbt=`:86- **Compounds**: Extra tags in target still match (subset match). `{}` matches anything.87- **Lists**: Order and count ignored — as long as every requested element is present, it matches. Empty list only matches empty list.88- **Arrays** (byte/int/long): Order and count ARE checked.89- **Types must match exactly**: `1` (int) ≠ `1d` (double)90- **Namespaces required**: `"stone"` ≠ `"minecraft:stone"`9192## Java vs Bedrock9394| Feature | Java | Bedrock |95|---------|------|---------|96| Endianness | Big-endian | Little-endian |97| level.dat | GZip-compressed | Uncompressed + 8-byte header |98| Heterogeneous lists | Supported in SNBT | N/A |99100## Dependencies101102No external tools required. For working with NBT files, common tools include:103- **NBTExplorer** / **NBT Studio** — GUI NBT file viewer/editor104- **webNBT** — Online NBT viewer105- Vanilla **data generator** — Converts `.snbt` ↔ `.nbt`106107## Validation Patterns108109When validating SNBT:1101. Check that all tags have a valid type suffix1112. Verify compound keys are properly quoted if they contain special characters1123. Ensure arrays use the correct prefix (`B;`, `I;`, `L;`)1134. Confirm numbers are within their type's range1145. Check for balanced brackets and braces1156. Verify escape sequences in strings are valid1167. Ensure namespaces are present in resource location strings when testing matches
woyxiang