Class ListBuilder

java.lang.Object
de.pauleff.builder.NBTBuilder
de.pauleff.builder.ListBuilder
public class ListBuilder extends NBTBuilder
Fluent builder for creating type-safe NBT lists. All elements must share the same NBT type, preventing common structural errors when building Minecraft NBT data.

Build complex inventory structures with confidence:


 Tag_List inventory = NBTBuilder.list("Inventory", NBTTags.Tag_Compound)
     .addCompound("item1")
         .addString("id", "minecraft:diamond_sword")
         .addInt("Count", 1)
     .end()
     .build();
Author:
Paul Ferlitz
See Also:

  • Constructor Details

    • ListBuilder

      public ListBuilder(String name, NBTTags listType, NBTBuilder parent)
      Creates a new list builder with strict type enforcement.
      Parameters:
      name - the list tag name
      listType - the NBT type all elements must match
      parent - the parent builder for nesting support, or null for root lists
      Throws:
      IllegalArgumentException - if listType is null

  • Method Details

    • addString

      public ListBuilder addString(String name, String value)
      Adds a string element to the list.
      Parameters:
      name - the element name
      value - the string value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept strings

    • addInt

      public ListBuilder addInt(String name, int value)
      Adds an integer element to the list.
      Parameters:
      name - the element name
      value - the integer value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept integers

    • addDouble

      public ListBuilder addDouble(String name, double value)
      Adds a double element to the list.
      Parameters:
      name - the element name
      value - the double value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept doubles

    • addFloat

      public ListBuilder addFloat(String name, float value)
      Adds a float element to the list.
      Parameters:
      name - the element name
      value - the float value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept floats

    • addByte

      public ListBuilder addByte(String name, byte value)
      Adds a byte element to the list.
      Parameters:
      name - the element name
      value - the byte value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept bytes

    • addShort

      public ListBuilder addShort(String name, short value)
      Adds a short element to the list.
      Parameters:
      name - the element name
      value - the short value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept shorts

    • addLong

      public ListBuilder addLong(String name, long value)
      Adds a long element to the list.
      Parameters:
      name - the element name
      value - the long value
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if this list doesn't accept longs

    • addCompound

      public CompoundBuilder addCompound(String name)
      Begins building a compound element within this list.
      Parameters:
      name - the compound element name
      Returns:
      a CompoundBuilder for defining the compound's contents
      Throws:
      IllegalArgumentException - if this list doesn't accept compounds

    • addList

      public ListBuilder addList(String name, NBTTags nestedListType)
      Begins building a nested list element within this list.
      Parameters:
      name - the nested list element name
      nestedListType - the NBT type for elements in the nested list
      Returns:
      a new ListBuilder for defining the nested list's contents
      Throws:
      IllegalArgumentException - if this list doesn't accept nested lists

    • addBuiltTag

      protected void addBuiltTag(Tag<?> tag)
      Adds a pre-built tag to this list. Used internally by nested builders.
      Parameters:
      tag - the completed tag to add
      Throws:
      IllegalArgumentException - if tag is null or type doesn't match

    • build

      public IListTag build()
      Completes construction and returns the built list.
      Specified by:
      build in class NBTBuilder
      Returns:
      the completed IListTag
      Throws:
      IllegalStateException - if this is a nested builder (call end() first)

    • end

      public NBTBuilder end()
      Finishes this nested list and returns to the parent builder. Automatically integrates the completed list 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
      Throws:
      IllegalStateException - if this is a root builder (call 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():

      • Lists nested within compounds where you need to continue building the compound
      • When you want compile-time type safety instead of runtime casting
      • Building complex structures with mixed container types

      Example usage:

      
 NBTBuilder.compound("Player")
     .addList("inventory", NBTTags.Tag_String)
         .addString("item1", "sword")
         .addString("item2", "potion")
     .endCompound()  // ← Type-safe return to Player compound
     .addInt("level", 50);  // ← 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():

      • Nested lists (lists within lists) where you need to continue building the parent list
      • When you want compile-time type safety for complex list structures
      • Building multi-dimensional array-like structures

      Example usage:

      
 NBTBuilder.list("matrix", NBTTags.Tag_List)
     .addList("row1", NBTTags.Tag_Int)
         .addInt("col1", 1)
         .addInt("col2", 2)
     .endList()  // ← Type-safe return to matrix list
     .addList("row2", NBTTags.Tag_Int)  // ← Can continue adding rows
         .addInt("col1", 3)
         .addInt("col2", 4)
     .endList();
      Returns:
      the parent as a ListBuilder
      Throws:
      IllegalStateException - if parent is not a ListBuilder
      Since:
      1.5.0

    • getListType

      public NBTTags getListType()
      Returns the NBT type this list accepts for all elements.
      Returns:
      the enforced element type

    • getList

      protected Tag_List getList()
      Provides access to the underlying list for parent builders.
      Returns:
      the list being constructed