Class CompoundBuilder

java.lang.Object
de.pauleff.builder.NBTBuilder
de.pauleff.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

  • 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

    • 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

    • 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