Class CompoundBuilder

java.lang.Object
de.pauleff.jnbt.builder.NBTBuilder
de.pauleff.jnbt.builder.CompoundBuilder
public class CompoundBuilder extends NBTBuilder
Fluent builder for creating structured NBT compound tags with seamless nesting support. Chain method calls to build complex hierarchical data structures effortlessly.

Build player data with nested inventory:

Tag_Compound player = NBTBuilder.compound("Player")
    .addString("Name", "Steve")
    .addInt("Level", 50)
    .addList("Inventory", NBTTags.Tag_Compound)
        .addCompound("item1")
            .addString("id", "minecraft:diamond_sword")
        .end()
    .end()
    .build();
Author:
Paul Ferlitz
See Also:

  • Constructor Details

    • CompoundBuilder

      public CompoundBuilder(String name, NBTBuilder parent)
      Creates a new compound builder ready for tag assembly.
      Parameters:
      name - the compound's identifier
      parent - the parent builder for nesting support, or null for root compounds

    • CompoundBuilder

      public CompoundBuilder(ICompoundTag existingCompound, NBTBuilder parent)
      Creates a compound builder from an existing compound tag for modification.
      Parameters:
      existingCompound - the existing compound to modify
      parent - the parent builder for nesting support, or null for root compounds

  • Method Details

    • addString

      public CompoundBuilder addString(String name, String value)
      Stores a string value with the specified name.
      Parameters:
      name - the tag identifier
      value - the string content
      Returns:
      this builder for chaining

    • addInt

      public CompoundBuilder addInt(String name, int value)
      Stores an integer value with the specified name.
      Parameters:
      name - the tag identifier
      value - the numeric content
      Returns:
      this builder for chaining

    • addDouble

      public CompoundBuilder addDouble(String name, double value)
      Stores a double-precision value with the specified name.
      Parameters:
      name - the tag identifier
      value - the floating-point content
      Returns:
      this builder for chaining

    • addFloat

      public CompoundBuilder addFloat(String name, float value)
      Stores a single-precision float with the specified name.
      Parameters:
      name - the tag identifier
      value - the floating-point content
      Returns:
      this builder for chaining

    • addByte

      public CompoundBuilder addByte(String name, byte value)
      Stores a byte value with the specified name.
      Parameters:
      name - the tag identifier
      value - the byte content
      Returns:
      this builder for chaining

    • addShort

      public CompoundBuilder addShort(String name, short value)
      Stores a short integer with the specified name.
      Parameters:
      name - the tag identifier
      value - the numeric content
      Returns:
      this builder for chaining

    • addLong

      public CompoundBuilder addLong(String name, long value)
      Stores a long integer with the specified name.
      Parameters:
      name - the tag identifier
      value - the numeric content
      Returns:
      this builder for chaining

    • addByteArray

      public CompoundBuilder addByteArray(String name, byte[] value)
      Stores a byte array with the specified name.
      Parameters:
      name - the tag identifier
      value - the byte array content
      Returns:
      this builder for chaining

    • addIntArray

      public CompoundBuilder addIntArray(String name, int[] value)
      Stores an integer array with the specified name.
      Parameters:
      name - the tag identifier
      value - the integer array content
      Returns:
      this builder for chaining

    • addLongArray

      public CompoundBuilder addLongArray(String name, long[] value)
      Stores a long array with the specified name.
      Parameters:
      name - the tag identifier
      value - the long array content
      Returns:
      this builder for chaining

    • addTag

      public CompoundBuilder addTag(Tag<?> tag)
      Incorporates an existing tag into this compound.
      Parameters:
      tag - the pre-built tag to include
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if tag is null

    • addList

      public ListBuilder addList(String name, NBTTags listType)
      Creates a new list within this compound and switches to list-building mode.
      Parameters:
      name - the list identifier
      listType - the element type this list will contain
      Returns:
      a ListBuilder for adding list elements
      See Also:

    • addCompound

      public CompoundBuilder addCompound(String name)
      Creates a nested compound within this one and switches to nested-building mode.
      Parameters:
      name - the nested compound identifier
      Returns:
      a new CompoundBuilder for the nested structure

    • setString

      public CompoundBuilder setString(String name, String value)
      Updates or creates a string value with the specified name.
      Parameters:
      name - the tag identifier
      value - the string content
      Returns:
      this builder for chaining

    • setInt

      public CompoundBuilder setInt(String name, int value)
      Updates or creates an integer value with the specified name.
      Parameters:
      name - the tag identifier
      value - the numeric content
      Returns:
      this builder for chaining

    • setDouble

      public CompoundBuilder setDouble(String name, double value)
      Updates or creates a double-precision value with the specified name.
      Parameters:
      name - the tag identifier
      value - the floating-point content
      Returns:
      this builder for chaining

    • setFloat

      public CompoundBuilder setFloat(String name, float value)
      Updates or creates a float value with the specified name.
      Parameters:
      name - the tag identifier
      value - the floating-point content
      Returns:
      this builder for chaining

    • setByte

      public CompoundBuilder setByte(String name, byte value)
      Updates or creates a byte value with the specified name.
      Parameters:
      name - the tag identifier
      value - the byte content
      Returns:
      this builder for chaining

    • setShort

      public CompoundBuilder setShort(String name, short value)
      Updates or creates a short integer with the specified name.
      Parameters:
      name - the tag identifier
      value - the numeric content
      Returns:
      this builder for chaining

    • setLong

      public CompoundBuilder setLong(String name, long value)
      Updates or creates a long integer with the specified name.
      Parameters:
      name - the tag identifier
      value - the numeric content
      Returns:
      this builder for chaining

    • setByteArray

      public CompoundBuilder setByteArray(String name, byte[] value)
      Updates or creates a byte array with the specified name.
      Parameters:
      name - the tag identifier
      value - the byte array content
      Returns:
      this builder for chaining

    • setIntArray

      public CompoundBuilder setIntArray(String name, int[] value)
      Updates or creates an integer array with the specified name.
      Parameters:
      name - the tag identifier
      value - the integer array content
      Returns:
      this builder for chaining

    • setLongArray

      public CompoundBuilder setLongArray(String name, long[] value)
      Updates or creates a long array with the specified name.
      Parameters:
      name - the tag identifier
      value - the long array content
      Returns:
      this builder for chaining

    • setTag

      public CompoundBuilder setTag(Tag<?> tag)
      Updates or replaces an existing tag.
      Parameters:
      tag - the tag to set
      Returns:
      this builder for chaining

    • removeTag

      public CompoundBuilder removeTag(String name)
      Removes a tag by name.
      Parameters:
      name - the tag name to remove
      Returns:
      this builder for chaining

    • removeTags

      public CompoundBuilder removeTags(String... names)
      Removes multiple tags by name.
      Parameters:
      names - the tag names to remove
      Returns:
      this builder for chaining

    • clear

      public CompoundBuilder clear()
      Removes all tags from this compound.
      Returns:
      this builder for chaining

    • build

      public ICompoundTag build()
      Finalizes construction and returns the completed compound tag. Only available for root-level compounds.
      Specified by:
      build in class NBTBuilder
      Returns:
      the fully constructed ICompoundTag
      Throws:
      IllegalStateException - if called on a nested builder (use end() first)

    • end

      public NBTBuilder end()
      Completes this nested compound and returns control to the parent builder. Automatically integrates the completed compound into its parent structure.

      When to use end():

      • Terminal operations - when finishing the current branch without further chaining
      • Simple single-level nesting where parent type is obvious
      • Variable storage patterns where builders are stored in variables
      • Legacy code compatibility

      Consider using type-safe alternatives:

      • endCompound() - when continuing to build on a compound parent
      • endList() - when continuing to build on a list parent
      Specified by:
      end in class NBTBuilder
      Returns:
      the parent NBTBuilder to continue building
      Throws:
      IllegalStateException - if called on a root builder (use build() instead)
      Since:
      1.3.0

    • endCompound

      public CompoundBuilder endCompound()
      Type-safe method to return to a CompoundBuilder parent. Provides compile-time safety for fluent method chaining when you know the parent is a compound.

      When to use endCompound():

      • Complex fluent chaining where you need to continue adding to a compound parent
      • When you want compile-time type safety instead of runtime casting
      • Building deeply nested structures with multiple compound levels

      Example usage:

      NBTBuilder.compound("Player")
    .addCompound("Stats")
        .addInt("level", 50)
    .endCompound()  // ← Type-safe return to Player compound
    .addString("name", "Steve");  // ← Can continue building Player
      Returns:
      the parent as a CompoundBuilder
      Throws:
      IllegalStateException - if parent is not a CompoundBuilder
      Since:
      1.5.0

    • endList

      public ListBuilder endList()
      Type-safe method to return to a ListBuilder parent. Provides compile-time safety for fluent method chaining when you know the parent is a list.

      When to use endList():

      • Adding multiple compound elements to a list with continued chaining
      • When you want compile-time type safety for list operations
      • Building arrays of complex objects

      Example usage:

      NBTBuilder.list("inventory", NBTTags.Tag_Compound)
    .addCompound("item1")
        .addString("type", "sword")
    .endList()  // ← Type-safe return to inventory list
    .addCompound("item2")  // ← Can continue adding to list
        .addString("type", "potion")
    .endList();
      Returns:
      the parent as a ListBuilder
      Throws:
      IllegalStateException - if parent is not a ListBuilder
      Since:
      1.5.0

    • getCompound

      protected Tag_Compound getCompound()
      Provides access to the underlying compound for framework integration.
      Returns:
      the compound tag under construction