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: ```xml io.github.diego6k9 guiforge 0.3.0 ``` ## Quick example A layout file, saved as `src/main/resources/gui/shop-main.json`: ```json { "formatVersion": 1, "id": "shop-main", "type": "chest", "rows": 3, "title": "Shop", "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": "Buy", "lore": ["Hello {player}, click to buy"], "locked": true }, { "key": "cancel", "slots": [15], "material": "minecraft:red_dye", "name": "Cancel", "locked": true, "action": "close" } ] } ``` The Java side loads the file, fills in the placeholder and binds the click handler: ```java GuiManager guis = new GuiManager(this); Gui 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("Bought!")); 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](https://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](https://github.com/Diego6k9/GuiForge/blob/master/docs/format-v1.md) - [Placeholders and translations](https://github.com/Diego6k9/GuiForge/blob/master/docs/placeholders-and-translations.md) - [Paginated GUIs](https://github.com/Diego6k9/GuiForge/blob/master/docs/paginated-guis.md) - [Actions](https://github.com/Diego6k9/GuiForge/blob/master/docs/actions.md) - [Source and issues on GitHub](https://github.com/Diego6k9/GuiForge) ## Support GuiForge is free. If it saves you time, you can support development on [GitHub Sponsors](https://github.com/sponsors/Diego6k9).