GUI Layouts

Files: config/frontier/guis/*.conf

Frontier’s GUIs are built on Ceremony’s ConfigGui system. Each GUI is defined in a HOCON config file that controls layout, items, actions, and pagination. All GUI files can be customized and hot-reloaded with /ranked reload.

GUI Files

File	GUI ID	Purpose
`hub.conf`	`frontier:hub`	Main lobby — ladders, stats, season info.
`ladder_dashboard.conf`	`frontier:ladder_dashboard`	Ladder details, player stats, queue controls.
`leaderboard.conf`	`frontier:leaderboard`	Top-ranked players on a ladder.
`rewards.conf`	`frontier:rewards`	Milestones and season rewards.
`rules.conf`	`frontier:rules`	Format clauses and bans.
`team_preview.conf`	`frontier:team_preview`	Team selection and opponent preview before battle.
`challenge_invite.conf`	`frontier:challenge_invite`	Accept/decline incoming challenge.

GUI Structure

Every .conf file follows this structure:

id = "frontier:gui_name"
title = "<!italic><gradient:#FFD700:#FFA500>Display Title</gradient>"
rows = 6
open-sound = "minecraft:block.chest.open"

state {
    variable_name = "default_value"
}

watchers {
    "variable_name" = [{type = "refresh"}]
}

areas = [
    { ... }
]

slots {
    slot_id { ... }
}

Field	Type	Description
`id`	String	Unique GUI identifier (e.g., `"frontier:hub"`).
`title`	String	Window title, supports MiniMessage formatting.
`rows`	Int	Chest rows (1-6).
`open-sound`	String?	Sound played when the GUI opens.

Slots

Individual item slots at specific row/column positions. Each slot defines an item, optional visibility conditions, and click actions.

slots {
    join_queue {
        type = "button"
        row = 4
        col = 4
        visible = "!frontier:in_queue && !frontier:in_match"
        item {
            stack = {id: "minecraft:lime_dye"}
            name = "<!italic><green><bold>Join Queue</bold></green>"
            lore = [
                "<!italic><gray>Queue for a ranked match."
                "<!italic><yellow>Click to join!"
            ]
        }
        actions {
            left = [{type = "frontier:join_queue", value = "{state:ladder_id}", sound = "minecraft:block.note_block.chime"}]
        }
    }
}

Slot Fields

Field	Type	Description
`type`	String	Slot type. Usually `"button"`.
`row`	Int	Row position (0-based from top).
`col`	Int	Column position (0-based from left, 0-8).
`visible`	String?	Visibility condition. Omit = always visible.
`item.stack`	Object	Minecraft item: `{id: "minecraft:diamond"}`.
`item.name`	String	Display name, MiniMessage format.
`item.lore`	List<String>	Lore lines, MiniMessage format.
`actions`	Object	Click handlers keyed by button (`left`, `right`).

Areas

Rectangular regions that can be filled with a repeating item or paginated data. Areas are defined in a list and rendered in order (later areas overlay earlier ones).

Fill Areas

Fill a region with a static item — useful for backgrounds and dividers:

areas = [
    {
        id = "bg"
        rows = [0, 1, 2, 3, 4, 5]
        cols = [0, 1, 2, 3, 4, 5, 6, 7, 8]
        fill {
            stack = {id: "minecraft:black_stained_glass_pane"}
            name = " "
        }
    }
]

Pagination Areas

Display dynamic data from a data source with automatic paging:

areas = [
    {
        id = "ladder_grid"
        rows = [2, 3]
        cols = [1, 2, 3, 4, 5, 6, 7]
        pagination {
            source = "frontier:active_ladders"
            item-template {
                type = "frontier:data_icon_button"
                item {
                    stack = {id: "cobblemon:poke_ball"}
                    name = "<!italic><gold>{data:name}</gold>"
                    lore = [
                        "<!italic><gray>{data:description}"
                        "<!italic><gray>Format: <white>{data:format}"
                        "<!italic><yellow>Click to view"
                    ]
                }
                actions {
                    left = [{type = "frontier:open_ladder", value = "{data:id}"}]
                }
            }
        }
    }
]

The frontier:data_icon_button widget type swaps the item’s visual appearance based on data while preserving the template’s name and lore.

State Variables

State variables persist within the GUI session. They track context like which ladder is being viewed.

state {
    ladder_id = ""
    ladder_name = ""
}

Access state values in text with {state:variable_name}:

name = "<!italic><gold>{state:ladder_name}</gold>"

Watchers

Trigger actions when state variables change:

watchers {
    "ladder_id" = [{type = "refresh"}]
}

When ladder_id changes, the GUI refreshes to reflect the new ladder’s data.

Visibility Conditions

Control when slots are shown or hidden. Conditions can be combined with && (and), || (or), and ! (not):

visible = "frontier:in_queue"                     # Show only when in queue
visible = "!frontier:in_queue && !frontier:in_match"  # Show when idle
visible = "frontier:has_challenge"                # Show when challenge pending
visible = "frontier:in_match && !frontier:in_queue"   # Show when in match

Page-based visibility uses MoLang expressions:

visible = "molang:query.page('ladder_grid') < query.page_count('ladder_grid') - 1"
visible = "molang:query.page('ladder_grid') > 0"

Data Placeholders

Pagination templates use {data:field} to insert values from data providers.

Ladder Data

{data:id}, {data:name}, {data:description}, {data:format}, {data:battle_type}, {data:team_size}

Leaderboard Data

{data:position}, {data:name}, {data:rating}, {data:rank}, {data:wins}, {data:losses}, {data:winrate}

Team Preview Data

{data:name}, {data:level}, {data:ability}, {data:nature}, {data:types_line}, {data:move1} through {data:move4}, {data:iv_total}, {data:ev_total}, {data:iv_line1}, {data:iv_line2}, {data:ev_line1}, {data:ev_line2}, {data:gender}, {data:shiny}, {data:primary_hue}, {data:order_label}, {data:select_hint}, {data:index}

Reward Data

{data:name}, {data:progress}, {data:description}, {data:rewards}

Player Data (Slots)

{frontier_rating}, {frontier_rank}, {frontier_wins}, {frontier_losses}, {frontier_winrate}, {frontier_streak}, {frontier_season_name}, {frontier_season_end}, {frontier_season_remaining}, {frontier_queue_ladder}, {frontier_queue_size}, {frontier_challenges_status}, {frontier_ladder_level_cap}, {frontier_ladder_pick_count}

Action Types

Action	Description
`frontier:join_queue`	Join a ladder queue (value = ladder ID).
`frontier:leave_queue`	Leave the current queue.
`frontier:open_ladder`	Open the ladder dashboard (value = ladder ID).
`frontier:open_leaderboard`	Open the leaderboard (value = ladder ID).
`frontier:open_rewards`	Open the rewards GUI (value = ladder ID).
`frontier:open_rules`	View format rules (value = ladder ID).
`frontier:accept_challenge`	Accept a pending challenge.
`frontier:decline_challenge`	Decline a pending challenge.
`frontier:select_pokemon`	Select a Pokemon in team preview (value = index).
`frontier:confirm_preview`	Confirm team selection.
`frontier:surrender`	Forfeit the current match.
`frontier:toggle_challenges`	Toggle challenge invitations on/off.
`frontier:handle_preview_close`	Handle closing the preview (with optional delay).
`open_gui`	Open a GUI by ID (value = GUI ID).
`page_next`	Next page in pagination (value = area ID).
`page_prev`	Previous page in pagination (value = area ID).
`close`	Close the GUI.
`refresh`	Refresh the GUI display.

Actions can include a sound field to play a sound on click:

actions {
    left = [{type = "frontier:join_queue", value = "{data:id}", sound = "minecraft:block.note_block.chime"}]
}

Customization Tips

Background areas should use stained glass panes with name = " " for clean layouts.
Use <dark_gray> box-drawing characters (like the ones in the default configs) to create visual structure in lore text.
The on-close field at the GUI root level runs actions when the GUI is closed — the team preview uses this to handle disconnects.
All text fields support the same MiniMessage formatting as messages.conf.