> 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-wiki/feature-configuration/input-modes.md).

# Touch and mouse input

ArcMenu offers touch mode (`touch`) and mouse mode (`mouse`). Both use the same menus, buttons and hit regions. You do not need separate menus for each mode.

| Mode  | How to target a button                                   | Servers                                 | Resource pack                                     |
| ----- | -------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |
| Touch | Turn your view, aim the crosshair at a button and click. | Paper, Folia, Leaf and Spigot.          | Input itself needs no pack; menu images still do. |
| Mouse | Move the menu cursor onto a button and click.            | Paper, Folia, Leaf and similar servers. | Load the accompanying pack.                       |

Touch mode means aiming with your view; it does not require a touchscreen. Ordinary players need no client mod for either mode.

## Player controls

### Opening and closing

Use `/arcmenu open <menu-id>` to open a menu and `/arcmenu close` to close it. When the server enables the main-menu shortcut, Shift+F opens the main menu or closes the currently open menu.

Shift+F uses the game's sneak and swap-offhand controls. Players with custom bindings should use their corresponding keys. The shortcut does not bypass menu permissions.

### Clicking buttons

Point the crosshair or cursor at the button's hit region, then use the configured input:

| Input                                        | Click type      |
| -------------------------------------------- | --------------- |
| Left-click                                   | `left`.         |
| Right-click                                  | `right`.        |
| Left-click while sneaking                    | `shift-left`.   |
| Right-click while sneaking                   | `shift-right`.  |
| Middle-click, mouse mode only                | `middle`.       |
| Middle-click while sneaking, mouse mode only | `shift-middle`. |

Shift is the default sneak key. Ordinary left and right clicks do not also trigger their sneaking counterparts. Scrolling does not automatically turn menu pages; configure page buttons with navigation actions.

Button behavior comes from its `backend` region and actions. Visible text alone is not an interactive button. See [Backend regions and click events](/arcmenu-wiki/menu-configuration/menus/backend.md) for click types and overlap rules.

### Switching modes

These commands require `arcmenu.use`, must be run in-game and are available on Paper-family servers:

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

The first shows the current mode and server policy. The other two select a mode. A successful switch applies to a currently open menu; otherwise, it applies the next time a menu opens.

On servers allowing player choice, personal preferences are saved across reconnects. A server-enforced policy prevents choosing a different mode.

Spigot provides only crosshair input. `/arcmenu mode` reports that limitation and does not offer mouse switching.

## Mouse mode requirements

Mouse mode supports Minecraft Java Edition **1.21.2–1.21.11, 26.1.x, 26.2 and 26.3 clients**. These are player client versions, not the server support range. See [Requirements](/arcmenu-wiki/getting-started/requirements.md) for server and Java requirements.

Players should accept and load a server resource pack containing ArcMenu resources. Supply the accompanying pack for mouse mode even when the menu uses only text or vanilla items.

Players connecting through ViaVersion still need a supported client and the corresponding resources. Being able to join does not establish compatibility with all mouse display and input features.

After updating the pack, have players load the new content before checking menus. See [Installation and updates](/arcmenu-wiki/getting-started/install.md#resource-pack-configuration) for generation and distribution steps.

## Server settings

These settings belong in `plugins/ArcMenu/config.yml` on Paper-family servers. Merge changes into existing sections rather than adding duplicate `mouse` or `shortcuts` keys.

### Input policy: `mouse`

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

| Field     | Purpose                                                              |
| --------- | -------------------------------------------------------------------- |
| `policy`  | Determines whether players choose a mode or the server enforces one. |
| `default` | Mode for players without a saved preference: `touch` or `mouse`.     |

Available `policy` values:

| Value           | Behavior                                                                      |
| --------------- | ----------------------------------------------------------------------------- |
| `player-choice` | Allows switching; uses the personal preference if saved, otherwise `default`. |
| `force-touch`   | Uses touch mode for every player.                                             |
| `force-mouse`   | Uses mouse mode for every player.                                             |

Changing `default` does not replace saved preferences. Under an enforced policy, `default` does not determine the active mode. Before enabling `force-mouse`, confirm that allowed clients meet the requirements and arrange pack distribution.

### Cursor appearance and sensitivity: `mouse.cursor`

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

| Field           | Purpose                                                                      | Range             |
| --------------- | ---------------------------------------------------------------------------- | ----------------- |
| `sensitivity-x` | Horizontal cursor sensitivity; larger values move faster.                    | `0.05` to `50`.   |
| `sensitivity-y` | Vertical cursor sensitivity.                                                 | `0.05` to `50`.   |
| `clamp-margin`  | Inset kept between the cursor and the canvas edge, in menu coordinate units. | At least `0`.     |
| `size`          | Cursor display height, in menu coordinate units.                             | Greater than `0`. |
| `z`             | Cursor depth ordering.                                                       | A finite number.  |

These settings affect the cursor, not button placement or hit regions. Cursor images are in `plugins/ArcMenu/images/mouse/mouse.png` and `choose.png`; the latter is used when pointing at an interactive region.

After changing cursor images, sensitivity or appearance, run `/arcmenu reload all` and distribute the updated pack. When using CraftEngine to merge packs, rebuild its pack following the installation page as well.

### Main-menu shortcut: `shortcuts`

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

Setting this to `false` stops ArcMenu from toggling menus with Shift+F. Commands remain available for opening and closing. The menu's `main-menu: true` selects the main menu; retain exactly one main menu whether the shortcut is enabled or not.

Spigot also supports this setting in `plugins/ArcMenu/spigot/config.yml`. Do not add mouse settings to that file.

### Screen placement for each mode

Paper-family servers can configure separate `touch` and `mouse` screen placements in `offset.yml`. These settings move the entire screen rather than individual buttons. See [Canvas, coordinates and screen placement](/arcmenu-wiki/menu-configuration/menus/canvas.md#screen-placement-offsetyml) for fields and coordinates.

Changes only to policy, default mode or the shortcut need `/arcmenu validate` followed by `/arcmenu reload`. Reloading closes open menus; reopen them to check the settings.

## Troubleshooting input

| Symptom                                    | What to check                                                                                                                    |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Cannot switch to mouse mode                | Confirm the server is not Spigot, check whether touch mode is enforced and whether the message reports missing cursor resources. |
| Missing or incorrect cursor                | Confirm a supported client and the latest loaded resource pack containing ArcMenu content.                                       |
| Cursor moves too quickly or slowly         | Adjust `mouse.cursor` sensitivity, rebuild and distribute the pack, then test again.                                             |
| A visible button does not respond          | Open the menu normally rather than in preview; check the hit region, click type and conditions.                                  |
| Shift+click performs a different operation | Check sneaking state and the configured `shift-left` or `shift-right` actions.                                                   |
| Shift+F does not open the main menu        | Check the shortcut setting, main-menu marker, permissions and key bindings.                                                      |

Administrators can run `/arcmenu pointer` in an open menu to inspect targeting. For mouse display issues, use `/arcmenu pointer debug on`, then `/arcmenu pointer debug off` when finished. These commands are unavailable on Spigot; see [Commands and permissions](/arcmenu-wiki/configuration-and-administration/commands-permissions.md) for access requirements.

Continue with [Images and resource packs](/arcmenu-wiki/feature-configuration/resource-packs.md) for image references, resource generation and distribution.