# Common menu configuration

> menu_common.yml configuration guide

The `menu_common.yml` file holds settings and items that are **shared across every menu** in the plugin (the main menu, each quest pool menu, and the level menus). Instead of repeating the same close button, pagination arrows, progress bar, etc. in every config, they are defined here once. Any individual menu can still override a shared item in its own `items:` section — see the note at the bottom.

Here is the full default file:

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

task-statuses:
  completed: "&a&l✔&r"
  not-completed: "&c&l✖&r"

display-components:
  rewards:
    title: "&7Rewards:&r"
    line: "  {reward}"

progress-bar:
  length: 10
  filled-character: "&a&l■"
  unfilled-character: "&7&l■"

# Optional fallback appearance for completed quests. Quest-specific
# completed-menu-item settings take priority over this item.
# completed-quest-item:
#   material: LIME_STAINED_GLASS_PANE
#   name: "&e{name} &a✔"

# You can override these items in other menu configurations
items:
  previous-page: { ... }
  next-page: { ... }
  current-page: { ... }
  close: { ... }
  back: { ... }
  switch-to-completed: { ... }
  switch-to-active: { ... }
  switch-to-levels: { ... }
  completed-level: { ... }
  locked-level: { ... }
```

# Top-level sections

- `config-version` - Internal version number. **Don't touch this**, the plugin manages it.
- `task-statuses` - The two strings that replace the `{status}` placeholder in a task's `display` line. `completed` is used once the task is done, `not-completed` while it is still in progress. This is where the default ✔ / ✖ marks come from.
- `display-components` - Templates used to render reward lists **inside menu item lore**, wherever an item's lore contains the special `component:rewards` line (for example the level tiles). `title` is the header line shown above the rewards, and `line` is repeated once per reward with `{reward}` replaced by that reward's display text.

:::callout{type="neutral"}
There is a separate `display-components` block in `config.yml`. That one is used for reward lists in **chat messages** (quest-complete / level-up messages). This one in `menu_common.yml` is only for reward lists shown **inside menus**.
:::

- `progress-bar` - Controls the `{progressbar}` placeholder (used by the level tiles). `length` is how many characters wide the bar is, `filled-character` is drawn for completed progress and `unfilled-character` for the remainder.
- `completed-quest-item` - An optional, server-wide fallback appearance applied to **every** completed quest when a pool keeps completed quests visible. Commented out by default. The per-quest `completed-menu-item` overrides it. The full layering order is explained in [Quest configuration](../../auroraquests/configuration/quest-configuration.md).
- `items` - The shared library of menu items (detailed below). All use the standard [Item config](../../aurora/item-config.md) format.

# Shared items

| Key | Where it is used | Useful placeholders |
| --- | --- | --- |
| `previous-page` | Pagination, every menu | `{current}`, `{max}` (`{total}` in the main menu) |
| `current-page` | Pagination, every menu | `{current}`, `{max}` (`{total}` in the main menu) |
| `next-page` | Pagination, every menu | `{current}`, `{max}` (`{total}` in the main menu) |
| `close` | Close button, every menu | — |
| `back` | Back button, pool & level menus | — |
| `switch-to-completed` | Global pools only — button to view already completed quests | `{name}`, `{total_completed}` |
| `switch-to-active` | Global pools only — button to go back to ongoing quests | `{name}` |
| `switch-to-levels` | Pool menu — button to open the level menu (shown only if the pool has leveling) | `{name}`, `{total_completed}`, `{level}`, `{level_raw}`, `{level_roman}`, `{lb_position}`, `{lb_position_percent}`, `{lb_size}` |
| `completed-level` | Level menu — a level tile the player has reached | `{level}`, `{level_raw}`, `{level_roman}`, `{current}`, `{required}`, `{progressbar}`, `{progress_percent}`, `component:rewards` |
| `locked-level` | Level menu — a level tile not reached yet | same as `completed-level` |

:::callout{type="neutral"}
Give `switch-to-completed` and `switch-to-active` the **same slot** — they replace each other as the player toggles the view. The defaults both sit in slot 8.
:::

# Overriding a shared item for one menu

Every menu config (`menu_main.yml`, a pool's `menu` / `leveling.menu` section) has its own `items:` block. Anything you put there is **merged on top** of the shared item defined here, so you only specify the properties you want to change. For example, to make the back button a different material only inside one quest pool:

```yaml
# inside that pool's config.yml -> menu:
menu:
  items:
    back:
      material: red_wool
```

The name, lore and slot still come from the `back` item in `menu_common.yml`; only the material changes.

# Example: a longer, differently-styled progress bar

```yaml
progress-bar:
  length: 20
  filled-character: "&b|"
  unfilled-character: "&8|"
```