# Main menu configuration

> menu_main.yml configuration guide

The `menu_main.yml` file controls the **main quest menu** — the first screen players see when they run `/quests`. This menu is a grid of your quest pools; clicking a pool opens its own [Quest pool configuration](../../auroraquests/configuration/quest-pool-configuration.md) menu.

Here is the full default file:

```yaml
# Don't touch this
config-version: 0

title: "Quests"

menu-rows: 6
has-close-button: true

filler:
  enabled: true
  item:
    material: black_stained_glass_pane
    name: " "

# You can override the default items here
items: {}

# Define your custom menu items here
custom-items: {}
```

# Options

- `config-version` - Internal version number. **Don't touch this**, the plugin manages it.
- `title` - The inventory title shown at the top of the menu.
- `menu-rows` - How many rows (1–6) the chest menu should have. Each row is 9 slots.
- `has-close-button` - Whether to show a close button. The button's appearance is taken from the shared `close` item in [Common menu configuration](../../auroraquests/configuration/common-menu-configuration.md) (you can override it via `items` below).
- `filler` - If `enabled: true`, every empty slot is filled with the given `item`. See [Item config](../../aurora/item-config.md) for the item format.
- `items` - Override the shared menu items **for this menu only**. You don't need to copy the whole item — whatever you put here is merged on top of the default from `menu_common.yml`. The items used by the main menu are `close`, `previous-page`, `current-page` and `next-page`.
- `custom-items` - Add your own decorative or informational items. Keys must be unique. See [Item config](../../aurora/item-config.md).

# Where do the quest pool icons come from?

The main menu does **not** define the pool icons here. Each pool's icon, slot and page come from that pool's own `menu-item` section — see [Quest pool configuration](../../auroraquests/configuration/quest-pool-configuration.md). A pool only appears in this menu if its `menu-item.show-in-main-menu` is `true` (and the player has it unlocked, or it is set to always show).

# Pages

There is no page count to configure here. The number of pages is derived automatically from the highest `menu-item.page` value among your visible pools. If more than one page exists, the pagination items (`previous-page`, `current-page`, `next-page`) are shown; otherwise they are hidden.

# Placeholders

On a **pool icon** (configured in the pool's `menu-item.item`) you can use:

- `{name}` - The pool's name.
- `{total_completed}` - How many quests the player has completed in that pool.
- `{lb_position}` - The player's leaderboard position in that pool.
- `{lb_position_percent}` - The player's position as a top-% of the leaderboard.
- `{lb_size}` - The size of that pool's leaderboard.

On the **pagination items** you can use `{current}` (current page) and `{total}` (total pages).

:::callout{type="neutral"}
Locked pools that are set to always show in the menu will have their `menu-item.locked-lore` lines appended to the icon. Clicking a locked pool does nothing.
:::

# Example: a 3-row menu with a custom info item

```yaml
config-version: 0

title: "&8» &6Quests"
menu-rows: 3
has-close-button: true

filler:
  enabled: true
  item:
    material: gray_stained_glass_pane
    name: " "

items:
  # Move the close button to a different slot just for this menu
  close:
    slot: 22

custom-items:
  info:
    material: oak_sign
    slot: 4
    name: "&eHow quests work"
    lore:
      - "&7Pick a quest pool below and"
      - "&7start completing objectives!"
```