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

# 触摸与鼠标输入

ArcMenu 提供触摸模式（`touch`）和鼠标模式（`mouse`）。两种方式使用同一套菜单、按钮和点击区域，无需分别创建菜单。

| 操作方式 | 如何指向按钮           | 适用服务端                    | 资源包                 |
| ---- | ---------------- | ------------------------ | ------------------- |
| 触摸模式 | 转动视角，用准星指向按钮后点击。 | Paper、Folia、Leaf、Spigot。 | 操作本身不要求资源包；菜单图片仍需要。 |
| 鼠标模式 | 移动菜单光标，指向按钮后点击。  | Paper、Folia、Leaf 等。      | 应加载配套资源包。           |

“触摸模式”指通过视线指向菜单，并不要求触摸屏。普通玩家使用这两种方式均无需安装客户端模组。

## 玩家操作

### 打开与关闭

使用 `/arcmenu open <菜单标识>` 打开菜单，使用 `/arcmenu close` 关闭。服务器启用主菜单快捷键时，也可按 Shift+F 打开主菜单，菜单已打开时则关闭当前菜单。

Shift+F 使用游戏的潜行与交换副手操作；修改过按键绑定的玩家应使用对应按键。快捷键不会绕过菜单权限。

### 点击按钮

将准星或光标指向按钮的点击区域，再使用菜单配置的操作：

| 操作          | 对应点击类型          |
| ----------- | --------------- |
| 左键          | `left`。         |
| 右键          | `right`。        |
| 潜行时左键       | `shift-left`。   |
| 潜行时右键       | `shift-right`。  |
| 中键，仅鼠标模式    | `middle`。       |
| 潜行时中键，仅鼠标模式 | `shift-middle`。 |

默认潜行键为 Shift。普通左键、右键不会同时触发对应的潜行点击类型。滚轮也不会自动表示菜单翻页；翻页按钮应通过菜单导航动作配置。

按钮是否执行操作取决于其 `backend` 点击区域与动作，显示文字本身不构成按钮。点击类型与重叠规则见[后端交互区域与点击事件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/backend.md)。

### 切换操作方式

以下命令适用于 Paper 系服务端，需要 `arcmenu.use`，并在游戏内执行：

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

第一条查看当前方式与服务器策略，后两条选择对应方式。菜单已打开时，成功切换会应用到当前菜单；尚未打开时，下一次打开使用所选方式。

在允许玩家选择的服务器中，个人选择会保存，重新登录后仍可使用。管理员强制指定方式时，玩家无法选择其他方式。

Spigot 只提供准星操作；`/arcmenu mode` 提示其支持范围，不提供鼠标切换功能。

## 鼠标模式要求

鼠标模式支持 Minecraft Java 版 **1.21.2–1.21.11、26.1.x、26.2 和 26.3 客户端**。这些是玩家客户端版本，不能作为服务端支持范围；服务端与 Java 要求见[运行要求](/arcmenu-wen-dang/ru-men/requirements.md)。

玩家应接受并加载包含 ArcMenu 资源的服务器资源包。菜单仅含文字或原版物品时，鼠标模式也应配套分发资源包。

通过 ViaVersion 连接的玩家仍需使用受支持的客户端，并加载对应资源。能够进入服务器，不代表所有鼠标显示与操作都符合要求。

资源包更新后，应让玩家加载新内容，再检查菜单。资源生成与分发步骤见[安装与更新](https://simple.superiormc.cn/arcmenu-wen-dang/gong-neng-pei-zhi/pages/JfPbYFTL9xk7jR5CbVN6#资源包配置)。

## 服务器设置

以下设置位于 Paper 系服务端的 `plugins/ArcMenu/config.yml`。修改时合并到已有配置节，不要重复添加 `mouse` 或 `shortcuts`。

### 操作策略：`mouse`

```yaml
mouse:
  policy: player-choice
  default: touch
```

| 字段        | 用途                                     |
| --------- | -------------------------------------- |
| `policy`  | 决定由玩家选择还是由服务器统一指定。                     |
| `default` | 玩家尚未保存个人选择时的默认方式，可用 `touch` 或 `mouse`。 |

`policy` 的可用值：

| 值               | 行为                                   |
| --------------- | ------------------------------------ |
| `player-choice` | 允许玩家切换；优先使用个人选择，没有个人选择时使用 `default`。 |
| `force-touch`   | 所有玩家使用触摸模式。                          |
| `force-mouse`   | 所有玩家使用鼠标模式。                          |

修改 `default` 不会覆盖已有个人选择。强制策略生效时，`default` 不决定实际方式。启用 `force-mouse` 前，应确认允许进入服务器的客户端符合要求，并已安排资源包分发。

### 光标外观与灵敏度：`mouse.cursor`

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

| 字段              | 用途                         | 可用范围           |
| --------------- | -------------------------- | -------------- |
| `sensitivity-x` | 光标横向移动灵敏度；数值较大时移动更快。       | `0.05` 至 `50`。 |
| `sensitivity-y` | 光标纵向移动灵敏度。                 | `0.05` 至 `50`。 |
| `clamp-margin`  | 光标与画布边缘之间保留的内侧余量，使用菜单坐标单位。 | 大于或等于 `0`。     |
| `size`          | 光标的显示高度，使用菜单坐标单位。          | 大于 `0`。        |
| `z`             | 光标的前后层次。                   | 有限数值。          |

这组设置控制光标，不改变按钮位置或点击区域。光标图片位于 `plugins/ArcMenu/images/mouse/mouse.png` 与 `choose.png`，后者用于指向交互区域时的状态。

修改光标图片、灵敏度或外观后，执行 `/arcmenu reload all`，并向玩家分发更新后的资源包。使用 CraftEngine 合并资源包时，还需按安装页的步骤重建其资源包。

### 主菜单快捷键：`shortcuts`

```yaml
shortcuts:
  shift-f: true
```

设为 `false` 后，ArcMenu 不再使用 Shift+F 切换菜单，玩家仍可通过命令打开与关闭。主菜单由菜单文件中的 `main-menu: true` 指定；无论快捷键是否启用，都应保留唯一主菜单。

Spigot 也支持这项设置，但应修改 `plugins/ArcMenu/spigot/config.yml`，不应在该文件中添加鼠标设置。

### 两种模式的屏幕位置

Paper 系服务端可在 `offset.yml` 中分别设置 `touch` 与 `mouse` 的屏幕位置。这是整体位置设置，不是按钮布局；字段与坐标说明见[画布、坐标与屏幕位置](https://simple.superiormc.cn/arcmenu-wen-dang/gong-neng-pei-zhi/pages/TdYmoYWGUfFABevgepIK#整体屏幕设置offsetyml)。

只修改操作策略、默认方式或快捷键时，执行 `/arcmenu validate` 和 `/arcmenu reload` 即可。重载会关闭已打开的菜单，重新打开后检查设置。

## 操作异常排查

| 情况              | 检查方法                                           |
| --------------- | ---------------------------------------------- |
| 无法切换鼠标模式        | 确认不是 Spigot，检查服务器是否强制触摸模式，以及提示中是否指出光标资源缺失。     |
| 光标缺失或显示异常       | 确认客户端受支持，并已加载包含 ArcMenu 内容的最新资源包。              |
| 光标移动过快或过慢       | 调整 `mouse.cursor` 灵敏度，并重建、分发资源包后再次测试。          |
| 按钮可以看到，但点击无效    | 确认正常打开菜单而非预览，检查点击区域、点击类型及条件。                   |
| Shift+点击执行了不同操作 | 检查是否处于潜行状态，以及对应 `shift-left`、`shift-right` 配置。 |
| Shift+F 没有打开主菜单 | 检查快捷键设置、主菜单标记、玩家权限和按键绑定。                       |

管理员可在已打开的菜单中执行 `/arcmenu pointer` 查看指向情况；鼠标显示异常时可使用 `/arcmenu pointer debug on`，检查结束后执行 `/arcmenu pointer debug off`。这些命令不适用于 Spigot，权限说明见[命令与权限](/arcmenu-wen-dang/pei-zhi-yu-guan-li/commands-permissions.md)。

继续阅读[图片与资源包](/arcmenu-wen-dang/gong-neng-pei-zhi/resource-packs.md)，了解图片引用、资源生成与分发。