Project: Shop menu

In this project you build a chest shop. Players type /shop, pick a category, click an item and confirm the purchase. Prices are paid in experience levels, and every item and price comes from config.yml, so the server owner can change the shop without touching any Java.

What you will build

Shops are one of the first things a server owner asks for, and a chest menu is the friendliest way to show one. This project puts several earlier chapters to work in one plugin: chest menus, config files, items, inventories and events. You pay with the player's experience levels (the green number above the hotbar). That way the plugin needs no other money plugin, and a player earns "money" just by mining, smelting and killing mobs.

The shop has three screens. First the player sees the categories:

Clicking a category opens its items, each with the amount you get and the price:

Clicking an item opens a confirm screen, so nobody spends levels by accident:

After a click on Buy the player gets a chat message, and the shop goes back to the item list:

If the player is short of levels, or the backpack is full, the shop says so and takes nothing:

These are the rules the plugin follows:

The plan

The shop is a small chain of screens, and only the last click does anything that matters. This picture shows the path, and the two checks that happen before a purchase:

Every piece of the plan is one small class. This table shows which class does what, and where to read more about the idea behind it:

The build steps are:

1. Write plugin.yml and config.yml

   Decide what the server owner can change before writing any Java.

2. Turn the config into records

   Two tiny data classes and a loader that checks every entry.

3. Build the menu base and protect the items

   A holder class, plus the listener that stops every kind of item theft.

4. Make the item icons

   One helper that builds buttons, and a clear line between the icon and the real goods.

5. Build the category and items screens

   Buttons that open the next screen.

6. Build the confirm screen and the purchase

   The check for levels, the check for room, the payment and the messages.

7. Add /shop and register everything

   The command, the main class, and a testing checklist.

This page reuses the menu design from Chest menus and explains it more briefly. If the words holder or slot feel new, read that chapter first.

Step 1: write plugin.yml and config.yml

Create a project the same way as in the earlier projects (copy the starter, or run new-plugin.cmd -Name ShopGui from the paper-templates folder) with the package com.example.projectshopgui. The plugin.yml declares two permissions:

1name: ShopGui2version: '1.0.0'3main: com.example.projectshopgui.ShopPlugin4api-version: '26.3'5description: A chest shop with categories, a confirm screen and prices paid in experience levels.6permissions:17  shopgui.use:8    description: Lets a player open the shop with /shop.9    default: true210  shopgui.reload:11    description: Lets a player reload the shop prices with /shop reload.12    default: op

Now the most important file: config.yml. Everything a server owner may want to change goes here: the menu title, the messages, and the whole shop. Read the file from the top. The shop is a tree of categories, and every category holds items:

11menu-title: "<dark_green><bold>Shop"2 3messages:24  bought: "<green>You bought <white><amount>x <item></white> for <yellow><price> levels</yellow>."5  not-enough-levels: "<red>You need <yellow><price> levels</yellow>, but you only have <yellow><have></yellow>."6  inventory-full: "<red>Your inventory has no room for that. Make some space and try again."7  reloaded: "<green>The shop was reloaded: <white><categories></white> categories, <white><items></white> items."8 39categories:10  building:411    icon: BRICKS512    name: "<gold>Building blocks"13    items:614      oak-logs:715        material: OAK_LOG816        amount: 16917        price: 2

The rest of the file has two more categories, food and tools, built the same way. An item can also have an optional name, like "<aqua>Hero Sword", which the player sees on the item itself.

Step 2: turn the config into records

You could read getInt("categories.food.items.steak.price") every time a player opens the shop, but the code would be full of long text paths, and a typo would only show up when a player clicks that exact button. A better design reads the file once, checks it, and turns it into small Java objects. The objects are records: classes whose only job is to hold a few values. Java writes the constructor and the getter methods for you.

1package com.example.projectshopgui;2 3import org.bukkit.Material;4 15public record ShopItem(String id, Material material, int amount, int price, String customName) {6}

1package com.example.projectshopgui;2 3import java.util.List;4import org.bukkit.Material;5 16public record ShopCategory(String id, Material icon, String name, List<ShopItem> items) {7}

The loader is the longest class of the plugin, and the most important one for beginners to understand: it is the place where untrusted text meets your code. A server owner can type anything into config.yml. The loader reads it with suspicion and skips bad entries instead of crashing. This is its main method:

21public static ShopCatalog load(FileConfiguration config, Logger logger) {122    List<ShopCategory> categories = new ArrayList<>();223    ConfigurationSection section = config.getConfigurationSection("categories");24    if (section == null) {525        logger.warning("config.yml has no 'categories' section, so the shop is empty.");26        return new ShopCatalog(categories);27    }328    for (String categoryId : section.getKeys(false)) {429        if (categories.size() == MAX_CATEGORIES) {30            logger.warning("The shop shows at most " + MAX_CATEGORIES + " categories. Skipping '" + categoryId + "'.");31            continue;32        }33        ConfigurationSection categorySection = section.getConfigurationSection(categoryId);34        ShopCategory category = readCategory(categoryId, categorySection, logger);635        if (category != null) {36            categories.add(category);37        }38    }739    return new ShopCatalog(List.copyOf(categories));40}

Reading one item is where the checks happen. Every line below protects the server from one specific mistake an owner might make:

70private static ShopItem readItem(String categoryId, String itemId, ConfigurationSection section, Logger logger) {171    String where = categoryId + "." + itemId;72    if (section == null) {73        logger.warning("Item '" + where + "' is not a section. Skipping it.");74        return null;75    }276    Material material = readMaterial(section.getString("material"));77    if (material == null) {78        logger.warning("Item '" + where + "' has a missing or unknown material. Skipping it.");79        return null;80    }381    int amount = Math.clamp(section.getInt("amount", 1), 1, material.getMaxStackSize());582    int price = section.getInt("price", -1);683    if (price < 1) {84        logger.warning("Item '" + where + "' needs a price of at least 1. Skipping it.");85        return null;86    }87    return new ShopItem(itemId, material, amount, price, section.getString("name"));88}

90private static Material readMaterial(String text) {91    if (text == null) {92        return null;93    }194    Material material = Material.matchMaterial(text);295    if (material == null || !material.isItem() || material.isAir()) {96        return null;97    }98    return material;99}

Step 3: build the menu base and protect the items

Now the window. The base class is the same idea as in Chest menus: a holder is an object that owns a chest window. Because every shop screen is a Menu, our code can later ask any open window "who owns you?" and know at once that it is a shop screen.

1package com.example.projectshopgui;2 3import java.util.HashMap;4import java.util.Map;5import java.util.function.Consumer;6import net.kyori.adventure.text.Component;7import org.bukkit.Bukkit;8import org.bukkit.Sound;9import org.bukkit.entity.Player;10import org.bukkit.event.inventory.InventoryClickEvent;11import org.bukkit.inventory.Inventory;12import org.bukkit.inventory.InventoryHolder;13import org.bukkit.inventory.ItemStack;14 115public abstract class Menu implements InventoryHolder {16 17    private final Inventory inventory;218    private final Map<Integer, Consumer<Player>> actions = new HashMap<>();19 20    protected Menu(int rows, Component title) {321        this.inventory = Bukkit.createInventory(this, rows * 9, title);22    }23 424    protected abstract void render(Player viewer);25 26    public final void open(Player viewer) {27        redraw(viewer);528        viewer.openInventory(inventory);29    }30 31    protected final void redraw(Player viewer) {32        inventory.clear();33        actions.clear();34        render(viewer);35    }36 637    protected final void button(int slot, ItemStack icon, Consumer<Player> action) {38        inventory.setItem(slot, icon);39        actions.put(slot, action);40    }41 42    protected final void icon(int slot, ItemStack icon) {43        inventory.setItem(slot, icon);44    }45 746    protected final void fillEmpty() {47        for (int slot = 0; slot < inventory.getSize(); slot++) {48            if (inventory.getItem(slot) == null) {49                inventory.setItem(slot, Icons.filler());50            }51        }52    }53 54    final void handleClick(InventoryClickEvent event) {855        Consumer<Player> action = actions.get(event.getSlot());956        if (action != null && event.getWhoClicked() instanceof Player player) {57            player.playSound(player, Sound.UI_BUTTON_CLICK, 0.6f, 1.0f);58            action.accept(player);59        }60    }61 62    @Override63    public final Inventory getInventory() {64        return inventory;65    }66}

The menu does nothing yet, because nobody calls handleClick. That is the listener's job. It is also the plugin's theft protection, so read it carefully:

1package com.example.projectshopgui;2 3import org.bukkit.event.EventHandler;4import org.bukkit.event.EventPriority;5import org.bukkit.event.Listener;6import org.bukkit.event.inventory.InventoryClickEvent;7import org.bukkit.event.inventory.InventoryDragEvent;8 9public final class MenuListener implements Listener {10 111    @EventHandler(priority = EventPriority.HIGH)12    public void onClick(InventoryClickEvent event) {213        if (!(event.getInventory().getHolder(false) instanceof Menu menu)) {14            return;15        }416        event.setCancelled(true);517        if (event.getClickedInventory() == event.getView().getTopInventory()) {18            menu.handleClick(event);19        }20    }21 22    @EventHandler(priority = EventPriority.HIGH)623    public void onDrag(InventoryDragEvent event) {24        if (event.getInventory().getHolder(false) instanceof Menu) {25            event.setCancelled(true);26        }27    }28}

Why cancel every click, even those in the player's own backpack? Because players have many ways to move items, and most of them look harmless:

Step 4: make the item icons

All screens build their icons with one helper class, Icons. Most of it is the button builder from the Chest menus chapter: an item with a name and lore. The two methods that are new are the ones about shop goods:

34static ItemStack goods(ShopItem item) {135    ItemStack stack = ItemStack.of(item.material(), item.amount());236    if (item.customName() != null) {337        stack.editMeta(meta -> meta.displayName(text(item.customName())));38    }39    return stack;40}

42static ItemStack display(ShopItem item, String... lore) {143    ItemStack icon = goods(item);244    icon.editMeta(meta -> meta.lore(Arrays.stream(lore).map(Icons::text).toList()));45    return icon;46}

The shop deliberately has two methods that build almost the same stack. goods is the real thing a player receives. display is a copy with extra lore, used only in menus. Handing out the display stack would give players an Oak Log that says "Click to buy" forever, and it would not stack with a normal Oak Log. Each call to goods or display builds a new stack, so the icon in the menu and the item in the backpack never become the same object.

Step 5: build the category and items screens

With the base class ready, a screen is just a render method. This is the first screen, the list of categories:

21@Override22protected void render(Player viewer) {123    icon(LEVELS_SLOT, Icons.button(Material.EXPERIENCE_BOTTLE,224        "<green>Your levels: <white>" + viewer.getLevel(),25        "<gray>Everything here is paid in",26        "<gray>experience levels."));27 328    List<ShopCategory> categories = shop.catalog().categories();429    if (categories.isEmpty()) {30        icon(EMPTY_SLOT, Icons.button(Material.STRUCTURE_VOID, "<gray>The shop is empty"));31    }32    for (int index = 0; index < categories.size(); index++) {33        ShopCategory category = categories.get(index);534        button(CATEGORY_SLOTS[index],35            Icons.button(category.icon(), category.name(),36                "<gray>" + category.items().size() + " items",37                "",38                "<yellow>Click to browse"),639            player -> new ItemsMenu(shop, category).open(player));40    }41 742    button(CLOSE_SLOT, Icons.button(Material.BARRIER, "<red>Close"), Player::closeInventory);43    fillEmpty();44}

The items screen has the same shape. Each item becomes one button, in slots 0 to 26, and the bottom row holds the Back button:

21@Override22protected void render(Player viewer) {23    List<ShopItem> items = category.items();124    for (int slot = 0; slot < items.size(); slot++) {25        ShopItem item = items.get(slot);26        button(slot,227            Icons.display(item,28                "<gray>Amount: <white>" + item.amount(),29                "<gray>Price: <yellow>" + item.price() + " levels",30                "",31                "<yellow>Click to buy"),332            player -> new ConfirmMenu(shop, category, item).open(player));33    }34 435    button(BACK_SLOT, Icons.button(Material.ARROW, "<yellow>Back", "<gray>Return to the categories"),36        player -> new CategoryMenu(shop).open(player));37    icon(LEVELS_SLOT, Icons.button(Material.EXPERIENCE_BOTTLE, "<green>Your levels: <white>" + viewer.getLevel()));38    fillEmpty();39}

Step 6: build the confirm screen and the purchase

The confirm screen shows the item once more, the price, and two big buttons. Its purchase method runs when the player presses Buy:

24@Override25protected void render(Player viewer) {126    icon(GOODS_SLOT, Icons.display(item, "<gray>Price: <yellow>" + item.price() + " levels"));27 228    button(BUY_SLOT, Icons.button(Material.LIME_CONCRETE, "<green><bold>Buy",29            "<gray>Pay <yellow>" + item.price() + " levels",30            "<gray>You have <white>" + viewer.getLevel() + " levels"),331        this::purchase);32 433    button(CANCEL_SLOT, Icons.button(Material.RED_CONCRETE, "<red><bold>Cancel", "<gray>Go back without buying"),34        player -> new ItemsMenu(shop, category).open(player));35 36    fillEmpty();37}

39private void purchase(Player player) {140    PurchaseResult result = shop.buy(player, item);241    shop.tell(player, item, result);342    Sound sound = result == PurchaseResult.BOUGHT ? Sound.ENTITY_EXPERIENCE_ORB_PICKUP : Sound.ENTITY_VILLAGER_NO;43    player.playSound(player, sound, 1.0f, 1.0f);444    new ItemsMenu(shop, category).open(player);45}

The result type is a three-value enum. Using an enum instead of true and false lets one method report why something failed:

1package com.example.projectshopgui;2 3public enum PurchaseResult {14    BOUGHT,25    NOT_ENOUGH_LEVELS,36    INVENTORY_FULL7}

Now the heart of the shop, the buy method. The order of the lines is the whole trick: check everything first, change things last. If we took the levels before checking for room, a player with a full backpack would lose levels and get nothing.

42public PurchaseResult buy(Player player, ShopItem item) {143    if (player.getLevel() < item.price()) {44        return PurchaseResult.NOT_ENOUGH_LEVELS;45    }246    ItemStack goods = Icons.goods(item);347    if (!hasRoomFor(player.getInventory(), goods)) {48        return PurchaseResult.INVENTORY_FULL;49    }450    player.setLevel(player.getLevel() - item.price());551    player.getInventory().addItem(goods);52    return PurchaseResult.BOUGHT;53}

You might ask: why not just call addItem and look at what comes back? addItem returns the items that did not fit, but by then some of the stack is already in the backpack. Undoing a half-delivered purchase is harder than checking first. So we count the room ourselves:

68private static boolean hasRoomFor(PlayerInventory inventory, ItemStack goods) {69    int room = 0;170    for (ItemStack slot : inventory.getStorageContents()) {271        if (slot == null || slot.isEmpty()) {72            room += goods.getMaxStackSize();373        } else if (slot.isSimilar(goods)) {474            room += Math.max(0, slot.getMaxStackSize() - slot.getAmount());75        }76    }577    return room >= goods.getAmount();78}

The messages come from the config. The tell method chooses the right one with a switch over the enum:

55public void tell(Player player, ShopItem item, PurchaseResult result) {156    switch (result) {57        case BOUGHT -> send(player, "bought",258            Placeholder.unparsed("amount", String.valueOf(item.amount())),359            Placeholder.component("item", Icons.nameOf(item)),60            Placeholder.unparsed("price", String.valueOf(item.price())));61        case NOT_ENOUGH_LEVELS -> send(player, "not-enough-levels",62            Placeholder.unparsed("price", String.valueOf(item.price())),63            Placeholder.unparsed("have", String.valueOf(player.getLevel())));64        case INVENTORY_FULL -> send(player, "inventory-full");65    }66}

Step 7: add /shop and register everything

The command is a BasicCommand, the simple kind from Commands, part 1. It opens the first screen, and an admin can add the word reload to re-read the config:

19@Override20public void execute(CommandSourceStack source, String[] args) {21    CommandSender sender = source.getSender();122    if (args.length > 0 && args[0].equalsIgnoreCase("reload")) {23        reload(sender);24        return;25    }226    if (!(source.getExecutor() instanceof Player player)) {27        sender.sendRichMessage("<red>Only players can open the shop.");28        return;29    }330    new CategoryMenu(shop).open(player);31}

33private void reload(CommandSender sender) {134    if (!sender.hasPermission("shopgui.reload")) {35        sender.sendRichMessage("<red>You may not reload the shop.");36        return;37    }238    shop.reload();39    shop.send(sender, "reloaded",340        Placeholder.unparsed("categories", String.valueOf(shop.catalog().categories().size())),41        Placeholder.unparsed("items", String.valueOf(shop.catalog().itemCount())));42}

And the main class ties the pieces together. It is short, because every class has just one job:

1package com.example.projectshopgui;2 3import org.bukkit.plugin.java.JavaPlugin;4 5public final class ShopPlugin extends JavaPlugin {6 7    @Override8    public void onEnable() {19        saveDefaultConfig();210        Shop shop = new Shop(this);311        getServer().getPluginManager().registerEvents(new MenuListener(), this);412        registerCommand("shop", "Open the shop", new ShopCommand(shop));513        getLogger().info("Shop ready: " + shop.catalog().categories().size() + " categories, " + shop.catalog().itemCount() + " items.");14    }15}

You can download the finished project and compare it with yours.

Testing checklist

Build the plugin and start the test server (see Build and run). Look at the console first: you should see a line like this.

[14:02:11 INFO]: [ShopGui] Enabling ShopGui v1.0.0[14:02:11 INFO]: [ShopGui] Shop ready: 3 categories, 10 items.

Then join the server and go through these checks in order:

• Run /shop. You see three categories and the level display. Click Close.
• Give yourself levels with /xp add @s 10 levels, open /shop again and check that the bottle shows 10.
• Open a category, click an item, then click Cancel. You come back to the item list and nothing was paid.
• Buy an item. The levels go down by the price, the items arrive and the chat message names them.
• Spend all your levels, then try to buy something you cannot afford. You see the red message and keep your levels.
• Fill your backpack with /give @s dirt 2304 (36 full stacks), then buy anything. You get the "no room" message and keep your levels. Empty some slots and buy again.
• Try to steal: left-click, right-click, shift-click, press the number keys, drag across the slots and double-click on icons. Nothing may leave the menu, and nothing from your backpack may enter it.
• Switch to creative with /gamemode creative and try to pick up an icon. It stays in place.
• Edit a price in config.yml, run /shop reload and open the shop again. The new price is shown and the console line did not complain.
• Write a mistake on purpose, such as material: DIAMONDD, and reload. That one item disappears and the console says Item 'food.steak' has a missing or unknown material (with your own names). The rest of the shop still works.
• Take away operator status with deop YourName. /shop still works, but /shop reload says you may not.

Sidebar: using real money with Vault

Many servers already have an economy plugin that gives every player a money balance. Vault is a small plugin that sits between economy plugins and the plugins that want to charge money, so your plugin can say "take 50 coins from this player" without knowing which economy plugin is installed.

Switching this shop to Vault touches exactly three places, and the first is plugin.yml. A soft dependency tells Paper to load Vault before your plugin when it is installed:

11softdepend: [Vault]

• The payment. Shop.buy would ask Vault for the player's balance and take money instead of levels. The "check first, change last" order stays the same.
• The texts. The words "levels" in the lore and in the config messages become your currency name.
• The balance icon. The experience bottle would show the player's money.

This page does not contain compiled Vault code, because Vault's classes are not part of the Paper API, and adding another plugin's API to a project needs extra build setup. Working with other plugins shows how to do that step by step, including the crash to avoid when the other plugin is missing.

Mistakes to avoid

• Canceling only left clicks. Right clicks, shift-clicks, number keys, drags and double-clicks are all different ways to move items. Cancel the whole event, as MenuListener does.
• Checking for the menu by its title. Titles can be changed or copied by other plugins, and a player can rename a chest in an anvil. Use a holder, as Menu does.
• Taking the payment before the checks. The order is: check the price, check the room, then charge. Anything else loses players' levels in bad moments.
• Handing out the icon. The icon has extra lore and may share state with the menu. Always give a freshly built stack of the real goods.
• Trusting the config. A bad material name should skip one item, not crash the plugin. A negative price should never reach buy.
• Forgetting saveDefaultConfig(). Without it there is no config.yml on a fresh server, and the shop is empty.
• More than 27 items in a category. They would overwrite the Back button's row. The loader limits the count and warns.
• Forgetting to register the listener. The menu looks fine, but players can walk away with the icons.

Exercises

1redstone:2  icon: REDSTONE3  name: "<red>Redstone"4  items:5    redstone-dust:6      material: REDSTONE7      amount: 168      price: 29    pistons:10      material: PISTON11      amount: 212      price: 313    repeaters:14      material: REPEATER15      amount: 416      price: 3

21@Override22protected void render(Player viewer) {23    List<ShopItem> items = category.items();24    for (int slot = 0; slot < items.size(); slot++) {25        ShopItem item = items.get(slot);126        int missing = item.price() - viewer.getLevel();27        if (missing > 0) {228            icon(slot, Icons.display(item,29                "<gray>Amount: <white>" + item.amount(),30                "<gray>Price: <yellow>" + item.price() + " levels",31                "",32                "<red>You need " + missing + " more levels"));333            continue;34        }35        button(slot,36            Icons.display(item,37                "<gray>Amount: <white>" + item.amount(),38                "<gray>Price: <yellow>" + item.price() + " levels",39                "",40                "<yellow>Click to buy"),41            player -> new ConfirmMenu(shop, category, item).open(player));42    }43 44    button(BACK_SLOT, Icons.button(Material.ARROW, "<yellow>Back", "<gray>Return to the categories"),45        player -> new CategoryMenu(shop).open(player));46    icon(LEVELS_SLOT, Icons.button(Material.EXPERIENCE_BOTTLE, "<green>Your levels: <white>" + viewer.getLevel()));47    fillEmpty();48}

Extension ideas

• Selling. Add a second screen where players sell items for levels. Remember the same rule: check first, change last.
• Buy more than one. Let a shift-click on Buy purchase five times. The price check needs to multiply.
• Pages. Replace the 27-item limit with Previous and Next buttons, as in the paged menu of Chest menus.
• Per-item permissions. Add an optional permission: to each item and hide the items a player may not buy. See Permissions.
• A purchase log. Write every sale to a file in a background task, so the owner can see what sells.
• Sale prices. Add a sale-until time in the config and show a discount in the lore.
• Sounds and particles. Play a louder sound for expensive items. See Effects, particles and sounds.

The next project, Live sidebar scoreboard, shows live information on the right side of the screen and updates it every second.

Recap

• A shop is a chain of chest screens. Each screen is a Menu, an InventoryHolder that remembers what each slot does.
• Read the config once into records, and check every value. Skip bad entries and warn, instead of crashing.
• The listener cancels every click and every drag in a shop window. That one rule stops all item theft.
• Show an icon that looks like the goods, but give the player a freshly built stack of the real goods.
• In a purchase, check everything first (levels, then room) and change things last.
• Use an enum for the result, so one method can say why a purchase failed.
• Keep the payment in one method, so you can change the currency later without touching the screens.

Quick quiz

Next steps

• Project: Live sidebar scoreboard: show live stats that update every second.
• Chest menus: paged menus and more ways to build screens.
• Working with other plugins: add Vault or another plugin's API the safe way.
• Practice Arena: challenges for menus, inventories and configs.