commit	9b18fc499bff1df4b813526541dd1c37ffba743a	[log] [download]
author	Querz <info@querz.net>	Fri Sep 07 08:56:27 2018 +0200
committer	Querz <info@querz.net>	Fri Sep 07 08:56:27 2018 +0200
tree	8b7edbb2eae450230e5d2eca16df5c1927de12c4
parent	2c7bbf89fd1555893d9e5a1b0fc5814a35224471 [diff]

tree: 8b7edbb2eae450230e5d2eca16df5c1927de12c4

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"}

There are also some tools to read, change and write MCA files: For example:

//This changes the InhabitedTime field of the chunk at x=68, z=81 to 0

MCAFile mcaFile = MCAUtil.readMCAFile("r.2.2.mca");
CompoundTag tag = mcaFile.getChunkData(68, 81);
tag.getCompoundTag("Level").setLong("InhabitedTime", 0L);
MCAUtil.writeMCAFile(mcaFile);

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().