How to make a Minecraft GUI menu plugin

Step by step

1. 1.Sketch the menu

   A chest menu has 1 to 6 rows of 9 slots (9 to 54). Write which item goes in which slot, what each click does, and which slots are just decoration such as glass panes.

2. 2.Create the inventory with a holder

   Open it with Bukkit.createInventory(holder, size, title), using your own InventoryHolder class. The holder is how the plugin knows a click happened in its menu and not in a normal chest.

3. 3.Handle clicks

   In InventoryClickEvent, check the holder, cancel the event, then run the action for that slot. Close the menu or refresh it after the action.

4. 4.Block every other way to move items

   Cancel InventoryDragEvent too, and handle shift-clicks, number keys and clicks in the player's own inventory while the menu is open.

5. 5.Add pages if the list is long

   For warps or shop items that do not fit, reserve the bottom row for previous, next and close buttons.

6. 6.Open it from a command

   For example /warps, or from an item or NPC. Give the command a permission if the menu is not for everyone.

7. 7.Build and click through it

   Let Codexe compile the plugin, join the test server and click every button. Test players can open the menu and click slots for you too.

The rules that keep a menu safe

• Identify the menu by its holder, never by its title: titles can be copied by any renamed chest.
• Cancel the click before doing anything else, so an error in the action never leaves the item in the player's cursor.
• Cancel drags and shift-clicks from the player's inventory, or items can be pushed into the menu.
• Do not trust the item in the slot: look up the action by slot number or by a tag on the item.
• Run slow work (database reads, web requests) off the main thread and update the menu when it is done.

Menus from config

Server owners like to change menus without a new build. Ask for each menu to be defined in a config file, with the size, title and, per button, the slot, material, name, lore and action:

Example description

"A Paper 1.21.4 plugin called WarpMenu. /warps opens a 6-row menu with one button per warp, 45 per page, with previous, next and close buttons in the bottom row. Admins add warps with /setwarp <name> <material> and remove them with /delwarp. Clicking a warp teleports after a 3-second warmup that cancels on movement. Players cannot take or move any item in the menu. Warps saved in warps.yml, menu title, button names and messages in config.yml."

Testing menus with test players

Codexe's test players can open a menu and click a slot, then check that a menu opened, a message appeared or an item was given. Add a test in your own words, such as "a normal player runs /warps and clicks slot 0, and sees the teleport message", and it runs again every time Codexe delivers a change.

Questions