> 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/ru-men/first-menu.md).

# 第一个菜单

这一节我们来亲手做一个带标题和欢迎按钮的简单菜单。玩家打开菜单后，用准星或鼠标指向按钮并点击右键，就会在聊天栏收到一条带自己名字的欢迎消息。

## 快速创建菜单文件

进入服务端的 `plugins/ArcMenu/menus/` 目录，新建一个名为 `welcome.yml` 的文件。

> **小技巧**：如果你直接新建一个空白的 `welcome.yml` 并执行 `/arcmenu reload`，ArcMenu 会自动根据文件名帮你补全 `schema-version`、`id` 和默认的 `canvas` 画布配置。文件名只需使用小写字母、数字、下划线或连字符，并以字母或数字开头即可。

把下面这段配置写进 `welcome.yml` 并保存：

```yaml
schema-version: 1
id: welcome

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

frontend:
  background:
    type: rectangle
    width: 140
    height: 80
    color: '#182031'
    opacity: 235
  title:
    type: text
    content: '&f欢迎来到服务器'
    offset: {y: 24, z: 1}
    size: 5
  description:
    type: text
    content: '&7右键下方按钮'
    offset: {y: 4, z: 1}
    size: 3
  greeting-button:
    type: rectangle
    width: 60
    height: 18
    color: '#365E91'
    offset: {y: -20, z: 1}
  greeting-label:
    type: text
    content: '&f打个招呼'
    offset: {y: -20, z: 2}
    size: 4

backend:
  greeting-area:
    x: 0
    y: -20
    width: 60
    height: 18
    actions:
      right:
        - 'tell: &a欢迎，%player_name%！'
```

保存文件后，在游戏内或后台执行 `/arcmenu reload`，然后输入 `/arcmenu open welcome` 就能在眼前看到这个菜单了。命令里的 `welcome` 对应的就是文件中定义的 `id: welcome`。

如果你安装了客户端编辑器模组，也可以在游戏里执行 `/arcmenu edit welcome`，在可视化界面上修改并点击保存，修改会立即生效。

## 理解配置里的各个部分

一份标准的 ArcMenu 菜单由画布设置、前端画面和后端交互三块组成：

* **基础信息与画布（`canvas`）**：`schema-version` 固定填 `1`；`id` 是菜单的唯一标识。`canvas` 定义了一块宽高为 `320 × 180` 逻辑像素的 16:9 屏幕，`distance: 3` 与 `pixels-per-block: 42.7` 共同设定了画布的设计基准距离与比例（游戏内菜单实际生成的观察距离由 `offset.yml` 控制，默认距离玩家眼睛 `0.65` 格，渲染时会自动按比例缩放以保持你在设计时看到的画面大小不变）。
* **前端画面（`frontend`）**：这里放所有玩家看得见的视觉元素。例子里用 `type: rectangle` 画出了深蓝色的底板（`background`）和浅蓝色的按钮底色（`greeting-button`），支持十六进制颜色如 `'#182031'` 和 `0`–`255` 的不透明度 `opacity`；再用 `type: text` 放上了标题、提示语和按钮文字。
* **后端交互区（`backend`）**：前端元素只负责展示画面，真正的点击判定由 `backend` 里的区域负责。`greeting-area` 定义了一个中心在 `(0, -20)`、宽高为 `60 × 18` 的矩形命中区，刚好覆盖在前端按钮的正上方；当玩家在这个区域内点击右键（`right`）时，就会触发 `tell:` 动作向自己发送消息。

你可以留意一下坐标的配合方式：画布正中心是 `(0, 0)`，`y` 轴向上为正、向下为负。按钮底板 `greeting-button`、按钮文字 `greeting-label` 和后端点击区域 `greeting-area` 的中心点都设在 `y: -20`（未写的 `x` 默认为 `0`），这样三者就能严丝合缝地叠在一起。以后想把按钮换个位置，把它们的 `x` 和 `y` 一起改动即可。至于前端的 `z` 值则用来控制前后遮挡，数值越大的图层越靠前，所以按钮文字（`z: 2`）会清晰地浮现在按钮底板（`z: 1`）上方。

## 继续往下尝试

有了这个基础骨架，你可以试着改改里面的值：

* 修改 `content` 里的文本可以更换标题，支持 `&` 颜色代码与 MiniMessage 格式；修改 `tell:` 后面的内容可以更换点击后的提示语。
* 把 `actions.right` 下面的动作改成 `- 'open: main'`，右键点击按钮就会直接跳转到服务器的 `main` 主菜单。更多指令执行、扣费、播放声音等写法，可以在[动作与导航](/cai-dan-pei-zhi/menus/actions.md)中查看。
* 服务器只允许同时存在一个主菜单（即按 **Shift+F** 默认唤出的菜单）。如果你想让这个 `welcome` 菜单成为新的主菜单，只需先把原主菜单（默认是 `main.yml`）里的 `main-menu: true` 改为 `false` 或删掉，再在 `welcome.yml` 顶层加上一行 `main-menu: true` 并重载即可。

想要系统了解菜单支持的全部属性，可以继续阅读[菜单文档结构](/cai-dan-pei-zhi/menus.md)；想直接在游戏画面里拖拽排版，请前往[可视化编辑器](/gong-neng-pei-zhi/editor.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/ru-men/first-menu.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.