CUSTOM GUI SYSTEM DOCUMENTATION

1. Introduction

This custom GUI system allows datapack creators to build interactive interfaces using JSON definitions and Lua scripting. GUIs can range from simple chest-like containers to complex custom interfaces with buttons, sliders, text boxes, and more.

Key Features:

• Two GUI types: Container (chest-like) and Custom (fully customizable)
• Rich element library: Buttons, sliders, progress bars, entities, text boxes, dropdowns, switches, checkboxes
• Lua scripting: Full logic support for dynamic behavior
• Persistence: Shared context across clicks
• Client-server synchronization: Automatic context management

2. GUI Types

Container GUI

Traditional chest-like inventory interfaces (9-54 slots). Best for item selection menus, shop interfaces, and simple button grids.

Custom GUI

Pixel-perfect custom interfaces with unlimited flexibility. Best for complex dashboards, settings panels, interactive displays, and mini-games.

3. File Structure

data/
└── your_namespace/
    └── triggerapi/
        └── gui/
            ├── my_gui.json          # GUI definition
            └── scripts/
                └── my_script.lua    # Lua scripts

Opening a GUI from Lua:

mc.player.openGui("your_namespace:my_gui")

4. Container GUIs

Container GUIs use a traditional chest inventory layout.

Basic Structure

{
  "type": "container",
  "title": "My Container",
  "size": 27,
  "background": {
    "item": "minecraft:gray_stained_glass_pane",
    "fill_empty": true
  },
  "container_buttons": [
    {
      "slot": 13,
      "item": "minecraft:diamond",
      "name": "§bClick Me!",
      "lore": [
        "§7This is a button",
        "§7Click to execute script"
      ],
      "glow": true,
      "script": "mc.player.sendMessage('Button clicked!')",
      "close_on_click": false
    }
  ]
}

Container Properties

Background Object

Container Button Definition

Script References

Scripts can be inline or file references:

Inline:

"script": "mc.player.sendMessage('Hello!')"

File reference (ends with .lua):

"script": "your_namespace:button_handler.lua"

File location: data/your_namespace/triggerapi/gui/scripts/button_handler.lua

5. Custom GUIs

Custom GUIs provide pixel-perfect control over layout and appearance.

Basic Structure

{
  "type": "custom",
  "title": "My Custom GUI",
  "width": 176,
  "height": 166,
  "background_texture": "your_namespace:textures/gui/my_background.png",
  "elements": [
    {
      "type": "button",
      "id": "my_button",
      "x": 10,
      "y": 20,
      "width": 100,
      "height": 20,
      "texture": "minecraft:textures/gui/widgets.png",
      "texture_x": 0,
      "texture_y": 66,
      "hover_texture_y": 86,
      "script": "mc.player.sendMessage('Custom button clicked!')"
    }
  ]
}

Custom GUI Properties

6. GUI Elements

All custom elements share base properties like id, x, y, width, and height.

Common Element Properties

1. Button

Interactive clickable button.

Script Context Variables: guiId, button (0=left, 1=right, 2=middle)

2. Text

Static or dynamic text display.

3. Image

Static image display.

4. Item

Display a Minecraft item.

5. Progress Bar

Displays progress as a fillable bar (updated via Lua every 50ms).

Progress Script Example:

-- Must return a value between 0.0 and 1.0
return mc.player.health / mc.player.maxHealth

6. Slider

Interactive slider for numeric input.

Script Context: ctx.value (current slider value as string)

7. Entity

Display a 3D rendered entity.

8. Text Box

Editable text input field.

Reading value: local username = ctx.username_input_value

9. Dropdown

Dropdown selection menu.

Script Context: ctx.value (selected option index as string)

10. Switch

Toggle switch (on/off).

Script Context: ctx.value ("true" or "false")

11. Checkbox

Checkbox with optional label.

Script Context: ctx.value ("true" or "false")

7. Lua Scripting

Available Lua Environment

When scripts execute, they have access to:

1. Standard Lua libraries: Base, Package, String, Table, Math
2. mc table: Minecraft game access (see Lua API documentation)
3. ctx table: Persistent context storage (shared across script calls)
4. util table: Utility functions

Context Variables

The ctx table persists data across button clicks and element interactions within the same GUI session.

Setting context values:

ctx.player_choice = "option_a"
ctx.counter = 5
ctx.has_completed = true

Reading context values:

if ctx.counter then
  ctx.counter = ctx.counter + 1
else
  ctx.counter = 1
end
mc.player.sendMessage("Count: " .. ctx.counter)

Pre-populated context variables:

• guiId: Current GUI resource location (string)
• Element-specific variables based on interaction type

Script Execution Flow

1. Container buttons: Execute when slot is clicked
2. Custom GUI buttons: Execute when clicked
3. Sliders: Execute on_change_script when value changes
4. Progress bars: Execute progress_script every 50ms to get current value
5. Text boxes: Execute on_text_change_script when text changes
6. Dropdowns: Execute on_select_script when selection changes
7. Switches/Checkboxes: Execute on_toggle_script when toggled

Common Lua Patterns

Opening another GUI:

mc.player.openGui("your_namespace:next_gui")

Closing current GUI:

mc.player.closeGui()

Giving items:

mc.player.giveItem("minecraft:diamond", 64)

Teleporting:

mc.player.teleport(100, 64, 200)

Broadcasting messages:

mc.util.broadcast("§6Server Announcement!")

Executing commands:

mc.util.executeCommand("time set day")

Multi-step workflow:

-- First button
if not ctx.step then
  ctx.step = 1
  mc.player.sendMessage("Step 1: Complete task A")
end

-- Second button
if ctx.step == 1 then
  ctx.step = 2
  mc.player.sendMessage("Step 2: Complete task B")
  mc.player.giveItem("minecraft:diamond", 1)
end

-- Third button
if ctx.step == 2 then
  mc.player.sendMessage("All steps complete!")
  mc.player.closeGui()
end

8. Context Management

Server-Side Context

For container GUIs, context is managed entirely on the server and persists across button clicks automatically.

Client-Server Synchronization

For custom GUIs, context is synchronized between client and server:

1. Server creates/retrieves context when GUI opens
2. Server sends SyncContextPacket to client with current context
3. Client updates element states and executes scripts
4. Client sends GuiStateUpdatePacket when elements change
5. Server executes scripts and updates shared context
6. Context is cleaned up when GUI closes

Context Lifecycle

9. Complete Examples

Example 1: Simple Shop (Container)

File: data/myshop/triggerapi/gui/weapon_shop.json

{
  "type": "container",
  "title": "§6Weapon Shop",
  "size": 27,
  "background": {
    "item": "minecraft:black_stained_glass_pane",
    "fill_empty": true
  },
  "container_buttons": [
    {
      "slot": 11,
      "item": "minecraft:wooden_sword",
      "name": "§fWooden Sword",
      "lore": ["§7Price: §e10 Gold", "§aClick to purchase"],
      "script": "myshop:buy_item.lua",
      "close_on_click": false
    },
    {
      "slot": 13,
      "item": "minecraft:iron_sword",
      "name": "§fIron Sword",
      "lore": ["§7Price: §e50 Gold", "§aClick to purchase"],
      "glow": true,
      "script": "myshop:buy_item.lua",
      "close_on_click": false
    },
    {
      "slot": 15,
      "item": "minecraft:diamond_sword",
      "name": "§bDiamond Sword",
      "lore": ["§7Price: §e200 Gold", "§aClick to purchase"],
      "glow": true,
      "script": "myshop:buy_item.lua",
      "close_on_click": false
    }
  ]
}

File: data/myshop/triggerapi/gui/scripts/buy_item.lua

-- Get item name from clicked slot
local items = {
  [11] = {name = "wooden_sword", price = 10},
  [13] = {name = "iron_sword", price = 50},
  [15] = {name = "diamond_sword", price = 200}
}

local item_data = items[tonumber(ctx.slot)]

if item_data then
  mc.player.giveItem("minecraft:" .. item_data.name, 1)
  mc.player.sendMessage("§aPurchased " .. item_data.name .. " for " .. item_data.price .. " gold!")
  mc.player.playSound("minecraft:entity.experience_orb.pickup", 1.0)
else
  mc.player.sendMessage("§cInvalid item!")
end

Example 2: Settings Panel (Custom)

File: data/mymod/triggerapi/gui/settings.json

{
  "type": "custom",
  "title": "§6Game Settings",
  "width": 200,
  "height": 180,
  "background_texture": "minecraft:textures/gui/demo_background.png",
  "elements": [
    {
      "type": "text",
      "id": "title",
      "x": 50,
      "y": 10,
      "width": 100,
      "height": 10,
      "text": "§l§6Settings",
      "color": 0xFFFFFF,
      "shadow": true,
      "scale": 1.5
    },
    {
      "type": "slider",
      "id": "volume_slider",
      "x": 70,
      "y": 30,
      "width": 100,
      "height": 10,
      "min_value": 0.0,
      "max_value": 100.0,
      "default_value": 50.0,
      "step": 5.0,
      "show_value": true,
      "on_change_script": "ctx.volume = ctx.value"
    },
    {
      "type": "checkbox",
      "id": "particles",
      "x": 10,
      "y": 90,
      "width": 16,
      "height": 16,
      "default_state": true,
      "label": "Enable Particles",
      "label_color": 0x404040,
      "on_toggle_script": "ctx.particles_enabled = ctx.value"
    },
    {
      "type": "button",
      "id": "save_button",
      "x": 50,
      "y": 150,
      "width": 100,
      "height": 20,
      "texture": "minecraft:textures/gui/widgets.png",
      "texture_x": 0,
      "texture_y": 66,
      "hover_texture_y": 86,
      "script": "mymod:save_settings.lua"
    }
  ]
}

Example 3: Player Stats Dashboard

Complete dashboard with progress bars showing health, food, and XP with auto-updating values every 50ms.

{
  "type": "custom",
  "title": "§bPlayer Statistics",
  "width": 220,
  "height": 200,
  "elements": [
    {
      "type": "progress_bar",
      "id": "health_bar",
      "x": 70,
      "y": 15,
      "width": 130,
      "height": 15,
      "bar_color": 0xFFFF0000,
      "background_color": 0xFF404040,
      "show_percentage": true,
      "progress_script": "return mc.player.health / mc.player.maxHealth"
    },
    {
      "type": "entity",
      "id": "player_model",
      "x": 80,
      "y": 120,
      "width": 60,
      "height": 80,
      "entity_type": "minecraft:player",
      "entity_scale": 25.0,
      "rotate_entity": true
    }
  ]
}

10. Best Practices

1. GUI Design

• Keep GUIs focused on a single purpose
• Use consistent color schemes (ARGB hex format: 0xAARRGGBB)
• Provide clear visual feedback for interactive elements
• Include tooltips for complex elements
• Test at different GUI scales

2. Scripting

• Keep scripts simple and focused
• Use context (ctx) for persistent data
• Validate user input before executing actions
• Provide clear error messages
• Use file references for complex scripts

3. Performance

• Minimize progress bar update frequency (already limited to 50ms)
• Avoid heavy computations in frequently-called scripts
• Cache values in context when possible
• Close GUIs when no longer needed

4. User Experience

• Show progress indicators for multi-step processes
• Confirm destructive actions
• Provide escape routes (close buttons)
• Use sounds for feedback
• Display helpful error messages

5. Debugging

• Use mc.util.print() to log to console
• Check server logs for script errors
• Test with multiple players for container GUIs
• Verify context persistence across interactions

11. Color Reference (ARGB Hex)

Common colors in 0xAARRGGBB format:

12. Troubleshooting

GUI doesn't appear

• Verify JSON syntax (use a validator)
• Check file location: data/namespace/triggerapi/gui/filename.json
• Ensure namespace matches your datapack
• Look for errors in server logs

Scripts don't execute

• Check script file exists: data/namespace/triggerapi/gui/scripts/filename.lua
• Verify script reference format (inline vs file)
• Check server logs for Lua errors
• Ensure script has correct syntax

Progress bars don't update

• Verify progress_script returns a number between 0.0 and 1.0
• Check script syntax
• Progress updates every 50ms automatically

Context not persisting

• Ensure you're setting values in ctx table
• Don't use reserved names (guiId, slot, button, clickType, value)
• Context is cleared when GUI closes

Elements misaligned

• Verify x, y, width, height values
• Check GUI dimensions (width, height)
• Remember: coordinates are pixels from top-left (0, 0)

Additional Resources

• Lua API Documentation: See Document 11 for complete mc table reference
• Minecraft Textures: minecraft:textures/gui/ for vanilla textures
• Color Codes: Use § followed by color code (0-9, a-f) for text formatting