GUI System

Journey’s GUI system allows full customization of all in-game menus through JSON configuration files. Customize layouts, widgets, colors, items, and actions for journals, parties, bounty boards, and more.

Overview

The GUI system provides:

JSON Configuration - Define GUIs with simple JSON files
Widget System - Flexible components (buttons, lists, displays)
Placeholder Support - Dynamic text and values
Action System - Button actions (commands, close, open other GUIs)
Server-Sync - Automatically distributed to all clients
Custom Model Data - Support for resource pack custom items

Configuration Location

Path: assets/journey/guis/ (server-side)

All GUI files are synced from server to clients automatically.

Available GUIs

File	GUI	Description
`journal.json`	Task Journal	Quest/task list and tracking
`task_detail.json`	Task Details	Detailed task information
`party.json`	Party Menu	Party management and members
`party_create.json`	Party Creator	Create new party dialog
`party_invites.json`	Party Invites	View pending invitations
`bounty_board.json`	Bounty Board	Available bounty tasks
`backpack.json`	Quest Backpack	Quest item storage
`levelable.json`	Levelable XP	XP and level progression
`team_select.json`	Team Selection	Pokémon team selector

GUI Structure

All GUI files follow the same basic structure:

{
  "gui_id": "unique_id",
  "title": "<gold>GUI Title",
  "size": "9x6",
  "placeholders": {},
  "widgets": []
}

Root Fields

Field	Type	Description
`gui_id`	String	Unique identifier for this GUI
`title`	String	GUI title (supports MiniMessage formatting and placeholders)
`size`	String	GUI dimensions: `9x1` to `9x6` (chest inventory sizes)
`placeholders`	Object	Custom placeholder definitions
`widgets`	Array	List of GUI widgets (components)

Size Options

Journey GUIs use chest inventory sizes:

9x1 - 9 slots (1 row)
9x2 - 18 slots (2 rows)
9x3 - 27 slots (3 rows)
9x4 - 36 slots (4 rows)
9x5 - 45 slots (5 rows)
9x6 - 54 slots (6 rows - default)

Placeholders

GUIs support dynamic placeholders in titles, names, and lore.

Built-in Placeholders

Task/Journal

{task_name} - Task display name
{task_description} - Task description
{objectives} - Formatted objective list
{progress} - Current progress
{target} - Target amount

Party

{party_name} - Party name
{party_leader} - Leader name
{party_size} - Current member count
{party_max} - Maximum members
{party_created} - Creation date
{party_visibility} - Public/Private status
{member_name} - Member name
{member_server} - Member’s server
{member_role} - Member’s role

Bounty Board

{board_name} - Board name
{board_description} - Board description
{available_tasks} - Available task count
{max_tasks} - Maximum tasks

Backpack

{backpack_size} - Items in backpack
{backpack_max} - Maximum capacity

{prev_page} - Previous page number
{next_page} - Next page number
{current_page} - Current page number
{max_pages} - Total pages

Custom Placeholders

Define custom placeholders in the placeholders object:

{
  "placeholders": {
    "custom_text": {
      "type": "custom",
      "value": "Default Value"
    },
    "player_level": {
      "type": "levelable",
      "levelable": "trainer_rank"
    }
  }
}

Widgets are GUI components that provide functionality.

Static display item with no interaction.

{
  "id": "info_display",
  "type": "display",
  "position": {"x": 4, "y": 0},
  "enabled": true,
  "item": "minecraft:paper",
  "customModelData": 0,
  "name": "<gold>Information",
  "lore": [
    "<gray>This is a display item",
    "<yellow>It shows information"
  ],
  "glow": false,
  "count": 1
}

Fields:

id - Unique widget identifier
type - Must be "display"
position - Slot position (x: 0-8, y: 0-5)
enabled - Whether widget is active
item - Item ID for display
customModelData - Custom model data (resource packs)
name - Item name (supports formatting and placeholders)
lore - Item lore lines (array)
glow - Whether item has enchant glow
count - Item stack count (1-64)

Clickable button that performs an action.

{
  "id": "close_button",
  "type": "button",
  "position": {"x": 4, "y": 5},
  "enabled": true,
  "item": "minecraft:barrier",
  "customModelData": 0,
  "name": "<red>Close",
  "lore": ["<gray>Click to close"],
  "action": {
    "type": "close"
  },
  "glow": false
}

Action Types:

Type	Description	Value Field
`close`	Close the GUI	None
`command`	Run a command	`"value": "/command"`
`open_gui`	Open another GUI	`"value": "gui_id"`
`next_page`	Go to next page	None
`previous_page`	Go to previous page	None
`toggle_setting`	Toggle a boolean setting	`"setting": "key"`
`open_party_invites`	Open party invites	None
`open_player_invite`	Open player invite dialog	None

Examples:

Close Button:

{
  "action": {
    "type": "close"
  }
}

Command Button:

{
  "action": {
    "type": "command",
    "value": "/party leave"
  }
}

Open GUI Button:

{
  "action": {
    "type": "open_gui",
    "value": "party_invites"
  }
}

Toggle Setting:

{
  "action": {
    "type": "toggle_setting",
    "setting": "show_completed"
  }
}

Displays paginated list of tasks.

{
  "id": "task_list",
  "type": "task_list",
  "position": {"x": 1, "y": 1},
  "enabled": true,
  "size": {
    "width": 7,
    "height": 4
  },
  "itemsPerPage": 28,
  "taskFormat": {
    "active": {
      "item": "minecraft:paper",
      "customModelData": 0,
      "nameFormat": "<yellow>{task_name}",
      "loreFormat": [
        "<gray>{task_description}",
        "",
        "{objectives}",
        "",
        "<green>Click to view details"
      ],
      "glow": false
    },
    "completed": {
      "item": "minecraft:writable_book",
      "customModelData": 0,
      "nameFormat": "<green>{task_name} <dark_gray>(Completed)",
      "loreFormat": [
        "<gray>{task_description}",
        "",
        "{objectives}",
        "",
        "<gray>Completed"
      ],
      "glow": true
    },
    "available": {
      "item": "minecraft:map",
      "customModelData": 0,
      "nameFormat": "<gray>{task_name}",
      "loreFormat": [
        "<gray>{task_description}",
        "",
        "<red>Not started"
      ],
      "glow": false
    }
  },
  "objectiveFormat": {
    "completed": "  <gray><strikethrough>{objective_name}",
    "active": "  <gold>▸ <blue>{objective_name}",
    "locked": "  <dark_gray>▸ {objective_name}"
  }
}

Fields:

size - Widget dimensions (width × height in slots)
itemsPerPage - Max items to show per page
taskFormat - Item format for different task states
objectiveFormat - Format for objective lines

Task States:

active - Currently active/in-progress tasks
completed - Finished tasks
available - Tasks player can start

Displays party members with different formatting.

{
  "id": "party_members",
  "type": "party_member_list",
  "position": {"x": 1, "y": 1},
  "enabled": true,
  "size": {
    "width": 7,
    "height": 3
  },
  "memberFormat": {
    "leader": {
      "item": "minecraft:golden_helmet",
      "customModelData": 0,
      "nameFormat": "<gold>★ {member_name} <yellow>(Leader)",
      "loreFormat": [
        "<gray>Role: <gold>{member_role}",
        "",
        "<yellow>Party Leader"
      ],
      "glow": true
    },
    "member": {
      "item": "minecraft:player_head",
      "customModelData": 0,
      "nameFormat": "<green>{member_name}",
      "loreFormat": [
        "<gray>Role: <white>{member_role}",
        "",
        "<green>Click for options"
      ],
      "glow": false
    },
    "offline": {
      "item": "minecraft:skeleton_skull",
      "customModelData": 0,
      "nameFormat": "<dark_gray>{member_name} <gray>(Offline)",
      "loreFormat": [
        "<gray>Offline"
      ],
      "glow": false
    }
  }
}

Member States:

leader - Party leader
member - Online members
offline - Offline members

Toggle switches for party configuration (leader only).

{
  "id": "party_settings",
  "type": "party_settings",
  "position": {"x": 0, "y": 0},
  "enabled": true,
  "leaderOnly": true,
  "settings": [
    {
      "id": "public_toggle",
      "settingKey": "isPublic",
      "position": {"x": 0, "y": 4},
      "enabled": {
        "item": "minecraft:lime_dye",
        "customModelData": 0,
        "name": "<green>Public Party",
        "lore": [
          "<gray>Anyone can join",
          "",
          "<yellow>Click to make private"
        ],
        "glow": false,
        "count": 1
      },
      "disabled": {
        "item": "minecraft:gray_dye",
        "customModelData": 0,
        "name": "<gray>Private Party",
        "lore": [
          "<gray>Invite only",
          "",
          "<yellow>Click to make public"
        ],
        "glow": false,
        "count": 1
      }
    }
  ]
}

Fields:

leaderOnly - Only party leader can interact
settings - Array of toggle configurations
settingKey - Setting to toggle (isPublic, allowInvites, etc.)
enabled - Item display when setting is ON
disabled - Item display when setting is OFF

Special widget for quest item storage.

{
  "id": "backpack_slots",
  "type": "backpack_slots",
  "position": {"x": 0, "y": 0},
  "enabled": true,
  "size": {
    "width": 9,
    "height": 6
  },
  "emptySlot": {
    "item": "minecraft:gray_stained_glass_pane",
    "customModelData": 0,
    "name": "",
    "lore": [],
    "glow": false,
    "count": 1
  }
}

Fields:

size - Backpack dimensions (slots)
emptySlot - Item to display in empty slots

Page navigation for multi-page GUIs.

{
  "id": "navigation",
  "type": "navigation",
  "position": {"x": 0, "y": 0},
  "enabled": true,
  "previous": {
    "position": {"x": 0, "y": 5},
    "item": "minecraft:arrow",
    "customModelData": 0,
    "name": "<yellow>← Previous Page",
    "lore": ["<gray>Page {prev_page}/{max_pages}"]
  },
  "next": {
    "position": {"x": 8, "y": 5},
    "item": "minecraft:arrow",
    "customModelData": 0,
    "name": "<yellow>Next Page →",
    "lore": ["<gray>Page {next_page}/{max_pages}"]
  },
  "hideWhenUnavailable": true
}

Fields:

previous - Previous page button configuration
next - Next page button configuration
hideWhenUnavailable - Hide buttons on first/last page

Specialized list for bounty board tasks.

{
  "id": "task_list",
  "type": "bounty_task_list",
  "position": {"x": 0, "y": 1},
  "enabled": true
}

Automatically displays available bounty tasks with proper formatting and click actions.

Complete Examples

Example 1: Simple Info GUI

{
  "gui_id": "server_info",
  "title": "<gold><bold>Server Information",
  "size": "9x3",
  "placeholders": {},
  "widgets": [
    {
      "id": "server_name",
      "type": "display",
      "position": {"x": 4, "y": 1},
      "enabled": true,
      "item": "minecraft:oak_sign",
      "customModelData": 0,
      "name": "<gold>My Pokémon Server",
      "lore": [
        "<gray>Version: 1.0.0",
        "<gray>Players: 50/100",
        "",
        "<yellow>Welcome!"
      ],
      "glow": true,
      "count": 1
    },
    {
      "id": "close_button",
      "type": "button",
      "position": {"x": 4, "y": 2},
      "enabled": true,
      "item": "minecraft:barrier",
      "customModelData": 0,
      "name": "<red>Close",
      "lore": [],
      "action": {
        "type": "close"
      },
      "glow": false
    }
  ]
}

Example 2: Custom Quest Board

{
  "gui_id": "custom_quest_board",
  "title": "<gradient:gold:yellow>Quest Board</gradient>",
  "size": "9x6",
  "placeholders": {
    "player_name": {
      "type": "player_name"
    }
  },
  "widgets": [
    {
      "id": "welcome_display",
      "type": "display",
      "position": {"x": 4, "y": 0},
      "enabled": true,
      "item": "minecraft:book",
      "customModelData": 0,
      "name": "<gold>Welcome, {player_name}!",
      "lore": [
        "<gray>Select a quest to begin",
        "<yellow>Complete quests for rewards"
      ],
      "glow": false,
      "count": 1
    },
    {
      "id": "daily_quests_button",
      "type": "button",
      "position": {"x": 2, "y": 2},
      "enabled": true,
      "item": "minecraft:clock",
      "customModelData": 0,
      "name": "<yellow>Daily Quests",
      "lore": [
        "<gray>Reset every 24 hours",
        "",
        "<green>Click to view"
      ],
      "action": {
        "type": "open_gui",
        "value": "daily_quests"
      },
      "glow": false
    },
    {
      "id": "weekly_quests_button",
      "type": "button",
      "position": {"x": 4, "y": 2},
      "enabled": true,
      "item": "minecraft:calendar",
      "customModelData": 0,
      "name": "<gold>Weekly Quests",
      "lore": [
        "<gray>Reset every week",
        "",
        "<green>Click to view"
      ],
      "action": {
        "type": "open_gui",
        "value": "weekly_quests"
      },
      "glow": false
    },
    {
      "id": "story_quests_button",
      "type": "button",
      "position": {"x": 6, "y": 2},
      "enabled": true,
      "item": "minecraft:written_book",
      "customModelData": 0,
      "name": "<green>Story Quests",
      "lore": [
        "<gray>Main storyline quests",
        "",
        "<green>Click to view"
      ],
      "action": {
        "type": "open_gui",
        "value": "story_quests"
      },
      "glow": true
    },
    {
      "id": "my_journal_button",
      "type": "button",
      "position": {"x": 0, "y": 5},
      "enabled": true,
      "item": "minecraft:writable_book",
      "customModelData": 0,
      "name": "<aqua>My Journal",
      "lore": [
        "<gray>View your active quests"
      ],
      "action": {
        "type": "command",
        "value": "/journey journal"
      },
      "glow": false
    },
    {
      "id": "close_button",
      "type": "button",
      "position": {"x": 8, "y": 5},
      "enabled": true,
      "item": "minecraft:barrier",
      "customModelData": 0,
      "name": "<red>Close",
      "lore": [],
      "action": {
        "type": "close"
      },
      "glow": false
    }
  ]
}

Best Practices

Layout Design

✅ Logical positioning - Place related items near each other

✅ Clear navigation - Navigation buttons in consistent locations (bottom row)

✅ Visual hierarchy - Important items in center, actions on edges

✅ Consistent spacing - Leave empty space for better readability

Item Selection

✅ Meaningful icons - Use items that represent their function

Close: minecraft:barrier
Info: minecraft:book, minecraft:paper
Settings: minecraft:comparator, minecraft:repeater
Navigation: minecraft:arrow
Confirm: minecraft:lime_dye, minecraft:green_wool
Cancel: minecraft:red_dye, minecraft:red_wool

✅ Custom model data - Use resource packs for custom textures

✅ Enchant glow - Highlight important items with "glow": true

Text Formatting

✅ Consistent colors - Use same colors for similar elements

Titles: <gold>, <yellow>
Actions: <green>
Info: <gray>, <blue>
Warnings: <yellow>
Errors: <red>

✅ Clear instructions - Tell players what clicking does

✅ Proper spacing - Use empty strings "" for blank lines in lore

Performance

✅ Optimize widget count - Fewer widgets = better performance

✅ Use appropriate sizes - Don’t use 9x6 if 9x3 suffices

✅ Efficient placeholders - Only use placeholders that are needed

Custom Model Data

Journey GUIs support custom model data for resource pack textures.

Using Custom Models

{
  "item": "minecraft:paper",
  "customModelData": 1001,
  "name": "<gold>Special Quest"
}

Resource Pack (assets/minecraft/models/item/paper.json):

{
  "parent": "item/generated",
  "textures": {
    "layer0": "item/paper"
  },
  "overrides": [
    {
      "predicate": {
        "custom_model_data": 1001
      },
      "model": "journey/quest_scroll"
    }
  ]
}

This allows unique custom textures for GUI items while maintaining compatibility.

Reloading GUIs

After editing GUI files, reload with:

/journey reload guis

Or restart the server to apply changes.

Messages Customization - Customize in-game messages
Client Configuration - Client display settings
Task System - Task configuration for journal
Party System - Party mechanics
Bounty Boards - Bounty board configuration

GUI System

GUI System

Overview

Configuration Location

Available GUIs

GUI Structure

Root Fields

Size Options

Placeholders

Built-in Placeholders

Task/Journal

Party

Bounty Board

Backpack

Navigation

Custom Placeholders

Widget Types

Display Widget

Button Widget

Task List Widget

Party Member List Widget

Party Settings Widget

Backpack Slots Widget

Navigation Widget

Bounty Task List Widget

Complete Examples

Example 1: Simple Info GUI

Example 2: Custom Quest Board

Best Practices

Layout Design

Item Selection

Text Formatting

Performance

Custom Model Data

Using Custom Models

Reloading GUIs

GUI System

GUI System

Overview

Configuration Location

Available GUIs

GUI Structure

Root Fields

Size Options

Placeholders

Built-in Placeholders

Task/Journal

Party

Bounty Board

Backpack

Navigation

Custom Placeholders

Widget Types

Display Widget

Button Widget

Task List Widget

Party Member List Widget

Party Settings Widget

Backpack Slots Widget

Navigation Widget

Bounty Task List Widget

Complete Examples

Example 1: Simple Info GUI

Example 2: Custom Quest Board

Best Practices

Layout Design

Item Selection

Text Formatting

Performance

Custom Model Data

Using Custom Models

Reloading GUIs

Related Documentation