> 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/canvas.md).

# 画布、坐标与屏幕位置

在排版菜单之前，先了解 ArcMenu 的坐标系会让你事半功倍。无论是手写 YAML 还是在可视化编辑器里拖拽，所有元素都遵循同一套方向规则：

* **原点 `(0, 0)`** 位于画布正中心。
* **`x` 轴** 控制左右：正数向右，负数向左。
* **`y` 轴** 控制上下：正数向上，负数向下。
* **`z` 轴** 控制前后深度：正数朝玩家眼睛方向靠近（浮在前面），负数向远离玩家的方向退后。

菜单内部排版使用的是逻辑画布单位（可以理解为虚拟像素），而菜单在游戏世界里离玩家多远，使用的是 Minecraft 的方块距离。

## 画布配置（`canvas`）

每份菜单的 `canvas` 段决定了这块虚拟屏幕的尺寸和比例：

```yaml
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3
  depth-mode: perspective
```

| 字段                 | 填写内容与说明                                       | 省略时的默认值       |
| ------------------ | --------------------------------------------- | ------------- |
| `width`            | 画布逻辑宽度，填大于 `0` 的数值。                           | `320`         |
| `height`           | 画布逻辑高度，填大于 `0` 的数值。                           | `180`         |
| `pixels-per-block` | 1 个方块长度对应多少画布单位，填大于 `0` 的数值。                  | `42.7`        |
| `distance`         | 菜单的设计基准距离（单位：方块），填大于 `0` 的数值。                 | `3`           |
| `depth-mode`       | 深度显示模式，可选 `perspective`（透视）或 `layered`（分层对齐）。 | `perspective` |

默认的 `320 × 180` 是一块标准的 16:9 画布。因为中心是 `(0, 0)`，所以它的左边界是 `x: -160`，右边界是 `x: 160`；上边界是 `y: 90`，下边界是 `y: -90`。

如果你想调整整份菜单在屏幕上看起来的大小，可以修改 `pixels-per-block` 或 `distance`：

* **减小 `pixels-per-block`**（比如改成 `32`）：每个画布单位占用的空间变大，整个菜单看起来会**放大**。
* **增大 `pixels-per-block`**（比如改成 `60`）：每个画布单位更紧凑，整个菜单看起来会**缩小**。
* **修改 `distance`**：设计距离越远，菜单在视野中显得越小；设计距离越近，菜单显得越大。

注意 `canvas.distance` 定义的是计算元素视觉比例的设计基准距离，运行时菜单在玩家眼前的实际物理摆放距离由下文的 `offset.yml` 控制（默认为 `0.65` 方块），插件会自动换算缩放，保持设计时的视觉大小不变。

## 元素坐标与点击区域对齐

前端元素的坐标写在 `offset` 里，后端点击区域的坐标直接写 `x` 和 `y`。两者的定位点都是**元素或区域自身的中心**：

```yaml
frontend:
  button-bg:
    type: rectangle
    width: 60
    height: 18
    color: '#365E91'
    offset: {x: 0, y: -20, z: 1}
  button-label:
    type: text
    content: '&f关闭'
    size: 4
    offset: {x: 0, y: -20, z: 2}

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

上面的例子中，背景矩形、文字和点击区域的中心都定在 `(0, -20)`，宽高都是 `60 × 18`（即向左右各延伸 30，向上下各延伸 9）。文字的 `z` 设为 `2`，比背景的 `z: 1` 更靠近玩家，因此文字会清晰地叠在按钮背景上方。

如果前端元素放进了分组（`group`），子元素的 `offset` 就是相对于分组中心的偏移量。当你移动或缩放前端的按钮时，记得把对应的 `backend` 区域也调整到画面最终呈现的位置和尺寸。

## 深度模式：透视与平面图层对齐

当你在菜单里叠放多层背景、边框、图片和文字时，往往需要给它们设置不同的 `z` 值来决定谁挡住谁。`depth-mode` 决定了不同 `z` 值的元素在屏幕上如何呈现：

### `perspective`（默认原版透视）

遵循近大远小的三维透视规律。当某个元素的 `z` 值变大（更靠近玩家）时，它在屏幕上看起来会变大，并且稍微向屏幕四周边缘偏移。这种模式适合带有立体空间感、前后错落的设计。

### `layered`（平面图层对齐）

```yaml
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3
  depth-mode: layered
```

如果你要制作平整的现代 2D 界面，推荐使用 `layered`（也可以直接在可视化编辑器的画布设置里切换）。

在 `layered` 模式下，`z` 值依然正常决定前后遮挡顺序（`z` 大的盖住 `z` 小的），但服务端会自动补偿平面元素因为深度不同而产生的大小变化和位置偏移。这样一来，同样写着 `x: 50, y: 30, width: 100, height: 40` 的底板（`z: 1`）和边框（`z: 2`），在屏幕上就能严丝合缝地重合，分组和动画里的深度变换也会自动享受这套补偿。

需要注意的是，`layered` 专门针对平行于菜单平面的界面元素进行补偿；如果你把平面元素沿 `x`、`y` 轴旋转倾斜，或者放置了原本就有三维厚度的物品（`item`）和方块（`block`），它们依然会保留自身的立体透视感。排版时保持元素在视点前方，用小幅度的 `z` 差值（如 `0.5`、`1`、`2`）区分图层即可。

## 全局屏幕微调：`offset.yml`

`canvas` 控制单份菜单的设计尺寸，而插件目录下的 `plugins/ArcMenu/offset.yml` 控制所有菜单在玩家眼前的实际摆放位置：

```yaml
touch:
  distance: 0.65
  offset: {x: 0, y: 0, z: 0}

mouse:
  distance: 0.65
  offset: {x: 0, y: 0, z: 0}
```

配置文件分为 `touch`（触控模式）和 `mouse`（同时作用于鼠标模式、Vision 模式以及可视化编辑器预览）两段，可以分别调节：

* **`distance`**：玩家眼睛到菜单屏幕的实际物理距离（单位：方块），有效范围为 `0.1` 到 `16`。修改这个值**不会改变菜单在屏幕上看起来的大小**——插件会自动按比例缩放，它只改变菜单实体在世界里离玩家有多近（比如调小可以减少菜单穿进面前墙壁的概率）。
* **`offset`**：整块屏幕的额外平移量（单位：方块），`x`、`y`、`z` 各轴的有效范围均为 `-16` 到 `16`。`x` 正值向右移，`y` 正值向上移，`z` 正值朝玩家拉近。

例如觉得触控模式下菜单整体偏低，可以把 `touch.offset.y` 改成 `0.05`，保存后执行 `/arcmenu reload` 并重新打开菜单就能看到效果。

## 不同模式下的视野（FOV）表现

玩家在客户端设置里调节视野（FOV）滑块时，不同输入模式的表现有所不同：

* **Mouse 模式**：加载配套资源包后，菜单保持固定 FOV 的显示比例，不会因为玩家调高视野或奔跑而变形。
* **Vision 模式与可视化编辑器预览**：使用客户端原生固定 70° 垂直 FOV 独立渲染，画面尺寸始终恒定，且直接兼容各类光影包。
* **触控模式（Touch）**：完全使用原版展示实体渲染，不加载任何自定义着色器，完美兼容光影；菜单在屏幕上的大小会像普通世界物体一样随玩家的 FOV 设置自然变化。
* **Effect 过场动画**：使用原版固定机位视角，按场景自身的设计呈现。


---

# 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/canvas.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.