Skip to content

Custom GUIs

natan307 edited this page Nov 16, 2026 · 1 revision

Custom GUIs

Inventory menus are defined in plugins/PackLoader/guis/*.yml. Open one with:

/packloader gui <id> [player]

Example

guis:
  example_menu:
    title: "&8Example menu"
    rows: 3
    background: "packloader:gui/example_menu"
    buttons:
      11:
        item: ruby_flat
        name: "&cTake a ruby"
        lore:
          - "&7Click to receive a ruby"
        commands:
          - "[give] ruby_flat"
          - "[message] &aYou received a ruby!"
      13:
        material: BARRIER
        name: "&cClose"
        commands:
          - "[close]"

GUI keys

Key Description
(section name) GUI id (a-z 0-9 _).
title Title text, supports colours.
rows 1 to 6.
background namespace:path of a PNG in a pack (assets/<ns>/textures/<path>.png). Optional.
offset_x, offset_y Shift the background in pixels.
hide_title true hides the title text.
buttons Map of slot number (0-based, left to right, top to bottom) to a button.

Button keys

Key Description
item A PackLoader item id (uses its model). Shows a barrier if the id does not exist.
material Vanilla material, used when item is not set.
name, lore Text with colour support. Overrides the item's own name / lore.
commands Actions run when the button is clicked.

Actions

Each entry in commands starts with an action tag:

Action Effect
[close] Close the GUI
[player] <command> Run a command as the player (no leading /)
[console] <command> Run a command as the console
[message] <text> Send a chat message (colours supported)
[open] <gui id> Open another GUI
[give] <item id> Give one PackLoader item

%player% is replaced with the player's name in commands. Items in a PackLoader GUI cannot be taken, moved or dragged.

Backgrounds

The background is a PNG drawn through the inventory title using a generated font (assets/<ns>/font/gui.json). This needs Paper (Adventure components). On Spigot the GUI still opens and the buttons work, but without the background.

Tips:

  • The image is drawn on top of the vanilla inventory. Make the areas where slots are transparent, otherwise items can be hidden behind the picture. The example texture does this.
  • A standard 3-row chest is about 176x168 pixels.
  • The image starts at the left edge of the inventory. Use offset_x / offset_y if it is misaligned.
  • Glyph characters are assigned automatically in load order, so no manual setup is needed.
  • Backgrounds are rendered by the client and look best at their original size. Very tall images may be clipped by the client.

Positioning is based on the vanilla inventory layout and has not been verified on every client version. Please report alignment problems with your Minecraft version.

Item browser

/packloader browser opens a paged list of all custom items. Click an item to take one, shift-click to take a full stack. It needs the packloader.admin permission.

Letting players open a GUI

/packloader gui needs packloader.admin. To let normal players open a menu, run the command from the console through another plugin, for example a custom command or an item-command plugin that executes as console:

packloader gui example_menu %player%

Clone this wiki locally