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

# 画布、坐标与屏幕位置

菜单布局使用画布坐标。调整某个元素的位置，应修改菜单文件；调整所有菜单在玩家面前的位置，则使用整体屏幕设置。

本页先说明菜单中的 `canvas`，再介绍布局坐标和整体屏幕位置。顶层结构见[菜单文档结构](/arcmenu-wen-dang/cai-dan-pei-zhi/menus.md)。

## 画布设置：`canvas`

`canvas` 位于菜单文件顶层，适用于 Paper、Folia、Leaf 和 Spigot。

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

### `width` 与 `height`

设置画布的逻辑宽度和高度。示例为 `320 × 180`，宽高比为 `16:9`。

这些值用于确定画布范围，不是玩家显示器的分辨率。修改画布尺寸不会自动重新排列元素，也不会同步修改按钮的点击范围。

以上方配置为例，画布中心是 `(0, 0)`，参考边界如下：

| 位置 | 坐标        |
| -- | --------- |
| 左侧 | `x: -160` |
| 右侧 | `x: 160`  |
| 顶部 | `y: 90`   |
| 底部 | `y: -90`  |

布局时应为文字和按钮本身的尺寸预留空间，而不是仅将它们的中心放在边界内。

### `pixels-per-block`

设置画布单位与游戏内尺寸的比例。在其他设置不变时：

* 数值增大，菜单及元素显示得更小。
* 数值减小，菜单及元素显示得更大。

它同时影响菜单中的显示内容和点击范围。调整整个菜单的显示大小时，可修改此值，无需逐个改变元素坐标。

### `distance`

设置菜单的设计距离，单位为方块。在其他设置不变时，数值增大会使菜单在视野中显得更小，数值减小则会显得更大。

两类服务端的使用方式如下：

| 服务端                | `canvas.distance` 的作用                |
| ------------------ | ------------------------------------ |
| Paper、Folia、Leaf 等 | 用于确定菜单的显示比例；整体屏幕距离由 `offset.yml` 设置。 |
| Spigot             | 设置菜单与玩家视点之间的距离。                      |

`width`、`height`、`pixels-per-block` 和 `distance` 都必须是大于 `0` 的数值。不填写时，默认值依次为 `320`、`180`、`100` 和 `3`。

## 菜单布局坐标

### 方向与单位

| 轴   | 正值方向 | 负值方向 |
| --- | ---- | ---- |
| `x` | 向右   | 向左   |
| `y` | 向上   | 向下   |
| `z` | 靠近玩家 | 远离玩家 |

菜单中的位置和尺寸使用画布单位，不直接表示方块距离。例如，按钮的 `width: 60` 表示宽度为 `60` 个画布单位。

### 显示元素的位置

元素的位置写在 `frontend` 下对应元素的 `offset` 中。`x` 和 `y` 用于布局，`z` 用于安排前后层次。

文字放在按钮背景前方时，可为文字设置更大的 `z`，避免背景遮挡文字。未配置的偏移轴默认为 `0`。

分组中的元素位置以所在分组为参考；本页示例直接使用顶层元素。分组与缩放见[分组与可复用模板](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/groups-templates.md)。

### 点击区域的位置

点击区域的位置写在 `backend` 下对应区域的 `x` 和 `y` 中，表示区域中心。`width` 和 `height` 表示区域尺寸。

点击区域没有 `offset` 或 `z` 字段。它需要与显示按钮分别配置。

下面的按钮位于画布中心下方，背景、文字和点击区域相互对应。此片段用于替换或添加菜单中的相应内容，不是完整菜单文件。

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

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

将按钮向右移动时，应同时修改背景、文字的 `offset.x` 和区域的 `x`。改变按钮大小时，也应调整区域尺寸。

前端分组的移动、旋转和缩放不会自动改变点击区域。元素的完整属性见[前端元素类型](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/frontend.md)。

## 整体屏幕设置：`offset.yml`

本节仅适用于 Paper、Folia、Leaf 等服务端。配置文件为 `plugins/ArcMenu/offset.yml`，设置作用于对应操作方式下的所有菜单；鼠标模式设置也影响编辑器中的菜单。

Spigot 不使用此文件，应通过菜单的 `canvas.distance` 设置距离。

### 操作方式

`touch` 设置触摸模式，`mouse` 设置鼠标模式。两者可分别调整，默认配置如下：

```yaml
touch:
  distance: 0.65
  offset:
    x: 0.0
    y: 0.0
    z: 0.0

mouse:
  distance: 0.65
  offset:
    x: 0.0
    y: 0.0
    z: 0.0
```

### `distance`

设置屏幕与玩家视点的距离，单位为方块，允许范围为 `0.1` 至 `16`。

改变这里的距离时，插件会保持菜单在视野中的显示大小。因此，若目的是放大或缩小菜单，应调整菜单中的 `pixels-per-block` 或设计距离，而不是仅修改此项。

### `offset`

在原有位置上平移整个屏幕，单位为方块。方向以菜单屏幕为参考，不是世界坐标方向。

* `x` 正值向右，负值向左。
* `y` 正值向上，负值向下。
* `z` 正值靠近玩家，负值远离玩家。

每个轴的允许范围为 `-16` 至 `16`，默认均为 `0`。整体平移会同时移动显示内容和点击区域，无需逐个修改菜单元素。

例如，将触摸模式的菜单略微上移，可把 `touch.offset.y` 从 `0.0` 调整为 `0.05`。应从小幅度调整开始，并重新打开菜单检查效果。

## 修改与验证

| 调整目标        | 修改位置                                                 |
| ----------- | ---------------------------------------------------- |
| 移动一个按钮      | 按钮元素的 `offset` 和对应区域的 `x`、`y`。                       |
| 改变一个按钮的点击尺寸 | 对应区域的 `width`、`height`，同时检查按钮显示尺寸。                   |
| 放大或缩小整个菜单   | 菜单的 `canvas.pixels-per-block` 或 `canvas.distance`。   |
| 平移所有菜单      | Paper 系服务端的 `offset.yml`。                            |
| 改变屏幕实际距离    | Paper 系服务端的 `offset.yml`；Spigot 的 `canvas.distance`。 |

保存后执行 `/arcmenu reload`，重新打开菜单，检查显示与点击是否对齐。鼠标模式还应检查光标移动及边缘按钮。相关操作命令见[命令与权限](/arcmenu-wen-dang/pei-zhi-yu-guan-li/commands-permissions.md)。