GuiForge

GuiForge

Data-driven GUIs for Paper plugins. Design a menu visually, load it at runtime and bind click handlers by item key. Layouts are plain JSON, so designers and developers work on the same file.

Requires Paper 26.x. GuiForge uses Paper and Adventure APIs and does not run on Spigot.

Features

• Click handlers bound by item key. A typo in a key fails right away when the handler is bound, not in-game.
• Per-player items (balance, rank, owned state) with itemFor.
• Placeholders {token} in names, lore, titles and messages. Values are plain text, so players cannot inject formatting.
• Translations from YAML language files, with the client language per player and a fallback language.
• Paginated GUIs with setContents, onContentClick and page tokens such as {page} and {pages}.
• Connect GUIs via items.
• Import & Export aswell as templates.
• Actions: close, next-page, prev-page, open:, sound:, message:. Add your own prefixes with registerAction.
• Ready-made templates: shop, confirm dialog, category menu, admin toggles, auction listing.

Requirements

• JDK 25 to build
• Paper 26.x to run

Installation

Maven:

<dependency>
  <groupId>io.github.diego6k9</groupId>
  <artifactId>guiforge</artifactId>
  <version>0.3.0</version>
</dependency>

Quick example

A layout file, saved as src/main/resources/gui/shop-main.json:

{
  "formatVersion": 1,
  "id": "shop-main",
  "type": "chest",
  "rows": 3,
  "title": "<gradient:#ff66cc:#66ccff>Shop</gradient>",
  "items": [
    {
      "key": "filler",
      "slots": "border",
      "material": "minecraft:gray_stained_glass_pane",
      "name": " ",
      "locked": true,
      "hideTooltip": true
    },
    {
      "key": "confirm",
      "slots": [11],
      "material": "minecraft:lime_dye",
      "name": "<green><bold>Buy</bold></green>",
      "lore": ["<gray>Hello {player}, click to buy"],
      "locked": true
    },
    {
      "key": "cancel",
      "slots": [15],
      "material": "minecraft:red_dye",
      "name": "<red>Cancel</red>",
      "locked": true,
      "action": "close"
    }
  ]
}

The Java side loads the file, fills in the placeholder and binds the click handler:

GuiManager guis = new GuiManager(this);
Gui<Object> shop = guis.load("gui/shop-main.json");
 
// {player} in the lore is replaced with the name of the player who sees the menu
shop.placeholder("player", Player::getName);
 
// Runs when the item with key "confirm" is clicked
shop.onClick("confirm", ctx -> {
    ctx.player().sendMessage(Gui.text("<green>Bought!</green>"));
    ctx.player().closeInventory();
});
 
shop.open(player);

cancel needs no Java code. Its close action closes the menu when clicked. The full documentation for every feature is listed below under Documentation.

Visual editor

Layouts can be designed in the free browser editor: guiforge-editor.pages.dev. It needs no account and no install. Projects are saved in your browser, and you export them as JSON.

Documentation

• Format reference
• Placeholders and translations
• Paginated GUIs
• Actions
• Source and issues on GitHub

Support

GuiForge is free. If it saves you time, you can support development on GitHub Sponsors.