commit	ad58f0f5883eab25e4ebbe1686ed28604f12df94	[log] [download]
author	Querz <info@querz.net>	Mon Aug 20 16:13:22 2018 +0200
committer	Querz <info@querz.net>	Mon Aug 20 16:13:22 2018 +0200
tree	02cb18ac7365ddda58c56a1ff3a5201353b106e7
parent	d65c928ec39e6c5eed8c242b86842c63383259fd [diff]
parent	93c3e636461fc2c11a686b96c58d563865cc1d87 [diff]

tree: 02cb18ac7365ddda58c56a1ff3a5201353b106e7

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 12 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:

ByteTag bt = new ByteTag("8bitNumber", (byte) 1);
DoubleTag dt = new DoubleTag("64bitFloatingPointNumber", 1.234);

CompoundTag ct = new CompoundTag("compound");

ct.set(bt);
ct.set(dt);
ct.setString("string", "stringValue");

Utility

There are several utility classes that make your life easier using this library.

NBTFileWriter

The NBTFileWriter lets you write a Tag into a gzip compressed or uncompressed file in one line. Files are gzip compressed by default. Example usage:

new NBTFileWriter("filename.dat").write(tag);

NBTFileReader

The NBTFileReader reads any file containing NBT data. No worry about compression, it will automatically uncompress gzip compressed files. Example usage:

Tag tag = new NBTFileReader("filename.dat").read();

Playing Minecraft?

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

CompoundTag c = new CompoundTag("compound");
c.setByte("byte", (byte) 5);
c.setString("string", "test");
String s = c.toTagString();

//output: compound:{byte:5b,string:"test"}

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, it must be registered during runtime with TagType#registerCustomTag(int, Class).