> 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/en/configuration-and-administration/faq.md).

# FAQ and troubleshooting

This page covers common questions and solutions when configuring menus, setting up resource packs, and working with the visual editor.

## Menu file changes do not show up in game

After editing YAML files in `plugins/ArcMenu/menus/` by hand, run `/arcmenu reload` to apply your changes. When you edit and save a menu inside the visual editor, the server loads the updated menu automatically.

If a configuration fails validation during reload, ArcMenu keeps the previous working version of the menu active and prints the exact file, field, and reason for the failure to chat and the server log. You can also run `/arcmenu validate` at any time to check all configuration files.

For example, `border` elements require `2 * thickness < min(width, height)`. If a border has `width: 2` and keeps the default `thickness: 1`, the two opposite sides touch and leave no interior space, causing validation to fail. Lowering `thickness` (for instance, `thickness: 0.5`) resolves the error; see [Frontend element types](/en/menu-configuration/menus/frontend.md).

## Players cannot open a menu

To open a menu, a player needs both the default `arcmenu.use` permission and any `permission` configured on that menu.

Player movement state also matters: if a player jumps on the ground, normal menus wait until the player lands before opening. Players who are flying, or who are in Creative or Spectator mode, can open menus while airborne. Once a menu is open, physically moving, teleporting, or dying closes the interface automatically so the player regains camera control.

## Pressing Shift+F does not open the main menu

Check these two settings:

1. Open `config.yml` and confirm that `shortcuts.shift-f` is set to `true`.
2. Check the menu files in `plugins/ArcMenu/menus/` and make sure exactly one menu has `main-menu: true` set at its root.

Shift+F corresponds to the in-game Sneak + Swap Item With Offhand keybinds; if a player has rebound either action in their client controls, they should press their custom keys instead. Closing an open menu with Shift+F is controlled separately by `shortcuts.close-on-shift-f`, and closing with Space is controlled by `shortcuts.close-on-space`.

## A button looks fine on screen, but clicking it does nothing

ArcMenu separates visual presentation from click detection: `frontend` draws the elements on screen, while `backend` defines the clickable regions.

If a button does not respond to clicks, check that the corresponding region in `backend` has its center `offset`, `width`, and `height` aligned with the frontend button, and verify whether `events` is listening for `left`, `right`, or a Shift combination such as `shift-left`. When multiple regions overlap, the region with the higher `priority` value handles the click. Administrators can run `/arcmenu preview <menu-id> backend` in game to visualize the exact position and bounds of every click region.

## An image is missing or still shows the old version

First, verify that the image element's `source` path matches the actual file path inside `plugins/ArcMenu/images/`. For example, `source: '/ui/logo.png'` points to `plugins/ArcMenu/images/ui/logo.png`.

Once the path is confirmed, rebuild and reload the resource pack whenever you add or replace images:

* Run `/arcmenu resources` or `/arcmenu reload all` to rebuild ArcMenu's assets.
* If you merge packs through a custom item plugin, run `/ce reload pack` (or `/ce reload all`), `/nexo reload pack`, or `/iazip`, then have the client reload the updated resource pack.
* If players use a manually installed local resource pack, replace the ZIP file in the client's `resourcepacks` folder with the newly generated archive from `plugins/ArcMenu/generated/`.

## Which input mode should I use with shader packs?

When playing with shader packs enabled, two modes work best:

* **Vision mode**: Players with the matching **ArcMenu Editor** mod installed for their client version can switch to Vision mode using `/arcmenu mode vision`. Vision is built right into the Editor mod—no separate mouse mod is required—and provides an instant local cursor, fixed FOV, bright item rendering, and menu rendering that is never occluded by world blocks or entities, even with shaders active.
* **Touch mode**: For players without client mods, run `/arcmenu mode touch`. Touch mode renders purely with vanilla display entities without activating ArcMenu's lighting, depth, or FOV shaders, so it works naturally with any shader pack.

Effect cutscenes also use a vanilla fixed camera and do not rely on Mouse shaders.

## The mouse cursor is missing, Vision will not enable, or cursor alignment is off

If the cursor does not appear in Mouse mode, make sure the client has loaded the latest resource pack containing ArcMenu's assets. Whenever you change cursor settings in `config.yml` or replace textures under `images/mouse/`, regenerate and redistribute the resource pack.

If a player cannot switch to Vision mode, confirm that they have installed the matching **ArcMenu Editor** mod for their Minecraft version and restarted the client. Keeping both the server plugin and the client Editor mod on current matching releases is recommended.

To inspect cursor coordinates or rendering state while a menu is open, administrators can run `/arcmenu pointer` to view hit-test details, or `/arcmenu pointer debug on` to enable live diagnostics (`/arcmenu pointer debug off` turns them off).

## Mouse menus look dark or get blocked by terrain when using a manually installed resource pack

When players drop the generated resource pack into their client's `resourcepacks` folder manually instead of receiving it from the server, the server does not receive a pack-loaded receipt from the client.

Check `mouse.assume-resource-pack-loaded` in `config.yml`:

* Keep it set to the default **`true`** so Mouse mode enables flat lighting, menu depth, fixed FOV, the local cursor, and local GIFs immediately without waiting for a server receipt. After changing the setting, run `/arcmenu reload` and reopen the menu.
* If it is set to **`false`**, you must distribute the pack through the server (via `server.properties`, CraftEngine, Nexo, or ItemsAdder) so the server receives a load confirmation before activating those effects.

## Does pressing Space to close a menu in Vision mode make the player jump?

No. When you press Space to close a menu in Vision mode, the client consumes the jump key's press, repeat, and release events so no jump input reaches your character. Whether Space closes menus is still controlled by `shortcuts.close-on-space` in `config.yml`, and pressing Space while typing in an Arcitx text field simply enters a space character.

## Placeholders in menus are not replaced with values

See [Placeholders and text formatting](/en/text-formatting/text-placeholders.md) for the syntax of ArcMenu's built-in placeholders. If you are using placeholders from third-party plugins (such as `%vault_eco_balance%` or `%player_level%`), make sure **PlaceholderAPI** is installed and that the required PAPI expansions are downloaded and registered (for example, `/papi ecloud download Player` followed by `/papi reload`).

To refresh placeholder values periodically while a menu stays open, set an `update` interval on the text or image element, or trigger a refresh from an action or admin command.

## Changing `alignment` between `left` and `right` does not move a single line of text

On a `text` element, `offset` sets the center point of the entire text block, while `alignment` (`left`, `center`, `right`) controls how multiple lines align relative to each other inside a paragraph. When a text element contains only one line, changing paragraph alignment does not shift its center position. To move a single line of text left or right, adjust its `offset.x` coordinate; see [Frontend element types](/en/menu-configuration/menus/frontend.md).

## Backgrounds and text at different Z depths do not line up near screen edges

In the default perspective mode, layers with a larger Z value (closer to the camera) appear slightly larger due to perspective foreshortening, which becomes more noticeable toward the edges of the screen.

If you are building a flat UI where layers at different Z depths should stay aligned across the entire canvas, set `depth-mode: layered` under `canvas`. Layered depth keeps flat layers visually aligned in both size and position while preserving 3D perspective for tilted planes and 3D items; see [Canvas, coordinates and screen position](/en/menu-configuration/menus/canvas.md).

## How do I calculate `quantity × unit price` inside a condition?

Condition expressions evaluate arithmetic and comparisons directly, so you can write the formula right inside `condition`:

```yaml
condition: '%vault_eco_balance% >= {meta:input-x} * 24'
```

To display a calculated result in frontend text or pass it into an action parameter, wrap the formula in `{math: ...}` (for example, `{math: {meta:input-x} * 24}`). See [Math expressions](/en/menu-configuration/menus/math-expressions.md) for all supported operators and functions.

## The visual editor will not open or reports an error when saving

* **Editor will not open**: Make sure your client has both **Fabric API** and the matching **ArcMenu Editor** mod for your Minecraft version installed, and that your account has the `arcmenu.admin` permission. If you see a connection or protocol message, update both the server plugin and the client Editor mod to current matching builds. Once in game, run `/arcmenu edit <menu-id>` to open the menu editor or `/arcmenu projects` to open the project manager.
* **Oversized text or packet message**: A single editor text field can transfer up to **256 KiB**, and a complete logical packet can transfer up to **1 MiB** (measured in UTF-8 bytes). Because an entire action configuration block can be transmitted as a single field, its size is measured across the whole block rather than a single line. The error message names the exact field, its byte size, and the limit so you can trim or split the content; see [Visual editor](/en/feature-configuration/editor.md).
* **File changed on disk message when saving**: Another administrator or an external text editor modified and reloaded the menu's YAML file on the server while you had it open in the editor. Reopen the menu to load the latest version and continue editing; pre-save backups are also stored automatically in `plugins/ArcMenu/backup-menu/`.

## How marketplace login and downloads work

When you open the visual editor or project manager, the client automatically verifies your marketplace session using your active **authenticated Minecraft account**. The marketplace screen displays your login status and provides a retry button if a network hiccup occurs.

Installing marketplace packages onto the server requires `arcmenu.admin`. In addition to clicking install inside the marketplace UI, administrators can run `/arcmenu download pack <pack-id> [version]` in game or from the server console.


---

# 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/en/configuration-and-administration/faq.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.