> For the complete documentation index, see [llms.txt](https://docs.xandtech.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xandtech.fr/home/xtimerewards/features/menus.md). # Menus & GUI Customization Every menu XTimeRewards shows is defined in its own YAML file under `plugins/XTimeRewards/menus/`: title, size, decoration, items, and (for the dynamic ones) a paginated grid. All of them share the same field system, so once you know it, you can edit any of them. | File | Opened by | Purpose | | ------------------------ | ------------------------------------ | -------------------------------------------------- | | `playtime.yml` | `/xtimerewards` (no args) | Own playtime + embedded milestone browser | | `top.yml` | `/xtimerewards top` | Playtime leaderboard | | `streak.yml` | `/xtimerewards streak`, `/daily` | Own streak + reward-tier grid | | `streak-top.yml` | `/xtimerewards streaktop` | Streak leaderboard | | `afk-mode.yml` | Entering AFK mode | The persistent, mostly-uninteractive AFK-mode menu | | `afk-confirm.yml` | `/afk` | Confirmation step before entering AFK mode | | `admin-view.yml` | `/xtimerewards admin view ` | Per-player admin management | | `admin-view-streak.yml` | "Manage Streak" button | Per-player streak admin sub-menu | | `admin-view-history.yml` | "Reward History" button | Per-player reward-history log | | `admin-alts.yml` | `/xtimerewards admin alts` | Shared-IP group browser | | `admin-alts-detail.yml` | Clicking a group in `admin-alts.yml` | Accounts sharing one IP | ## Basic layout ```yaml title: "&8My Playtime" size: 54 fill: enabled: false material: GRAY_STAINED_GLASS_PANE name: " " custom: divider: slots: "9-17" material: BLACK_STAINED_GLASS_PANE name: " " items: - slot: 4 skull-self: true live: true close-on-click: false name: "{player}" lore: - "⏱ Total: {total}" ``` * `title` / `size` — MiniMessage (or legacy) text, and inventory size (must be a multiple of 9, up to 54). * `fill.enabled` + `fill.material`/`fill.name` — a uniform pane applied to every still-empty slot once everything else has been drawn. Off by default in the bundled templates (leftover gaps stay empty air). * `fill.custom.` — one or more **named slot groups**, each with its own pane, always applied regardless of `fill.enabled` — this is how the bundled templates draw their colored borders/dividers. ## Item fields | Field | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `slot` / `slots` | A single slot number, a list (`[1, 2, 3]`), or a range string (`"0-8,45-53"`). Same syntax everywhere a slot list is expected (grid ranges, fill groups, etc.). | | `material` | Bukkit `Material` name (`PLAYER_HEAD`, `NETHER_STAR`, `BARRIER`...). | | `skull-texture` | Base64 texture of a custom head (e.g. from minecraft-heads.com). Takes priority over `material` (forces `PLAYER_HEAD` with this texture). | | `skull-self` | `true` = shows the head of the player who opened the menu (or the managed player, in an admin menu). | | `live` | `true` = this item is re-rendered every `playtime-menu.refresh-seconds` (`config.yml`) — for a counter that ticks up in real time. | | `glow` | `true` = adds an enchant glow without showing an enchant. | | `name` / `lore` | MiniMessage (or legacy) text; `lore` is a list, one line each. | | `command` | Run **as the player** on click (not console) — e.g. to redirect to another XTimeRewards command. | | `close-on-click` | Closes the menu on click. Defaults to `true`; set `false` for anything purely decorative or that should stay open (a live counter head, a "manage streak" button, ...). | | `category` | Marks this item as a milestone-category tab instead of a plain button — one of `all`/`daily`/`weekly`/`monthly`/`yearly`/`total`. Active/locked-tab decoration is layered on automatically. | | `action` | A built-in behavior name specific to that menu (leave-afk, back, reset-all, streak-add-1, ...) rather than a plain command — see the comments at the top of each menu file for the exact list it recognizes. | ## Dynamic grids & pagination Menus with a variable-length list (milestones, leaderboard entries, reward history, alt-account groups) share one shape: a list of slots for the grid, plus previous/next page slots. ```yaml milestone-slots: "19-25,28-34,37-43" milestone-previous-page-slot: 45 milestone-next-page-slot: 53 milestone-progress-slot: 51 ``` ```yaml entry-slots: "19-25,28-34,37-43" previous-page-slot: 45 next-page-slot: 53 ``` How many entries show per page is simply however many slots you list — pagination kicks in automatically once there are more entries than fit on one page. `milestone-slots` (+ friends) backs the embedded milestone browser (`playtime.yml`, `streak.yml`, `admin-view.yml`); `entry-slots` (+ friends) backs leaderboard-style menus (`top.yml`, `streak-top.yml`, `admin-alts.yml`, `admin-alts-detail.yml`) and the reward-history log. ## Menu-specific extras | Field | Menu | Meaning | | ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `info-slot` | `playtime.yml`, `streak.yml` | Draws the purely-informational "rewards info" paper (`config.yml` `info-paper.playtime`/`info-paper.streak`) at this slot. `null`/omit to not show one. | | `freeze-slot` | `streak.yml` | Where the standalone "banked streak-freeze charges" item is drawn. | | `surprise-slots` | `afk-mode.yml` | Candidate slots the [surprise item](/home/xtimerewards/features/afk-mode.md#surprise-items) may randomly appear in — the one interactive slot in that menu besides leave. | ## Placeholders available in name/lore Vary by menu (see the comment block at the top of each file for the exact list), but generally include: `{player}`, `{daily}`/`{weekly}`/`{monthly}`/`{yearly}`/`{total}` (formatted time) and their `_seconds` raw equivalents, `{afk}`/`{afk_seconds}`, `{afk_session}`/`{afk_session_seconds}`, `{streak}`/`{longest}`/`{freezes}`, and `{elapsed}`/`{elapsed_formatted}` (AFK-mode session length). ## Sounds ```yaml sounds: enabled: true click: sound: UI_BUTTON_CLICK volume: 1.0 pitch: 1.0 claim-success: sound: ENTITY_PLAYER_LEVELUP claim-fail: sound: ENTITY_VILLAGER_NO milestone-locked: sound: ENTITY_VILLAGER_NO ``` Master switch plus one entry per event, each a standard `org.bukkit.Sound` name with volume/pitch. ## Reloading `/xtimerewards admin reload` reloads every menu file — no restart needed for a layout/text change. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xandtech.fr/home/xtimerewards/features/menus.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.