InvUI Documentation

An IngredientMatrix represents a grid of ingredients, typically used for crafting-style inventories. It is an immutable structure defined by a width, a height, and a structure string that maps the layout of ingredients.

To create one, you provide:

1. width and height of the grid.
2. A structure string of length width * height where each character represents an ingredient type.
3. An ingredientMap that maps these characters to Ingredient objects.

If an Ingredient is defined as an Ingredient.Element(SlotElementSupplier), the matrix will automatically invoke the supplier to generate SlotElements for the corresponding slots. You can also use Markers within your ingredients to identify specific slots (e.g., for content lists).

// Conceptual usage of the IngredientMatrix constructor
int width = 3;
int height = 3;
String structure = "ABCDEFGHI"; // 9 characters for 3x3

Map<Character, Ingredient> ingredientMap = new HashMap<>();
ingredientMap.put('A', ingredientA);
// ... add other ingredients

IngredientMatrix matrix = new IngredientMatrix(width, height, structure, ingredientMap);

The ItemProvider determines what the item looks like. CustomBoundItem.Builder provides several ways to set this:

• Static: .setItemProvider(ItemProvider itemProvider)
• Player-dependent: .setItemProvider(Function<? super Player, ? extends ItemProvider> itemProvider)
• GUI and Player-dependent: .setItemProvider(BiFunction<? super Player, ? super G, ? extends ItemProvider> itemProvider)
• Cycling: .setCyclingItemProvider(int period, List<? extends ItemProvider> itemProviders) cycles through a list of providers every period ticks.
• Asynchronous: Use .async(ItemProvider placeholder, Supplier<? extends ItemProvider> itemProviderSupplier) or .async(ItemProvider placeholder, CompletableFuture<? extends ItemProvider> itemProviderFuture) to prevent blocking the main thread while loading items.

// Cycling through items every 20 ticks
builder.setCyclingItemProvider(20, List.of(item1, item2, item3));

// Async loading with a placeholder
builder.async(placeholderItem, () -> fetchRealItem());

You can chain multiple handlers to a CustomBoundItem using add...Handler methods. These handlers are executed in the order they are added.

Instead of using the generic CustomBoundItem.Builder, use these specialized static inner classes to ensure the item automatically reacts to specific GUI state changes:

• CustomBoundItem.Paged: Automatically triggers item updates when the page changes or the total page count changes in a PagedGui.
• CustomBoundItem.Scroll: Automatically triggers item updates when the scroll position or line count changes in a ScrollGui.
• CustomBoundItem.Tab: Automatically triggers item updates when the active tab changes in a TabGui.

// Use Paged builder to react to page changes
BoundItem<PagedGui<?>> pagedItem = new CustomBoundItem.Paged()
    .setItemProvider(myProvider)
    .build();

// Use Scroll builder to react to scrolling
BoundItem<ScrollGui<?>> scrollItem = new CustomBoundItem.Scroll()
    .setItemProvider(myProvider)
    .build();

// Use Tab builder to react to tab switches
BoundItem<TabGui> tabItem = new CustomBoundItem.Tab()
    .setItemProvider(myProvider)
    .build();

Once an IngredientMatrix is constructed, you can query it to find specific slots, ingredient keys, or UI elements at specific coordinates or indices.

Querying Keys

• getKey(int i): Gets the ingredient key at the given index.
• getKey(int x, int y): Gets the ingredient key at the given coordinates.

Querying Slots

• getSlots(char key): Returns an unmodifiable list of all Slot objects associated with a specific ingredient key, ordered left-to-right, top-to-bottom.
• getSlots(Marker marker): Returns an unmodifiable list of Slot objects that are marked with the specified Marker.
• getContentListSlots(): A convenience method to get all slots marked as either Markers.CONTENT_LIST_SLOT_HORIZONTAL or Markers.CONTENT_LIST_SLOT_VERTICAL.

Querying SlotElements

• getSlotElement(int i): Gets the SlotElement at the given index.
• getSlotElement(int x, int y): Gets the SlotElement at the given coordinates.

Use CustomItem.Builder to create items with custom logic for how they look (via ItemProvider), how they respond to clicks, and how they respond to being selected in a bundle. This is useful for items that need to change dynamically based on the player or external state.

Key capabilities:

• Dynamic Providers: Set an ItemProvider that can change based on the Player viewing it.
• Event Handlers: Chain multiple click and selection handlers using addClickHandler and addBundleSelectHandler.
• Asynchronous Loading: Use .async() to show a placeholder item while a real item is being fetched from a Supplier or CompletableFuture.
• Automatic Updates: Configure the item to refresh its appearance periodically via updatePeriodically(int period) or whenever it is clicked via updateOnClick().

Item customItem = new CustomItem.Builder()
    .setItemProvider(player -> myDynamicItemProvider(player))
    .addClickHandler((item, click) -> {
        // Handle click logic here
    })
    .updateOnClick()
    .build();