NBT

A java implementation of the NBT protocol for Minecraft Java Edition.

!!! THIS FORK IS UNDER HEAVY DEVELOPMENT - May 2024!!!

But, it is ready for early adopters!

This library includes a rich NBT experience and powerful tools for working with .mca files. The NBT portion is largely stable while the mca library is still going through heavy iteration.

Highlights of the NBT library

• NbtPath Allows you to easily get and put nested tags.
• TextNbtHelpers Utilities for reading and writing text nbt data - with pretty printing! Yes, pretty printed text nbt data is also parseable.
• BinaryNbtHelpers Utilities for working with binary nbt files, compressed or uncompressed.

Highlights of the MCA library

• Version support from Minecraft Java 1.9.0 to 1.20.5 (no Bedrock support currently or planed at this time).
  • DataVersion nearly complete data version to minecraft version mapping and detection back to 1.9.0.
• Rich javadocs on most classes and methods.
• Excellent code coverage and extensive unit testing as well as integration testing for multiple Minecraft versions see test resources
  • There's always room for improvement of the richness of integration data samples - some of the samples are a little less interesting than I would prefer.
• Supports editing of non-vanilla world files without data loss.
• Support for terrain (region), entities, and poi mca files - the various chunk class types are due for a heavy refactor, and I plan to add an abstraction layer to wrap all 3 mca/chunk types to provide a more seamless processing / editing experience.
• Safely relocate (move) chunks - all chunk implementations fully support being moved to a new location. All contents are updated to exist in the new chunk location. This feature is the primary reason I dusted off this project after 3 years and is well tested and very ready for consumption.
  • RegionFileRelocator relocate entire region files.
• Multiple options for reading and writing chunk data to .mca files using one of the following classes.
  • RandomAccessMcaFile read and write chunks with minimal memory overhead.
  • McaFileChunkIterator iterate through the chunks in an mca file one after the other, again keeping memory overhead down.
  • McaFileStreamingWriter write an entire mca file one chunk at a time.

Powerful Utilities

• LongArrayTagPackedIntegers a comprehensive solution to working with all long[] packed values (block palettes, biome palettes, Heightmaps) across all DataVersions.
• PalettizedCuboid powerful class for working with block and biome palettes. This class supports all MC versions that use data palettes; I may add block and biome child classes to improve usability in the future.

How to get started with 0.1-SNAPSHOT

This package is not yet published to a public repository - but using it from a local build is easy!

Download the source, open the project in your IDE of choice (Intellij, etc), run the gradle rule gradle publishToMavenLocal to build the source and stash the 0.1-SNAPSHOT in your local maven cache.

Gradle:

dependencies {
	...
	implementation 'io.github.ensgijs:ens-nbt:0.1-SNAPSHOT'
}

Maven:

<dependency>
    <groupId>io.github.ensgijs</groupId>
    <artifactId>ens-nbt</artifactId>
    <version>0.1-SNAPSHOT</version>
    <scope>compile</scope>
</dependency>

---

NBT 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 payload size, then size ByteTag payloads
StringTag	Tag	8	ShortTag payload length, then a UTF-8 string with size length
ListTag	Tag	9	ByteTag payload tagId, then IntTag payload size, then size tags' payloads, all of type tagId
CompoundTag	Tag	10	Fully formed tags, followed by an EndTag
IntArrayTag	ArrayTag	11	IntTag payload size, then size IntTag payloads
LongArrayTag	ArrayTag	12	IntTag payload size, then size LongTag 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.