commit	3c2eb242eb33aeee03eb0b3beeaaeaec1c9592b8	[log] [download]
author	Querz <info@querz.net>	Tue Aug 21 15:32:36 2018 +0200
committer	Querz <info@querz.net>	Tue Aug 21 15:32:36 2018 +0200
tree	41311c4b2e6e637ff93a560c45af9ee464f070af
parent	4644a3bc5d91571007a5be8aa3abf64616490ed8 [diff]

tree: 41311c4b2e6e637ff93a560c45af9ee464f070af

README.md

NBT

A java implementation of the NBT protocol, including a way to implement custom tags.

Specification

According to the specification, there are currently 13 different types of tags:

Tag class	Superclass	ID	Payload
EndTag	Tag	0	None
ByteTag	NumberTag	1	1 byte / 8 bits, signed
ShortTag	NumberTag	2	2 bytes / 16 bits, signed, big endian
IntTag	NumberTag	3	4 bytes / 32 bits, signed, big endian
LongTag	NumberTag	4	8 bytes / 64 bits, signed, big endian
FloatTag	NumberTag	5	4 bytes / 32 bits, signed, big endian, IEEE 754-2008, binary32
DoubleTag	NumberTag	6	8 bytes / 64 bits, signed, big endian, IEEE 754-2008, binary64
ByteArrayTag	ArrayTag	7	`IntTag`'s payload size, then size `ByteTag`'s payloads
StringTag	Tag	8	`ShortTag`'s payload length, then a UTF-8 string with size length
ListTag	Tag	9	`ByteTag`'s payload tagId, then `IntTag`‘s payload size, then size tags’ payloads, all of type tagId
CompoundTag	Tag	10	Fully formed tags, followed by an `EndTag`
IntArrayTag	ArrayTag	11	`IntTag`'s payload size, then size `IntTag`'s payloads
LongArrayTag	ArrayTag	12	`IntTag`'s payload size, then size `LongTag`'s payloads

The EndTag is only used to mark the end of a CompoundTag in its serialized state or an empty ListTag.
The maximum depth of the NBT structure is 512. If the depth exceeds this restriction during serialization, deserialization or String conversion, a MaxDepthReachedException is thrown. This usually happens when a circular reference exists in the NBT structure. The NBT specification does not allow circular references, as there is no tag to represent this.

Example usage:

The following code snippet shows how to create a CompoundTag:

CompoundTag ct = new CompoundTag();

ct.put("byte", new ByteTag((byte) 1));
ct.put("double", new DoubleTag(1.234));
ct.putString("string", "stringValue");

An example on how to use ListTag:

ListTag<FloatTag> fl = new ListTag<>();

fl.add(new FloatTag(1.234f);
fl.addFloat(5.678f);

Utility

There are several utility methods to make your life easier if you use this library.

NBTUtil

NBTUtil.writeTag() lets you write a Tag into a gzip compressed or uncompressed file in one line (not counting exception handling). Files are gzip compressed by default. Example usage:

NBTUtil.writeTag(tag, "filename.dat");

NBTUtil.readTag() reads any file containing NBT data. No worry about compression, it will automatically uncompress gzip compressed files. Example usage:

Tag tag = NBTUtil.readTag("filename.dat");

Playing Minecraft?

Each tag can be converted into a JSON-like NBT String used in Minecraft commands. Example usage:

CompoundTag c = new CompoundTag();
c.putByte("blah", (byte) 5);
c.putString("foo", "bär");
String s = c.toTagString();

//output: {blah:5b,foo:"bär"}

Custom tags

Interested in more advanced features, and the default NBT protocol just isn't enough? Simply create your own tags! There are 4 example classes in net.querz.nbt.custom that show how to implement custom tags:

Class	ID	Description
ObjectTag	90	A wrapper tag that serializes and deserializes any object using the default java serialization.
ShortArrayTag	100	In addition to the already existing `ByteArrayTag`, `IntArrayTag` and `LongArrayTag`.
CharTag	110	`Character` (char) tag.
StructTag	120	Similar to the `ListTag`, but with the ability to store multiple types.

To be able to use a custom tag with deserialization, it needs to have a public no-args constructor and its id and class must be registered during runtime with TagFactory.registerCustomTag().