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

# Menu document structure

Every menu is a YAML file inside `plugins/ArcMenu/menus/`. You can place files directly in the root directory or organize them into subfolders by feature, such as `menus/shop/weapons.yml` or `menus/system/settings.yml`. Commands and navigation actions always reference the menu `id` defined inside the file, so you are free to name and organize the files themselves however you like.

## Creating a new menu with auto-completion

When creating a new menu, you do not need to write the boilerplate by hand. Create an empty `.yml` file (or a file containing only comments) anywhere under `menus/` and run `/arcmenu reload`. ArcMenu automatically fills in the standard header and saves the file. For example, an empty `shop.yml` becomes:

```yaml
schema-version: 1
id: 'shop'
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3
```

The generated `id` defaults to the filename without the `.yml` extension. If another menu on the server already uses that ID, ArcMenu appends a number (`shop1`, `shop2`, and so on) to avoid conflicts. If an existing menu file is missing its entire `canvas` section, reloading also inserts the default canvas settings while preserving your comments and other configuration.

## Complete structure overview

A complete menu typically consists of five parts: basic metadata, canvas settings, frontend visuals, backend interaction regions, and lifecycle events:

```yaml
schema-version: 1
id: menu-guide
permission: ''
main-menu: false

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

frontend:
  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:
    - 'sound: BLOCK_CHEST_OPEN-1-1'
  close:
    - 'sound: BLOCK_CHEST_CLOSE-1-1'
```

## Top-level fields

The root of a menu file accepts only the fields listed below. Misspelled or unknown root keys produce a clear error when the menu loads:

| Field                    | Valid values and description                                                                                                                         | Default when omitted                    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `schema-version`         | Configuration format version. Always set this to the integer `1`.                                                                                    | Required                                |
| `id`                     | Unique menu identifier. Must start with a lowercase letter or digit and may contain lowercase letters, digits, underscores (`_`), and hyphens (`-`). | Required                                |
| `permission`             | Additional permission node (string) required to open the menu. When empty or omitted, players only need the base `arcmenu.use` permission.           | `''` (no extra permission)              |
| `permission-denied-menu` | ID of another menu to open automatically when the player lacks the required `permission`. Uses the same format rules as `id`.                        | `''` (block access without redirecting) |
| `open-commands`          | Custom commands registered specifically to open this menu. Accepts a single string or a list of strings.                                             | Empty list                              |
| `main-menu`              | `true` or `false`. Determines whether pressing `Shift+F` opens this menu as the server's main menu.                                                  | `false`                                 |
| `canvas`                 | Object defining the logical canvas dimensions, scale, design distance, and depth mode.                                                               | Default canvas settings                 |
| `frontend`               | Map of all visible elements (text, images, rectangles, items, blocks, and groups).                                                                   | Empty (no visual elements)              |
| `backend`                | Map of all clickable hitboxes, tooltips, and text input components.                                                                                  | Empty (no interaction regions)          |
| `events`                 | Actions executed when the menu opens (`open`) or closes (`close`).                                                                                   | Empty (no lifecycle actions)            |

## Custom open commands and the main menu

Beyond `/arcmenu open <menu-id>`, you can bind short, direct commands to frequently used menus or designate a menu as the server-wide main menu:

```yaml
open-commands:
  - servermenu
  - guide
main-menu: true
```

With this configuration, players can type `/servermenu` or `/guide`, or press `Shift+F`, to open the menu directly.

When configuring `open-commands`, keep these rules in mind:

* Do not include a leading slash (`/`) in the command name.
* Use only lowercase letters, digits, underscores (`_`), and hyphens (`-`), starting with a letter or digit, up to 64 characters long.
* Do not list duplicate command names within the same menu.

Only one menu file on your server should have `main-menu: true` (such as the default `main` menu created on first install). When switching to a different main menu, set `main-menu: false` in the previous one.

## Permission checks and fallback menus

To open a menu, a player must have both `arcmenu.use` and any node configured in `permission`.

If a menu is reserved for VIP members or players who have reached a specific stage, a plain "permission denied" message can feel abrupt. You can pair `permission` with `permission-denied-menu` to redirect unauthorized players to an introduction or unlock guide instead:

```yaml
permission: myserver.vip
permission-denied-menu: vip-intro
```

When a player tries to open this menu:

* Players with `myserver.vip` enter the menu normally.
* Players without `myserver.vip` do not trigger this menu's `open` event. Instead, they are automatically sent to `vip-intro` along with any navigation arguments originally passed in (the target menu still checks its own permissions).
* Administrators running `/arcmenu force-open <menu-id> <player>` bypass permission checks and open the target menu directly for that player.

## How frontend visuals and backend regions work together

ArcMenu separates what players see from what they click into `frontend` and `backend`:

* **`frontend`** handles layout and presentation. Elements can be combined inside groups (`group`) and support 3D translation, rotation, and scaling.
* **`backend`** handles cursor clicks, hover detection, and tooltips. Interaction regions stay aligned with the horizontal and vertical axes of the canvas and define their own coordinates, width, and height.

Every element and group key under `frontend`, as well as every region and group key under `backend`, **must be unique across the entire menu file**. Keys cannot be duplicated and cannot contain slashes (`/`, `\`) or control characters.

## Open and close events

The `events` section runs actions at key points in the menu lifecycle and supports two keys, `open` and `close`:

```yaml
events:
  open:
    - 'tell: &aWelcome, %player_name%!'
    - 'sound: BLOCK_CHEST_OPEN-1-1'
  close:
    - 'sound: BLOCK_CHEST_CLOSE-1-1'
```

Lifecycle events use the exact same action syntax and conditional action groups as buttons. To trigger effects when a player moves the cursor onto or off a specific button, use `on-hover` and `on-leave` inside that button's `backend` region instead.

Next, explore each part of a menu in detail:

* [Canvas, coordinates and screen position](/en/menu-configuration/menus/canvas.md)
* [Frontend element types](/en/menu-configuration/menus/frontend.md)
* [Backend regions and click events](/en/menu-configuration/menus/backend.md)
* [Actions and navigation](/en/menu-configuration/menus/actions.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/en/menu-configuration/menus.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.