Skip to content

README.md

Latest commit

 

History

History
100 lines (79 loc) · 3.47 KB

README.md

File metadata and controls

100 lines (79 loc) · 3.47 KB
Raw

Configurate NBT

Configurate loaders and serializers for NBT (Named Binary Tag) using Kyori Adventure NBT. Supports saving and loading via NBT as well as serializing NBT data into configure.

Loaders

  • NBT
  • SNBT

Serializers

This library provides BinaryTag serializers that can be used independently with any Configurate loader. Since NBT needs to maintain type, two different kinds of serializers are provided:

  • Type-Safe Serializers preserve exact numeric types by appending SNBT-style suffixes (b, s, i, l, f, d).
  • Type-Unsafe Serializers relies on the configuration loader to de-serialize to correct numeric type. Some loaders (HOCON, JSON, YAML, etc.) do not preserve type and as such will not de-serialize correctly.

For both kinds a static TypeSerializerCollection is accessible in BinaryTagSerializer

A Note on Lists

Adventure NBT lists can support heterogeneity (a list with multiple tag types), but, for this a list must be explicitly created with support for it. When deserializing lists the deserializer will always presume that a list that deserializes to one type should be created as a non-heterogeneity supporting list. This means that if a list that supports heterogeneity but only contains one tag type is serialized upon deserialization a non-heterogeneity supporting list will be returned.

Installation

Gradle (Kotlin DSL)

repositories {
    maven {
        name = "hboyd-dev-repo-releases"
        url = uri("https://repo.hboyd.dev/releases/")
    }
    
    // Required for snapshot releases
    maven {
        name = "hboyd-dev-repo-snapshots"
        url = uri("https://repo.hboyd.dev/snapshots/")
    }
}

dependencies {
    implementation("dev.hboyd:configurate-nbt:1.0.0")
}

Examples

Saving using SNBT

// Create a loader for a SNBT file
SNBTConfigurationLoader loader = SNBTConfigurationLoader.builder()
    .path(Paths.get("config.snbt"))
    .indent(4)  // Indentation level
    .indentType(SNBTConfigurationLoader.IndentType.SPACE)
    .legacyFormat(false)
    .build();

// Load and save work the same as binary NBT
ConfigurationNode node = loader.load();
node.node("key").set("value");
loader.save(node);

Saving an ItemStack in a YAML file with the Minecraft Paper API

// Create YAML loader
YamlConfigurationLoader loader = YamlConfigurationLoader.builder()
        .defaultOptions(o ->
                o.serializers(o.serializers()
                    .childBuilder()
                    .registerAll(BinaryTagSerializer.TYPE_SAFE_SERIALIZERS)
                    .build()))
        .path(Path.of("example.yml"))
        .nodeStyle(NodeStyle.BLOCK)
        .build();

// Serialize ItemStack to NBT
CompoundBinaryTag itemStackNBT = inventory.getItemInMainHand().serializeAsBytes();

// Deserialize into Adventure's BinaryTag format
BinaryTag itemStackTag = BinaryTagIO.reader().read(new ByteArrayInputStream(), BinaryTagIO.Compression.GZIP);

// Save into Configurate node and save
ConfigurationNode itemStackTagNode = loader.createNode();
try {
        node.node("item").set(CompoundBinaryTag.class, itemStackTag);
        loader.save(node);
} catch (IOException e) {
        throw new RuntimeException(e);
}

License

This project is licensed under the GPLv3 License - see the LICENSE.md file for details