> 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/cai-dan-pei-zhi/menus.md).

# 菜单文档结构

每份菜单对应一个 YAML 文件，存放在 `plugins/ArcMenu/menus/` 目录下。你可以直接放在根目录，也可以按业务创建子文件夹来分类管理，比如 `menus/shop/weapons.yml` 或 `menus/system/settings.yml`。打开或跳转菜单时始终使用文件里的菜单 `id`，文件怎么摆放、叫什么名字可以按你的习惯安排。

## 新建菜单与快速补全

准备写新菜单时，不需要从头手打基础框架。直接在 `menus/`（或任意子目录）下新建一个空的 `.yml` 文件，或者只写几行注释，然后执行 `/arcmenu reload`，插件就会自动为你补全标准头部并保存。例如新建一个空白的 `shop.yml`，重载后文件内容会变成：

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

自动生成的 `id` 默认取自文件名（去掉 `.yml`）。如果服务器里已经有同名 ID，它会自动顺延成 `shop1`、`shop2`，避免冲突。如果某份现有菜单漏写了整个 `canvas` 段，重载时也会自动补上这套默认画布参数，同时保留你原有的注释和其他配置。

## 完整结构概览

一份完整的菜单通常包含基础信息、画布设置、前端画面、后端交互区域和生命周期事件五个部分：

```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: '&f菜单指南'
    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: '&f关闭'
    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'
```

## 顶层字段说明

菜单根节点只接受以下字段，拼写错误或多出的未知字段会在加载时给出明确报错：

| 字段                       | 填写内容与说明                                                 | 省略时的默认值        |
| ------------------------ | ------------------------------------------------------- | -------------- |
| `schema-version`         | 配置文件格式版本，固定填写整数 `1`。                                    | 必填             |
| `id`                     | 菜单唯一标识符。以小写字母或数字开头，可包含小写字母、数字、下划线 `_` 和连字符 `-`。         | 必填             |
| `permission`             | 打开该菜单所需的额外权限节点（字符串）。留空或省略时，玩家只需具备基础的 `arcmenu.use` 权限。  | `''`（无额外权限）    |
| `permission-denied-menu` | 玩家缺少 `permission` 指定的权限时，自动转而打开的另一份菜单 ID。格式要求与 `id` 相同。 | `''`（不跳转，直接拦截） |
| `open-commands`          | 为当前菜单注册的专属打开命令，可填写单个字符串或字符串列表。                          | 空列表            |
| `main-menu`              | 填 `true` 或 `false`，决定是否将此菜单设为 `Shift+F` 快捷键打开的主菜单。      | `false`        |
| `canvas`                 | 定义逻辑画布尺寸、比例、设计距离与深度模式的对象。                               | 全部使用画布默认值      |
| `frontend`               | 存放所有可见视觉元素（文字、图片、矩形、物品等）的映射表。                           | 空（无视觉元素）       |
| `backend`                | 存放所有点击判定区域、提示框与文本输入组件的映射表。                              | 空（无交互区域）       |
| `events`                 | 定义菜单打开（`open`）和关闭（`close`）时执行的动作。                       | 空（无事件动作）       |

## 绑定打开命令与主菜单

除了让玩家输入 `/arcmenu open <菜单ID>`，你还可以给常用菜单绑定简短的直达命令，或把它设为全服主菜单：

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

配置后，玩家输入 `/servermenu`、`/guide` 或按下 `Shift+F` 都能直接打开这份菜单。

填写 `open-commands` 时需要注意：

* 命令名不要带开头的斜杠 `/`
* 只能使用小写字母、数字、下划线 `_` 和连字符 `-`，且以字母或数字开头，长度不超过 64 个字符
* 同一份菜单里不能写重复的命令名

全服所有菜单文件中只应保留一份 `main-menu: true`（例如首次安装自带的 `main` 菜单）。如果你想换用新菜单作为主菜单，把原主菜单里的 `main-menu` 改为 `false` 即可。

## 权限拦截与引导跳转

要打开一份菜单，玩家需要同时具备默认的 `arcmenu.use` 权限和该菜单配置的 `permission` 权限。

如果某个菜单只对会员或特定阶段的玩家开放，直接提示“没有权限”往往不够直观。你可以配合使用 `permission-denied-menu`，把没有权限的玩家引导到专门的介绍页或解锁说明页：

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

当玩家尝试打开这份菜单时：

* 拥有 `myserver.vip` 的玩家正常进入当前菜单。
* 缺少 `myserver.vip` 的玩家不会触发当前菜单的 `open` 事件，而是携带原有的导航参数自动打开 `vip-intro` 菜单（目标菜单同样会检查它自己的权限）。
* 管理员使用 `/arcmenu force-open <菜单ID> <在线玩家>` 强制为玩家打开菜单时，会直接绕过权限检查进入原菜单。

## 前端画面与后端交互的配合

ArcMenu 将“看见的画面”和“能点的区域”拆分成 `frontend` 和 `backend` 两部分：

* **`frontend`** 负责排版和美观。里面的元素可以通过分组（`group`）组合在一起，支持三维位移、旋转和缩放。
* **`backend`** 负责接收指针点击、悬停和显示提示框。交互区域始终与画布横竖对齐，独立设置坐标和宽高。

无论是 `frontend` 里的元素、分组，还是 `backend` 里的区域和分组，它们的键名（ID）在**整份菜单文件内都必须唯一**，不能重名，也不能包含斜杠 `/`、`\` 或控制字符。

## 打开与关闭事件

`events` 用于在菜单生命周期的关键节点触发动作，只包含 `open` 和 `close` 两个字段：

```yaml
events:
  open:
    - 'tell: &a欢迎，%player_name%！'
    - 'sound: BLOCK_CHEST_OPEN-1-1'
  close:
    - 'sound: BLOCK_CHEST_CLOSE-1-1'
```

这里支持与按钮完全一致的动作语法和条件动作组。如果你想在玩家把指针移到某个按钮上或移开时触发效果，则应该写在对应 `backend` 区域的 `on-hover` 和 `on-leave` 中。

接下来，你可以按顺序深入了解各个部分的具体写法：

* [画布、坐标与屏幕位置](/cai-dan-pei-zhi/menus/canvas.md)
* [前端元素类型](/cai-dan-pei-zhi/menus/frontend.md)
* [后端交互区域与点击事件](/cai-dan-pei-zhi/menus/backend.md)
* [动作与导航](/cai-dan-pei-zhi/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/cai-dan-pei-zhi/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.