> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/menu-configuration/menus.md).

# Menu document structure

Each menu uses a YAML file. This page introduces its top-level fields in configuration order. Follow the links to the canvas, element and hit-region references for their child fields.

For creation and loading steps, see [Your first menu](/arcmenu-wiki/getting-started/first-menu.md). Menu directories are listed in [Configuration files](/arcmenu-wiki/configuration-and-administration/configuration-files.md).

## Overall structure

The following basic menu contains visible content, a close button and a message displayed when it opens. It works on Paper, Folia, Leaf and Spigot.

```yaml
schema-version: 1
id: menu-guide
permission: arcmenu.use
main-menu: false

canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3

frontend:
  background:
    type: rectangle
    width: 140
    height: 80
    color: '#182031'
  title:
    type: text
    content: '&fMenu guide'
    offset: {y: 20, z: 1}
    size: 5
  close-button:
    type: rectangle
    width: 60
    height: 18
    offset: {y: -20, z: 1}
    color: '#365E91'
  close-label:
    type: text
    content: '&fClose'
    offset: {y: -20, z: 2}
    size: 4

backend:
  close-area:
    x: 0
    y: -20
    width: 60
    height: 18
    actions:
      right: close

events:
  open:
    - 'tell: &aMenu opened.'
```

This example is not marked as the main menu. Retain the existing main menu when adding it to a menu directory.

## Top-level fields

These fields belong at the outermost level of the file, without indentation beneath another section.

| Field            | Value format      | Purpose                                               |
| ---------------- | ----------------- | ----------------------------------------------------- |
| `schema-version` | Integer           | Menu configuration format.                            |
| `id`             | Text              | Unique menu identifier.                               |
| `permission`     | Text              | Permission required to open the menu.                 |
| `open-commands`  | List              | Custom opening commands, on Paper-based servers only. |
| `main-menu`      | `true` or `false` | Marks the main menu.                                  |
| `canvas`         | Section           | Canvas settings.                                      |
| `frontend`       | Section           | Visible elements.                                     |
| `backend`        | Section           | Hit regions and interaction settings.                 |
| `events`         | Section           | Actions performed when the menu opens or closes.      |

### `schema-version`

Use `schema-version: 1`. This identifies the menu configuration format, not the plugin release version.

### `id`

The identifier is used to open the menu and navigate between menus. For example, `id: menu-guide` corresponds to:

```
/arcmenu open menu-guide
```

Use lowercase letters, digits, underscores and hyphens, beginning with a letter or digit. Identifiers must be unique across the menu directory.

The file name can differ from the identifier, but matching them makes management easier. Opening commands use the `id`, not the file name.

### `permission`

Set a permission required to open the menu, such as `permission: myserver.menu.vip`.

Players also need `arcmenu.use`. Omitting `permission` or setting it to an empty string removes the additional menu permission requirement.

See [Menu permissions](/arcmenu-wiki/configuration-and-administration/commands-permissions.md#menu-permissions) for permission assignment.

### `open-commands`

Define dedicated opening commands on Paper, Folia, Leaf and compatible servers:

```yaml
open-commands:
  - menuguide
  - serverguide
```

Once loaded, `/menuguide` or `/serverguide` opens the menu. Players must still meet its permission requirements.

Command names omit `/`, contain lowercase letters, digits, underscores or hyphens, begin with a letter or digit, and are limited to 64 characters. Names cannot be repeated in the list or used by another menu or plugin.

Omit this field if dedicated commands are unnecessary and use `/arcmenu open <menu-id>`. Spigot does not provide this feature; use `/arcmenu open` instead.

### `main-menu`

`main-menu: true` marks the menu opened by Shift+F. The default is `false`.

Exactly one menu must be marked as the main menu, even when the Shift+F shortcut is disabled. When changing the main menu, remove `main-menu: true` from the previous one.

The shortcut setting is in the server's corresponding `config.yml`; see [Configuration files](/arcmenu-wiki/configuration-and-administration/configuration-files.md).

### `canvas`

This section defines canvas dimensions, display scale and distance. Text, buttons and hit regions use menu coordinates for placement.

This page only establishes its position in the document. Child fields and their relationship to screen placement are covered in [Canvas, coordinates and screen placement](/arcmenu-wiki/menu-configuration/menus/canvas.md).

### `frontend`

Visible content is organized by element name, with each element's type and properties inside its section. In the example, `background`, `title`, `close-button` and `close-label` belong at this level.

Read the hierarchy as **`frontend` → element name → `type` and properties**. Type-specific fields are covered in [Frontend element types](/arcmenu-wiki/menu-configuration/menus/frontend.md).

### `backend`

Interaction settings are organized by region name. Each section defines its hit region and actions. The example's `close-area` is one such region.

Read the hierarchy as **`backend` → region name → region properties and `actions` → click type and actions**.

Visible elements and hit regions are configured separately. When moving or resizing a button, adjust its region too. Frontend group changes do not automatically affect hit regions.

Element and region names must be unique within a menu, including elements inside groups. A button element and its hit region must not share a name.

Region child fields are covered in [Backend regions and click events](/arcmenu-wiki/menu-configuration/menus/backend.md).

### `events`

Define actions performed when a menu opens or closes. The next level uses `open` and `close`:

```yaml
events:
  open:
    - 'tell: &aMenu opened.'
  close:
    - 'tell: &7Menu closed.'
```

Omit this section when no event actions are needed. Events use the same action syntax as buttons; see [Actions and navigation](/arcmenu-wiki/menu-configuration/menus/actions.md).

Here, `close` names a closing event. A button's `right: close` instead runs the close action on a right-click. They belong to different levels.

## Authoring rules

* Indent with spaces and align fields at the same level.
* Use supported field names; unknown fields cannot be added.
* Do not repeat the same field within a section.
* Keep text containing color codes or special characters in quotation marks.
* Validate configuration before reloading changes.

Check feature availability in [Platform and plugin compatibility](/arcmenu-wiki/configuration-and-administration/compatibility.md). Validation and reload commands are listed in [Commands and permissions](/arcmenu-wiki/configuration-and-administration/commands-permissions.md).