> 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/gong-neng-pei-zhi/input-modes.md).

# 触控、鼠标与 Vision 输入

ArcMenu 提供触控（`touch`）、鼠标（`mouse`）和视觉（`vision`）三种交互方式。它们共用同一份菜单配置与后端点击区域，你不需要为不同输入方式重复编写菜单。

| 方式          | 操作体验                        | 客户端准备                                          |
| ----------- | --------------------------- | ---------------------------------------------- |
| 触控 `touch`  | 转动视角，用准星对准按钮后点击。            | 原版客户端即可使用。                                     |
| 鼠标 `mouse`  | 视角固定，移动菜单光标指向按钮后点击。         | 加载包含 ArcMenu 资源的配套资源包，无需安装模组。                  |
| 视觉 `vision` | 菜单画面固定，由本地客户端驱动光标移动，支持开启光影。 | 安装与游戏版本匹配的 Fabric、Fabric API 与 ArcMenu Editor。 |

三种方式各有侧重：

* **触控模式**采用原版展示方式，跟随玩家自身的视野（FOV），保留正常的游戏光照与世界方块遮挡，开光影时也能保持正常的画面表现。
* **鼠标模式**在加载配套资源包后启用本地光标、固定视野、菜单前后深度以及均匀的平面光照。
* **Vision 模式**直接调用已集成在 ArcMenu Editor 中的客户端渲染与输入能力，无需再安装其他鼠标模组。普通玩家安装 Editor 后也只会获得客户端交互支持，不会自动获得管理或编辑权限。

## Vision 的显示与响应

Vision 的光标在客户端本地逐帧更新，移动手感流畅迅速。默认光标贴图与 Mouse 模式保持一致，横向和纵向采用统一的位移算法，同时支持服务器的轴向灵敏度配置以及玩家个人的灵敏度、光标缩放设置。当光标移动、悬停或点击时，服务器会实时计算命中区域并执行对应的菜单逻辑。

在画面呈现上，Vision 以固定的 **70° 垂直 FOV** 在独立渲染通道中绘制菜单。菜单尺寸不会因为玩家修改视野设置而变形，也不会被世界里的方块或实体穿模遮挡；菜单内部各图层依然按照自身的前后深度正常遮挡。物品和方块展示使用稳定明亮的界面光照，在开启光影包的环境下同样清晰易读。菜单中的图片和字体继续读取资源包，Editor 内部也自带了默认光标的备用贴图。

## 玩家如何切换模式

玩家在拥有 `arcmenu.use` 权限后，可以通过命令随时查看或切换自己的输入方式：

```
/arcmenu mode
/arcmenu mode touch
/arcmenu mode mouse
/arcmenu mode vision
```

直接输入 `/arcmenu mode` 会显示当前生效的模式。切换后的偏好会自动保存，下次进服时继续生效；如果切换时已经打开了菜单，新模式会直接应用到当前菜单上。

## 点击与悬停交互

无论使用哪种输入方式，后端交互区域都可以识别丰富的点击动作。你可以在按钮的 `actions` 中分别配置以下触发方式：

* `left`：左键点击
* `right`：右键点击
* `middle`：中键点击（对应原版“选取方块”按键）
* `shift-left`：潜行 + 左键
* `shift-right`：潜行 + 右键
* `shift-middle`：潜行 + 中键
* `shift`：按住潜行时的点击
* `all` 或 `any`：任意点击

除了点击，按钮还可以通过 `on-hover` 和 `on-leave` 在准星或光标移入、移出时触发动作。具体的交互区域写法可参考[后端交互](/cai-dan-pei-zhi/menus/backend.md)。

## 菜单快捷键

`config.yml` 中的 `shortcuts` 部分用于管理打开和关闭菜单的常用按键：

```yaml
shortcuts:
  shift-f: true
  close-on-shift-f: true
  close-on-space: true
```

这三个字段都填写布尔值（`true` 或 `false`），默认均为 `true`：

* `shift-f`：未打开菜单时，按 Shift+F（潜行 + 交换副手）直接打开主菜单。主菜单由菜单文件中的 `main-menu: true` 指定，也可以通过 `/arcmenu open main` 打开默认主菜单。
* `close-on-shift-f`：菜单或应用打开期间，允许按 Shift+F 将其关闭。
* `close-on-space`：菜单或应用打开期间，允许按空格（跳跃键）将其关闭。

按键检测跟随玩家在客户端里绑定的潜行、交换副手和跳跃键位。在 Vision 模式下按空格关闭菜单时，客户端会拦截这次跳跃输入，避免角色在关闭菜单的同时起跳。当玩家正在使用 Arcitx 输入文字时，空格键会正常输入空格字符，不会误关菜单。

## 服务器模式策略

服主可以在 `config.yml` 的 `mouse` 部分统一规划全服的默认输入方式与切换权限：

```yaml
mouse:
  policy: player-choice
  default: touch
  assume-resource-pack-loaded: true
  sample-rate: 40
```

### 字段取值说明

* `policy`：控制玩家的模式选择范围，可填以下字符串：
  * `player-choice`（默认）：允许玩家自由切换 `touch`、`mouse` 或 `vision`。首次进服未设置偏好时，按 `default` 生效。
  * `force-touch`：全服统一使用触控模式。
  * `force-mouse`：统一使用光标交互。玩家默认进入 `mouse` 模式，安装了对应版本 ArcMenu Editor 的客户端也可以切换到 `vision` 模式。
* `default`：当策略为 `player-choice` 且玩家尚未主动选择模式时使用的默认方式。可填 `touch`、`mouse` 或 `vision`。如果计划将默认值设为 `vision`，请先引导玩家安装好与客户端版本匹配的 ArcMenu Editor。
* `assume-resource-pack-loaded`：填写 `true` 或 `false`，默认 `true`。设为 `true` 时，即使玩家是通过客户端本地手动加载的配套资源包，也能直接使用 Mouse 模式的菜单深度、平面光照、本地光标与本地 GIF 播放；设为 `false` 时，服务器会先等待客户端返回资源包加载成功回执。关于资源包生成与分发，详见[图片与资源包](/gong-neng-pei-zhi/resource-packs.md)。
* `sample-rate`：填写 `20` 到 `60` 之间的整数，默认 `40`。用于旧版服务端轮询光标的采样频率（单位 Hz）；本地光标与 Vision 模式由客户端直接驱动，不依赖此轮询。

## 光标外观与灵敏度配置

`config.yml` 中的 `mouse.cursor` 用于调整光标的移动速度、活动边界和显示尺寸：

```yaml
mouse:
  cursor:
    interpolation-ticks: 0
    sensitivity-x: 2.0
    sensitivity-y: 2.0
    clamp-margin: 3.0
    size: 5.0
    z: 5.0
```

| 字段                    | 有效值范围             | 默认值   | 说明                          |
| --------------------- | ----------------- | ----- | --------------------------- |
| `sensitivity-x`       | `0.05` – `50` 的数值 | `2.0` | 光标横向移动灵敏度。数值越大，横向移动越快。      |
| `sensitivity-y`       | `0.05` – `50` 的数值 | `2.0` | 光标纵向移动灵敏度。数值越大，纵向移动越快。      |
| `clamp-margin`        | 大于或等于 `0` 的数值     | `3.0` | 画布四边的内缩留白（画布单位），防止光标移出菜单边缘。 |
| `size`                | 大于 `0` 的正数        | `5.0` | 光标的逻辑显示高度（画布单位）。            |
| `z`                   | 任意有限数值            | `5.0` | 光标相对于菜单平面的前后层次偏移，数值越大越靠前。   |
| `interpolation-ticks` | `0`、`1` 或 `2`     | `0`   | 旧版轮询光标的平滑插值刻数，`0` 为立即响应。    |

菜单的默认光标贴图位于 `plugins/ArcMenu/images/mouse/mouse.png`，当光标悬停在可点击区域上时会自动切换为 `choose.png`。生成资源时，这两张贴图也会一并同步给 Vision 模式使用。

修改了光标贴图或 `mouse.cursor` 中的几何与灵敏度参数后，需要重新构建资源包以更新本地光标配置：可以先执行 `/arcmenu resources` 或 `/arcmenu reload all` 生成 ArcMenu 资源，若配合了外部资源包插件，再执行对应插件的打包重载命令（如 `/ce reload pack`、`/nexo reload pack` 或 `/iazip`）。如果只是修改了 `policy`、`default` 或 `shortcuts`，直接执行 `/arcmenu reload` 即可生效。

如果你想调整整张菜单在玩家屏幕上的上下左右偏移或实际摆放距离，可以在 `offset.yml` 中按模式分别设置，详见[画布、坐标与屏幕位置](/cai-dan-pei-zhi/menus/canvas.md)。

## 玩家个人灵敏度与光标大小

每位拥有 `arcmenu.use` 权限的玩家都可以根据自己的习惯，微调光标移动速度和显示大小，不会影响服务器的基础配置或其他玩家。首次安装时自带的 `cursor-setting` 示例菜单也演示了这一功能。

```
/arcmenu sensitivity
/arcmenu sensitivity set 7
/arcmenu sensitivity add -1
/arcmenu sensitivity clear

/arcmenu cursor-scale
/arcmenu cursor-scale set 3
/arcmenu cursor-scale add 1
/arcmenu cursor-scale clear
```

* 不带参数执行命令会显示玩家当前的等级与倍率。
* `set <1-9>`：直接将等级设为 `1` 到 `9` 之间的整数。
* `add <整数>`：在当前等级基础上增减（例如 `add 1` 或 `add -1`），结果保持在 `1` 到 `9` 之间。
* `clear`：清除个人设置，恢复为默认的 `5` 级。

等级与倍率的换算公式为 `2^((等级 - 5) / 4)`：

* **等级 5（默认）**：`1` 倍，保持服务器配置的原始速度与大小。
* **等级 1（最低）**：`0.5` 倍。
* **等级 9（最高）**：`2` 倍。

个人灵敏度倍率会同时乘在服务器的 `sensitivity-x` 和 `sensitivity-y` 上，个人光标大小倍率会乘在 `mouse.cursor.size` 上。修改后对当前已打开的 Mouse 或 Vision 菜单立即生效，正在播放的菜单动画也不会中断。这项偏好保存在当前服务器的玩家数据中。

### 相关占位符

你可以在菜单文本中直接使用以下占位符来展示玩家当前的设置，安装 PlaceholderAPI 后也可以在其他插件中调用：

| 占位符                            | 返回内容                 |
| ------------------------------ | -------------------- |
| `%arcmenu_sensitivity%`        | 当前个人灵敏度倍率（最多保留四位小数）  |
| `%arcmenu_sensitivity_level%`  | 当前个人灵敏度等级（`1`–`9`）   |
| `%arcmenu_cursor_scale%`       | 当前个人光标大小倍率（最多保留四位小数） |
| `%arcmenu_cursor_scale_level%` | 当前个人光标大小等级（`1`–`9`）  |

`privatepointersensitivity` 和 `privatepointerscale` 可作为对应命令与占位符的同义别名使用（例如 `%arcmenu_privatepointersensitivity_level%`）。


---

# 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/gong-neng-pei-zhi/input-modes.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.