SyntaxNBT

A NBT and SNBT library for Java (17)

Overview

This is an implementation for serializing, deserializing, parsing, and stringifying NBTs (Named Binary Tags) by Mojang Studios, according to this specification.

Getting started

In order to use the code, you can either download the jar, or use the Maven dependency:

<!-- Repository -->

<repository>
  <id>syntaxerror.at</id>
  <url>https://maven.syntaxerror.at</url>
</repository>

<!-- Dependency -->

<dependency>
  <groupId>at.syntaxerror</groupId>
  <artifactId>syntaxnbt</artifactId>
  <version>1.0.0</version>
</dependency>

The library itself is located in the module syntaxnbt.

Usage

In order to parse a binary NBT file or an SNBT string, you can use the NBTUtil class:

import java.io.InputStream;
import at.syntaxerror.syntaxnbt.tag.TagCompound;
import at.syntaxerror.syntaxnbt.NBTUtil;

// read NBT tag from a stream
try(InputStream stream = ...) {
    TagCompound tag = NBTUtil.deserialize(stream);
}

// parse SNBT tag from a string
TagCompound tag = NBTUtil.parse("...");

The other way around works analogously:

import java.io.OutputStream;
import at.syntaxerror.syntaxnbt.NBTUtil;

// write NBT tag to a stream
try(OutputStream stream = ...) {
    NBTUtil.serialize(null, stream, tag);
}

// convert SNBT tag to a string
String snbt = NBTUtil.stringify(tag);

// or alternatively:
String snbt = tag.toString();

You can also create tags by yourself:

import at.syntaxerror.syntaxnbt.tag.TagCompound;

TagCompound tag = new TagCompound();
TagList<TagString> list = new TagList<>(TagString.class);
TagInt num = new TagInt(1337);
TagByteArray array = new TagByteArray(new byte[] { 1, 2, 3 });

Compounds

Compound Tags are lists of named tags (basically a Map<String, Tag<?>>). They are implemented in the TagCompound class, exposing the following methods:

• putX(String key, X value) - associates the specified value with the specified key in this compound tag. An existing mapping will be overridden
• getX(String key) - returns the value to which the specified key is mapped. Throws an exception if this map contains no mapping for the key
• remove(String key) - removes the entry associated with the key from the map, if present.
• has(String key) - returns true if this map contains a mapping for the specified key
• size() - returns the number of key-value mappings in this compound tag
• clear() - removes all of the mappings from this map

X stands for any of the supported types (listed below). You can specify either tags (e.g. putByteTag) or values (e.g. putByte), which will automatically be wrapped around their respective tags.

When X is unspecified, the untyped tags are used instead (e.g. put(String key, Tag<?> value)).

Lists

List Tags are lists of unnamed tags (List<Tag<?>>), only capable of holding tags of the same type (specified by the generic type). This type can also be queried by using the getComponentType() method.

If the list is created via TagList.emptyList(), the type of the list is determined by the first operation on the list involving types (e.g. addByte).

Lists are implemented in the TagList<?> class, exposing the following methods:

• addX(X value) - adds an element to the list
• addX(int index, X value) - inserts an element at the specified position in the list
• setX(int index, X value) - replaces an element at the specified position in the list
• getX(int index) - returns the element at the specified position in this list
• remove(int index) - removes the value at the specified position in the list
• size() - returns the number of entries in the list
• clear() - removes all entries from the list

When X is unspecified, the generic type is used instead (e.g. add(ByteTag value) for List<ByteTag>).

When trying to add a tag that is not compatible with the other tags in the list, an exception is thrown.

In case you are dealing with a list of currently unknown type (TagList<?> or TagList<Tag?>>), you can easily cast the list to the desired type by using the asXList() methods. This does not create a new list and will throw an exception if the desired type is incompatible with the component type.

Array

Array Tags are arrays of values of the same type (byte[], int[], or long[]).

They are implemented in the TagByteArray, TagIntArray, and TagLongArray classes, which are all sub-classes of TagArray, exposing the following methods:

• add(Number value), addTag(T value) - adds an element to the array
• add(int index, Number value), addTag(int index, T value) - inserts an element at the specified position in the array
• set(int index, Number value), setTag(int index, T value) - replaces an element at the specified position in the array
• get(int index) - returns the element at the specified position in this array
• remove(int index) - removes the value at the specified position in the list
• size() - returns the number of entries in the array
• clear() - removes all entries from the array

T stands for the tag-equivalent of elements in the array (e.g. for TagByteArray, T would be TagByte). However, not the tag itself is added to the array, only the value stored in this tag.

Tags

The NBT specification specifies the following tags:

ID | Name | Java type | Implementation | Payload size (bytes) | Description -- | ---------------- | --------- | -------------- | -------------------- | ---------- 0 | TAG_End | void | TagEnd | 0 | Signifies the end of a TAG_Compound. It is only ever used inside a TAG_Compound, and is not named despite being in a TAG_Compound 1 | TAG_Byte | byte | TagByte | 1 | A single signed byte 2 | TAG_Short | short | TagShort | 2 | A single signed, big endian 16 bit integer 3 | TAG_Int | int | TagInt | 4 | A single signed, big endian 32 bit integer 4 | TAG_Long | long | TagLong | 8 | A single signed, big endian 64 bit integer 5 | TAG_Float | float | TagFloat | 4 | A single, big endian IEEE-754 single-precision floating point number (NaN possible) 6 | TAG_Double | double | TagDouble | 8 | A single, big endian IEEE-754 double-precision floating point number (NaN possible) 7 | TAG_Byte_Array | byte[] | TagByteArray | 4+n | A length-prefixed array of signed bytes. The prefix is a signed integer (thus 4 bytes) 8 | TAG_String | String | TagString | 2+n | A length-prefixed modified UTF-8 string. The prefix is an unsigned short (thus 2 bytes) signifying the length of the string in bytes 9 | TAG_List | List<Tag> | TagList | 5+x | A list of nameless tags, all of the same type. The list is prefixed with the Type ID of the items it contains (thus 1 byte), and the length of the list as a signed integer (a further 4 bytes). If the length of the list is 0 o