> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marioded.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize the catalog

> Customize the replay catalog, details screen, buttons, and navigation.

# Customize the catalog

**Edit:** the role's `gui.yml` · **Apply:** the role's reload command

This page is about the inventory screens players use to browse recordings: the **catalog** (the list) and the **details** screen (one recording). The lobby and standalone player use the same menu configuration model. Their Watch action differs: the lobby dispatches to another server; the standalone player starts local playback.

## Where to configure menus

Edit `catalog` and `details` in that role's `gui.yml`. There is no enclosing `gui:` key. The player creates this GUI only when availability is disabled at startup. Recorder does not have catalog menus.

Open the catalog with `/reverseplayer` (or `/reverseplayer gui`) or `/reverselobby gui`; `/reverseview` without an ID also opens it from the lobby. Use `/reverseplayer help` for the compact player guide; the lobby and recorder bare roots show their guides. When no replays are accessible to the viewer, the GUI stays closed and sends `gui-empty` from that role's `messages.yml` (`player.gui-empty` for player).

Each menu has:

| Field | Meaning |
| - | - |
| `title` | Inventory title, with MiniMessage formatting. |
| `layout` | Rows of nine characters; `x` marks paginated replay-card slots. |
| `items` | Map of named configured item definitions. |

The default catalog has six rows: five rows of replay cards and a navigation row. The default details menu has three rows, Information at slot 15, Watch at 11, and Back at 22.

> [!NOTE]
>
> **Menu slots start at 0.** The player hotbar uses slots 1–9 instead. Keep this difference in mind when copying a slot number between guides.

## Item fields

| Field | Meaning |
| - | - |
| `slot` | Fixed zero-based inventory slot; absent/null for the repeated entry item. |
| `entry` | Whether this is the catalog's repeated replay card. |
| `visible-in` | State names that must all be active. Empty means always visible. |
| `material` | Bukkit material name supported by the target server. |
| `amount` | Stack amount; defaults to 1. |
| `data` | Legacy item damage/data, default 0. |
| `name`, `lore` | MiniMessage display text. |
| `flags` | Item flag names, such as `HIDE_ATTRIBUTES`. |
| `action` | Namespaced action identifier; empty means no click action. |
| `parameters` | String key/value parameters for that action. |

Unknown/AIR item materials fall back to stone in the current menu item builder. Use the material names available on your actual server instead of relying on this fallback.

## Add a delete button

Merge an item under `details.items` in `gui.yml`:

```yaml theme={null}
details:
  items:
    delete:
      slot: 13
      entry: false
      visible-in: [ready]
      material: BARRIER
      amount: 1
      data: 0
      name: '<red>Delete recording'
      lore:
        - '<gray>Deletes the selected replay.'
      flags: []
      action: reverse:delete
      parameters: {}
```

The standard registry includes deletion, but the default details menu does not place a delete button. Slot 13 leaves the default Information item at 15 intact; choose another free slot if your menu is customized. This example invokes deletion directly; it does not add a separate confirmation dialog. Deletion still performs an authoritative catalog access check.

## Built-in actions

| Action | Effect |
| - | - |
| `reverse:close` | Closes the current menu. |
| `reverse:back` | Returns through menu navigation. |
| `reverse:details` | Opens details for the selected replay. |
| `reverse:page_previous` | Previous catalog page. |
| `reverse:page_next` | Next catalog page. |
| `reverse:watch` | Local playback or lobby dispatch, according to the owning plugin. |
| `reverse:delete` | Authorized deletion of the selected replay. |

Actions needing a replay belong on replay cards/details, not arbitrary catalog background items with no selection. Third-party plugins can register their own IDs using the [menu API](https://docs.marioded.com/api/ui-extensions.md).

## Visibility states

Catalog states include `loading`, `empty`, `ready`, `can-back`, and `can-advance`. Details use `loading`, `empty`, and `ready`.

The list is an **AND** condition. `[ready, can-advance]` requires both. `[loading, ready]` usually describes mutually exclusive states and is not “loading or ready.” Use separate items if you need alternative states.

Details fetch the selected replay's metadata asynchronously. The default Watch button appears when that lookup reaches `ready`; Information and Back have no visibility condition. An entirely blank details inventory, including those unconditional items, is a different symptom from a temporarily hidden Watch button. See [empty details troubleshooting](https://docs.marioded.com/owners/troubleshooting.md).

## Placeholders

| Placeholder | Value |
| - | - |
| `<name>` | Literal replay name, or a date-based fallback if unnamed. |
| `<description>` | Literal replay description. |
| `<id>` | Full replay UUID, used in commands and technical details. |
| `<date>` | Start time formatted in UTC. |
| `<duration>` | Recorded wall-clock duration as hours:minutes:seconds. |
| `<world>` | Terrain identifier, not necessarily a Bukkit world name. |
| `<owners>` | Comma-separated owner UUIDs. |
| `<page>` | Current displayed catalog page. |

Replay names/descriptions are inserted as literal data, not parsed as MiniMessage instructions. The default Watch item uses a plain instruction and the `reverse:watch` action; it does not need a separate status-text placeholder.

Catalogue cards emphasize name, date and duration; the details item includes the full UUID via `<id>`. Use that placeholder in custom action commands too. There is no short/full ID pair and no name-based lookup. Names and descriptions are inserted literally, including when they contain markup-shaped text.

## Reloading

Use `/reverselobby reload` or `/reverseplayer reload` after editing. Reopen a menu to inspect changes and to see fresh metadata. A malformed menu can reject configuration preparation; check the log rather than repeatedly deleting the configuration file.

## Next steps

* [Style the playback hotbar and HUD](https://docs.marioded.com/owners/display.md).
* [Register your own menu action](https://docs.marioded.com/api/ui-extensions.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.