nbt

Flexible and intuitive library for reading and writing Minecraft's NBT format.

Overview • Usage • Features • Javadocs • License

Overview

NBT (Named Binary Tag) is a binary format devised by Notch to be Minecraft's primary means of data storage.

Due to the scuffed way the NBT format works, you'll probably want to read up on it before using this library in production. There are 12 types of tag that can be used in a complaint NBT file (see the links below for descriptions of each):

• Byte
• Short
• Int
• Long
• Float
• Double
• Byte Array
• Int Array
• Long Array
• String
• List
• Compound

Tag type IDs 1-12 for each of these can be found here.

All valid NBT structures begin with a compound tag; the root compound. Everything else in the NBT structure is a child of this root compound.

The original NBT specification written by Notch is also hosted here.

Usage

This library can be added as a dependency via maven central:

repositories {
    mavenCentral()
}

dependencies {
    implementation "dev.dewy:nbt:1.5.1"
}

Nbt Sample: Base64

The Nbt class can be used to easily (de)serialize NBT data:

public static final Nbt NBT = new Nbt();

CompoundTag test = NBT.fromBase64("CgALaGVsbG8gd29ybGQDAAR0ZXN0AAAAAAA");

System.out.println(test.getName()); // hello world
System.out.println(test.getInt("test").getValue()); // 0

See the NbtTest class for full sample usage.

SNBT Format

SNBT (Stringified NBT) is a format defined by Mojang used to record NBT tags as readable strings, used in command blocks.

The JSON NBT sample encoded as SNBT is as follows:

{"primitive":3,"array":[I;0,1,2,3],"list":["duck","goose"],"compound":{}}

NBT JSON Format

Every tag in NBT JSON is represented as an object containing the following properties:

• type The tag's type ID. (byte)
• value The tag's value. (JSON primitive, array, or object depending on the tag's type)
• name The tag's name, omitted if contained inside a list tag. (string)

The JSON NBT sample is documented below:

{ // root compound tag named "root"
  "type": 10, // compound tag type ID
  "name": "root",
  "value": {
    "primitive": { // an int tag named "primitive" with the value 3
      "type": 3, // int tag type ID
      "name": "primitive",
      "value": 3
    },
    "array": { // an int array tag named "array" with the value [0, 1, 2, 3]
      "type": 11, // int array tag type ID
      "name": "array",
      "value": [
        0,
        1,
        2,
        3
      ]
    },
    "list": { // a list tag named "list" containing string tags.
      "type": 9, // list tag type ID
      "listType": 8, // string tag type ID (this list contains string tags)
      "name": "list",
      "value": [
        { // unnamed string tag contained within "list"
          "type": 8, // string tag type ID
          "value": "duck"
        },
        {
          "type": 8,
          "value": "goose"
        }
      ]
    },
    "compound": { // an empty compound tag named "compound"
      "type": 10, // compound tag type ID
      "name": "compound",
      "value": {} // empty
    }
  }
}

Features

• Fully compliant with Mojang's "standards"
• Small and lightweight (40Kb!)
• Supports all Java edition NBT tags (including long array)
• Intuitive and flexible reading and writing functionality
• JSON (De)serialization
• SNBT Serialization

Javadocs

Javadocs for the library can be found here.

License

This project is licensed under the MIT license: see here.