GUI API — Fabric 1.21.8

A Fabric mod that lets datapacks define and open chest GUIs via JSON files.
No client mod required. No macros. No external dependencies beyond Fabric API.

Installation

1. Drop guiapi-1.0.4.jar into your mods/ folder.
2. Drop your datapack into world/datapacks/.
3. Run /reload or /guiapi reload.

Optionally install Mod Menu to see loaded GUIs and visually edit them in-game!

Commands

Command Description /guiapi Show help (same as /guiapi help) /guiapi open <id> Open a GUI for yourself /guiapi open <id> <targets> Open a GUI for target players /guiapi list List all loaded GUI definitions /guiapi reload Reload all datapack resources (including GUIs) /guiapi var get <player> <key> Get a player's runtime variable /guiapi var set <player> <key> <value> Set a player's runtime variable /guiapi var clear <player> Clear all runtime variables for a player /guiapi help Show command and JSON field reference in-game

Permission level 2 (OP) required by default (configurable in Mod Menu).

File Location

GUI definition files go in:

data/<namespace>/gui/<name>.json

The GUI ID used in commands is <namespace>:<name> — matching the file path under gui/.

JSON Schema

Top-level fields

Field Type Default Description title string "GUI" Inventory title. Supports § color codes and placeholders. rows int 1–6 3 Number of rows (9 slots each). tick_rate int 0 Auto-refresh interval in ticks (e.g., 20 = 1s). Set 0 to disable. close_on_move boolean false If true, closes screen if player walks away (> 1.5 blocks). filler object — Background filler configuration (see below). on_open action[] [] Actions executed when the GUI is opened. on_close action[] [] Actions executed when the GUI is closed (any reason). buttons button[] [] List of button definitions.

Filler fields

Any empty slot in the inventory is automatically populated with this background item.

"filler": { "item": "minecraft:gray_stained_glass_pane", "name": " ", "glint": false, "hide_tooltip": true }

Button fields

Field Type Default Description slot int 0 Zero-based slot index (0–rows*9-1). page int 0 Which page this button appears on. item string "minecraft:stone" Item ID. name string "" Display name. Supports color codes and placeholders. lore string[] [] Lore lines. Supports placeholders. glint boolean false Apply enchantment glint effect. amount string "1" Item stack count (supports placeholders like {var:counter}). hide_tooltip boolean false Hides item name and lore from hover tooltip. hide_additional_tooltip boolean false Hides attributes, enchantments, and clutter. custom_model_data int or object — Custom model data component (supports legacy int and 1.21.4+ composite object). item_model string — Custom item model component ID (1.21.2+). click_type string "any" Which click triggers actions: any · left · right · shift condition object — Visibility condition (see below). actions action[] [close] Actions executed in order on click. Supports "delay": int (ticks). toggle object — Toggle definition — replaces item/actions (see below).

Placeholders

Supported in title, button name, lore, message values, and run_command values.

Placeholder Resolves to {player} Player's display name {gui} GUI ID (namespace:name) {page} Current page index (0-based) {page1} Current page index (1-based) {pages} Total page count {score:objective} Player's score in the given scoreboard objective {var:key} Player's runtime variable key (empty string if unset)

Action types

Any action can be delayed by adding "delay": int (in ticks) to its JSON block.

Type value format run_with Description run_command Command string player · console Run a command. Default: player. Supports placeholders. close — — Close the GUI. refresh — — Refresh the current GUI inventory dynamically (no closing/flicker). open_gui namespace:name — Close and open another GUI. message Text string — Send a chat message to the player. Supports placeholders. action_bar Text string — Send an action bar message directly to the player. sound sound.id or sound.id:volume:pitch — Play a sound. Volume/pitch default to 1.0. Supports placeholders. set_score objective:value — Set player's scoreboard objective score directly (supports placeholders). add_score objective:value — Add score to player's scoreboard objective directly. sub_score objective:value — Subtract score from player's scoreboard objective directly. take_item itemId:amount — Deduct a specified amount of an item from the player's inventory. add_effect effect_id:duration:amplifier:particles — Give player status effect (duration in seconds, particles true/false). remove_effect effect_id — Remove a specific status effect from the player. clear_effects — — Clear all status effects from the player. set_var New value — Set a runtime variable. Requires "var": "key". add_var Integer to add — Add an integer to a runtime variable. Requires "var": "key". sub_var Integer to subtract — Subtract an integer from a runtime variable. Requires "var": "key". reset_var — — Delete a single runtime variable. Requires "var": "key". clear_vars — — Delete all runtime variables for this player. next_page — — Go to the next page. prev_page — — Go to the previous page. goto_page Page index (string) — Jump to a specific page.

Condition types

Conditions control button visibility. Hidden buttons cannot be clicked.

Type value format Visible when has_tag Tag name Player has the scoreboard tag not_tag Tag name Player does not have the scoreboard tag score_gt "objective:threshold" Player's score > threshold score_lt "objective:threshold" Player's score < threshold score_eq "objective:value" Player's score == value var_eq "key:value" Runtime variable key equals value (string compare) var_gt "key:value" Runtime variable key (int) > value var_lt "key:value" Runtime variable key (int) < value var_set key Runtime variable key is set (any value) has_item "itemId:amount" Player has at least amount of itemId in inventory not_item "itemId:amount" Player has less than amount of itemId in inventory level_gt value Player's XP level > value level_lt value Player's XP level < value health_gt value Player's current health > value health_lt value Player's current health < value food_gt value Player's hunger level > value food_lt value Player's hunger level < value

Toggle buttons

A toggle button shows different item/name/lore/actions depending on a scoreboard tag on the player. Replace the item and actions fields with a toggle object.

Field Type Default Description tag string "" Scoreboard tag that stores the on/off state. item_on / item_off string lime/gray dye Item shown in each state. name_on / name_off string §aEnabled / §7Disabled Display name in each state. lore_on / lore_off string[] [] Lore in each state. glint_on / glint_off boolean false Glint in each state. actions_on action[] [tag @s remove <tag>] Actions executed on click while ON (turning OFF). actions_off action[] [tag @s add <tag>] Actions executed on click while OFF (turning ON).

Toggle actions also fully support the multi-action engine (separated by ; in the visual editor).

Client-Side features (Optional)

Installing this mod on the client-side unlocks powerful, highly-polished user experience features:

1. In-Game GUI Editor

• Open the Mod Menu config screen to see a list of loaded GUIs.
• Click any GUI to open the GUI Editor Screen!
• Visually edit GUI title, rows, tick_rate, close_on_move, and background filler.
• Manage buttons list, add new buttons, and edit slot, item, amount, glint, lore (using ; split), multiple actions, and toggle properties.
• Click Apply & Back to open the Gui Save Loading Screen which finds the target datapack folder on the server, safely writes the JSON to disk, and reloads the API definitions. No edits are ever lost on rejoin!

2. Native Keybindings

Integrates natively with Minecraft's official controls menu (Options > Controls > Key Binds > GUI API):

• Accept Rules (Open GUI): Opens the default welcome GUI (Defaults to G).

Examples

Please refer to the updated example-datapack directory in the repository sources for highly-polished, fully-annotated examples demonstrating auto-refreshing clocks, direct scoreboard trading, status effect controllers, and custom visual models!

Building

chmod +x gradlew ./gradlew build # Output: build/libs/guiapi-1.0.4.jar

Requires Java 21.

License

MIT — see LICENSE.