Skip to content

Latest commit

 

History

History
212 lines (179 loc) · 11.8 KB

README.md

File metadata and controls

212 lines (179 loc) · 11.8 KB
Raw

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.
  • Multiple options for reading and writing chunk data to .mca files using one of the following classes.

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.