bitbuf / nbt

Flexible and intuitive Java NBT library, with emphasis on custom tags.

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.

nbt's Issues

Why u hate maven

please provide maven version

How to serialize a class with this?

I am making an RPG game and would like to use this for game saving (because I want to use NBTexplorer to cheat a bit), so I am asking how to serialize an entire class (just a normal serializable class with some ints, floats, one 3d int array and two normal int arrays).

Thanks in advance.

A crash while saving NBT

CompoundTag config = new CompoundTag();
		
		config.put("globalSettings", GlobalSettings.loader.save(GlobalSettings.instance));
		config.put("profileCollection", ProfileCollection.loader.save(ProfileCollection.instance));
		config.put("javaRuntimeCollection", JavaRuntimeCollection.loader.save(JavaRuntimeCollection.instance));
		config.put("launcher", Launcher.loader.save(launcher));
		config.put("translation", Translation.loader.save(Translation.instance));
		
		try {
			new Nbt().toFile(config, FileMetadata.config); // Crashed here
		} catch (Exception e) {
			logger.error("Failed to save config: ", e);
		}

Stacktrace:

java.lang.NullPointerException: Cannot read field "next" because "this.next" is null
	at java.util.LinkedList$ListItr.next(LinkedList.java:904) ~[?:?]
	at dev.dewy.nbt.tags.collection.ListTag.write(ListTag.java:109) ~[nbt-1.5.1.jar:?]
	at dev.dewy.nbt.tags.collection.CompoundTag.write(CompoundTag.java:92) ~[nbt-1.5.1.jar:?]
	at dev.dewy.nbt.io.NbtWriter.toStream(NbtWriter.java:37) ~[nbt-1.5.1.jar:?]
	at dev.dewy.nbt.Nbt.toStream(Nbt.java:85) ~[nbt-1.5.1.jar:?]
	at dev.dewy.nbt.Nbt.toFile(Nbt.java:122) ~[nbt-1.5.1.jar:?]
	at dev.dewy.nbt.Nbt.toFile(Nbt.java:96) ~[nbt-1.5.1.jar:?]
	at minecraft.morningmc.mcli.launcher.main.Main.stop(Main.java:132) ~[classes/:?]
	at com.sun.javafx.application.LauncherImpl.lambda$launchApplication1$10(LauncherImpl.java:858) ~[javafx-graphics-21-win.jar:?]
	at com.sun.javafx.application.PlatformImpl.lambda$runAndWait$12(PlatformImpl.java:483) ~[javafx-graphics-21-win.jar:?]
	at com.sun.javafx.application.PlatformImpl.lambda$runLater$10(PlatformImpl.java:456) ~[javafx-graphics-21-win.jar:?]
	at java.security.AccessController.doPrivileged(AccessController.java:400) ~[?:?]
	at com.sun.javafx.application.PlatformImpl.lambda$runLater$11(PlatformImpl.java:455) ~[javafx-graphics-21-win.jar:?]
	at com.sun.glass.ui.InvokeLaterDispatcher$Future.run(InvokeLaterDispatcher.java:95) ~[javafx-graphics-21-win.jar:?]
	at com.sun.glass.ui.win.WinApplication._runLoop(Native Method) ~[javafx-graphics-21-win.jar:?]
	at com.sun.glass.ui.win.WinApplication.lambda$runLoop$3(WinApplication.java:185) ~[javafx-graphics-21-win.jar:?]
	at java.lang.Thread.run(Thread.java:1583) ~[?:?]

New version?

I found this library and ran straight into a bug where toBytesArray returns an empty array.
Well I found the reason and noticed that there was already a PullRequest #2 for it, which got merged long ago.

The currently released version 1.5.1 is about 2 years old by now.

It however still contains all the bugs that had been fixed long ago.

Is there any plans to release a new version 1.5.2 with the fixes to the maven central repository?