MrPippi/docs/paper/inventory

Inventory Skill — Paper

Purpose

Reference this skill when building custom clickable inventory GUIs (chest menus, shop UIs, settings screens) in Paper 1.21. Covers inventory creation, InventoryHolder pattern, and event-driven click handling.

When to Use This Skill

• Creating a chest-style menu that players open with a command
• Building a shop or upgrade UI where clicks perform actions
• Handling InventoryClickEvent to route button clicks to plugin logic
• Preventing players from taking items out of a GUI inventory

API Quick Reference

| Class / Method | Purpose | Notes | |---------------|---------|-------| | Bukkit.createInventory(holder, size, title) | Create a custom inventory | size must be multiple of 9 (9–54) | | Inventory#setItem(slot, ItemStack) | Place an item in a slot | Slots 0–53 for double chest | | Player#openInventory(Inventory) | Open for a player | Main thread only | | InventoryHolder | Tag interface to identify plugin inventories | Implement on your GUI class | | InventoryClickEvent | Fires when any slot is clicked | Check event.getInventory() | | InventoryOpenEvent | Fires when inventory is opened | | | InventoryCloseEvent | Fires when inventory is closed | | | event.setCancelled(true) | Prevent item movement | Use in GUI click handler | | event.getSlot() | Clicked slot index | Top inventory slots only | | event.getClick() | ClickType (LEFT, RIGHT, SHIFT_LEFT…) | | | event.getWhoClicked() | HumanEntity (cast to Player) | |

Code Pattern

package com.yourorg.myplugin.gui;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import net.kyori.adventure.text.format.TextDecoration;
import org.bukkit.Bukkit;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.inventory.InventoryClickEvent;
import org.bukkit.event.inventory.InventoryCloseEvent;
import org.bukkit.inventory.Inventory;
import org.bukkit.inventory.InventoryHolder;
import org.bukkit.inventory.ItemStack;
import org.bukkit.inventory.meta.ItemMeta;
import org.jetbrains.annotations.NotNull;

import java.util.List;

// --- 1. Inventory Holder: identifies this as a plugin GUI ---
public class MainMenuGui implements InventoryHolder {

    private final Inventory inventory;

    public MainMenuGui() {
        // 27-slot (3-row) chest with Adventure title
        this.inventory = Bukkit.createInventory(this, 27,
            Component.text("Main Menu").color(NamedTextColor.DARK_AQUA));

        buildContents();
    }

    private void buildContents() {
        // Fill background with grey glass panes
        ItemStack filler = makeButton(Material.GRAY_STAINED_GLASS_PANE, " ", List.of());
        for (int i = 0; i < inventory.getSize(); i++) {
            inventory.setItem(i, filler);
        }

        // Shop button — slot 11
        inventory.setItem(11, makeButton(
            Material.GOLD_INGOT,
            "Shop",
            List.of(Component.text("Click to open the shop.").color(NamedTextColor.GRAY))
        ));

        // Stats button — slot 13
        inventory.setItem(13, makeButton(
            Material.BOOK,
            "Stats",
            List.of(Component.text("View your stats.").color(NamedTextColor.GRAY))
        ));

        // Close button — slot 15
        inventory.setItem(15, makeButton(
            Material.BARRIER,
            "Close",
            List.of(Component.text("Close this menu.").color(NamedTextColor.RED))
        ));
    }

    private ItemStack makeButton(Material mat, String name, List<Component> lore) {
        ItemStack item = new ItemStack(mat);
        ItemMeta meta = item.getItemMeta();
        meta.displayName(Component.text(name)
            .color(NamedTextColor.WHITE)
            .decoration(TextDecoration.ITALIC, false));
        meta.lore(lore.stream()
            .map(c -> c.decoration(TextDecoration.ITALIC, false))
            .toList());
        item.setItemMeta(meta);
        return item;
    }

    public void open(Player player) {
        player.openInventory(inventory);
    }

    @Override
    public @NotNull Inventory getInventory() {
        return inventory;
    }
}

// --- 2. Event Listener: handles all GUI clicks ---
class GuiListener implements Listener {

    @EventHandler
    public void onInventoryClick(InventoryClickEvent event) {
        // Only handle clicks inside MainMenuGui inventories
        if (!(event.getInventory().getHolder() instanceof MainMenuGui gui)) return;

        // Always cancel to prevent item theft
        event.setCancelled(true);

        // Ignore clicks on the player's own bottom inventory
        if (event.getClickedInventory() != event.getInventory()) return;

        if (!(event.getWhoClicked() instanceof Player player)) return;

        switch (event.getSlot()) {
            case 11 -> player.performCommand("shop");
            case 13 -> player.performCommand("stats");
            case 15 -> player.closeInventory();
        }
    }

    @EventHandler
    public void onInventoryClose(InventoryCloseEvent event) {
        if (event.getInventory().getHolder() instanceof MainMenuGui) {
            // Clean up resources if needed when GUI is closed
        }
    }
}

Common Pitfalls

• Not cancelling InventoryClickEvent: Without event.setCancelled(true), players can pick up the glass-pane filler items or swap them with their own inventory.

• Not checking getClickedInventory(): InventoryClickEvent fires for BOTH the top (GUI) inventory and the player's bottom inventory. Filter by event.getClickedInventory() == event.getInventory() to only handle GUI slots.

• Creating a new Inventory object per click: Calling Bukkit.createInventory() on every click creates thousands of objects. Create the inventory once (in the constructor or open()) and reuse it.

• Identifying GUIs by title string: Titles are user-visible and can collide with other plugins. Always use InventoryHolder (instanceof check) to identify your GUIs reliably.

• Updating items while the GUI is open: Use inventory.setItem(slot, newItem) to update live — the client sees the change without reopening.

Version Notes

• 1.21 / 1.21.1: Bukkit.createInventory(holder, size, Component title) is the standard Adventure-title overload. The String overload is deprecated.

Related Skills

• inventory-events.md — Full InventoryClickEvent, DragEvent reference
• ../items/SKILL.md — Building ItemStack buttons
• ../events/SKILL.md — Event registration