> 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/pei-zhi-yu-guan-li/faq.md).

# 常见问题与故障排查

这里整理了在配置菜单、设置资源包和使用编辑器时最常遇到的问题与解决办法。

## 修改菜单文件后，游戏里没有变化

手动修改 `plugins/ArcMenu/menus/` 下的 YAML 文件后，需要执行 `/arcmenu reload` 让新配置生效；如果在可视化编辑器中修改并点击保存，服务器会自动加载最新内容。

如果执行重载时提示配置校验未通过，插件会保留上一份正常运行的菜单，并把具体的错误文件、字段和原因输出到聊天栏及服务器日志中。你也可以随时执行 `/arcmenu validate` 单独检查所有配置文件。

比如在配置边框（`border`）元素时，几何校验要求边框粗细满足 `2 * thickness < min(width, height)`。如果一个边框的 `width` 是 `2`，而 `thickness` 保持默认的 `1`，就会因为两侧边框贴合占满宽度而报错；此时把 `thickness` 改小（例如 `thickness: 0.5`）即可正常加载，详见[前端元素类型](/cai-dan-pei-zhi/menus/frontend.md)。

## 玩家打不开菜单

要打开一个菜单，玩家需要同时拥有默认的 `arcmenu.use` 权限和该菜单中配置的 `permission` 权限。

同时请留意玩家当前所处的状态：在地面跳跃的过程中，普通菜单会在玩家落地后打开；处于创造模式、旁观模式或拥有飞行能力的玩家则可以在空中直接打开。打开菜单后，如果玩家发生实际移动、传送或死亡，当前界面会自动关闭以释放视角。

## 按 Shift+F 没有打开主菜单

请按以下两点检查：

1. 打开 `config.yml`，确认 `shortcuts.shift-f` 设为了 `true`。
2. 检查 `plugins/ArcMenu/menus/` 下的菜单文件，确认其中有且仅有一份菜单在根部配置了 `main-menu: true`。

Shift+F 对应游戏内的“潜行 + 交换副手物品”按键；如果玩家在客户端按键设置里修改了这两个键位，则需要按下修改后的对应按键。此外，按 Shift+F 关闭菜单由 `shortcuts.close-on-shift-f` 独立控制，按空格键关闭菜单由 `shortcuts.close-on-space` 控制。

## 按钮画面显示正常，但是点不到

ArcMenu 采用前后端分离的设计：`frontend` 负责画面显示，`backend` 负责定义可点击的交互区域。

如果按钮点不到，请检查 `backend` 中对应区域（region）的中心坐标 `offset` 和宽高尺寸是否与前端按钮对齐，并确认 `events` 下配置的是左键（`left`）、右键（`right`）还是 Shift 组合点击（如 `shift-left`）。当多个点击区域发生重叠时，`priority`（优先级）数值更大的区域会优先响应。管理员可以在游戏内执行 `/arcmenu preview <菜单ID> backend`，直观地看到所有点击区域的实际位置和大小。

## 图片不显示，或者显示的还是修改前的旧图

首先核对图片元素的 `source` 路径是否与 `plugins/ArcMenu/images/` 下的实际文件路径一致。例如 `source: '/ui/logo.png'` 对应的是 `plugins/ArcMenu/images/ui/logo.png`。

确认路径无误后，新增或替换图片需要重新构建并加载资源包：

* 先执行 `/arcmenu resources` 或 `/arcmenu reload all` 重建 ArcMenu 资源。
* 如果使用了自定义物品插件合包，接着按所用的插件执行 `/ce reload pack`（或 `/ce reload all`）、`/nexo reload pack` 或 `/iazip`，并让客户端重新加载更新后的资源包。
* 如果玩家使用的是手动放入客户端的本地资源包，需要把 `plugins/ArcMenu/generated/` 下新生成的 ZIP 包替换到客户端中。

## 开启光影包时应该使用哪种模式

在开启光影（Shader Pack）游玩时，推荐以下两种方式：

* **Vision 模式**：玩家在客户端安装与自身游戏版本对应的 **ArcMenu Editor** 模组后，可以执行 `/arcmenu mode vision` 切换到 Vision 模式。Vision 已经内置在 Editor 模组中，无需额外安装其他鼠标模组，在开启光影时依然拥有客户端即时移动的本地光标、固定 FOV、明亮的物品显示，并且菜单不会被世界中的方块或实体遮挡。
* **触控模式（Touch）**：在不安装任何客户端模组的情况下，可以执行 `/arcmenu mode touch` 使用触控模式。触控模式完全采用原版展示实体渲染，不启用 ArcMenu 的光照、深度或 FOV 着色器，与各类光影包天然兼容。

此外，Effect 过场动画也采用原版固定相机渲染，观看时不依赖 Mouse 着色器。

## 鼠标光标缺失、无法切换 Vision 或位置异常

如果 Mouse 模式下看不到光标，请确认客户端已成功加载包含 ArcMenu 内容的最新资源包。如果你修改过 `config.yml` 中的光标配置或更换了 `images/mouse/` 下的光标贴图，需要重新生成并分发资源包。

如果提示无法切换到 Vision 模式，请确认客户端已安装与当前游戏版本匹配的 **ArcMenu Editor** 模组并重启客户端完成加载；排查问题时建议将插件与 Editor 模组一并更新到最新版本。

管理员需要排查光标指向坐标或渲染状态时，可以在打开菜单后执行 `/arcmenu pointer` 查看指向信息，或执行 `/arcmenu pointer debug on` 开启实时诊断（执行 `/arcmenu pointer debug off` 关闭）。

## 客户端手动装包后，Mouse 菜单发暗或被方块遮挡

当玩家没有通过服务端下发资源包，而是自己把生成的资源包放进客户端 `resourcepacks` 文件夹手动启用时，服务端通常不会收到资源包加载成功的回执。

此时请检查 `config.yml` 中的 `mouse.assume-resource-pack-loaded`：

* 将其保持为默认的 **`true`**，即可让 Mouse 模式在没有服务端回执的情况下直接启用平面光照、菜单深度、固定 FOV、本地光标和本地 GIF。修改配置后执行 `/arcmenu reload` 并重新打开菜单即可恢复明亮显示与遮挡隔离。
* 如果将其设为了 **`false`**，则必须通过服务端资源包分发流程（如服务端 `server.properties`、CraftEngine、Nexo 或 ItemsAdder 自动发包）让服务器收到加载成功的回执，相关效果才会开启。

## Vision 模式下按 Space 关闭菜单时，角色会跟着跳一下吗

不会。在 Vision 模式下按空格键关闭菜单时，客户端会直接消费掉这次跳跃键的按下、重复和释放事件，不会把跳跃指令继续传给游戏角色。是否允许按空格关闭菜单，依然由 `config.yml` 中的 `shortcuts.close-on-space` 控制；而在进行文本输入期间，按空格键只会正常输入空格字符。

## 菜单里的占位符没有替换成实际数值

ArcMenu 内置占位符的完整写法可参考[占位符与文字格式](/wen-zi-ge-shi/text-placeholders.md)。如果使用的是第三方插件的占位符（如 `%vault_eco_balance%`、`%player_level%` 等），请确认服务器已安装 **PlaceholderAPI**，并且已经下载注册了对应的 PAPI 扩展（例如通过 `/papi ecloud download Player` 与 `/papi reload` 安装）。

如果希望菜单在打开期间定时刷新占位符内容，可以为对应的文字或图片元素配置 `update` 刷新间隔，或者在动作与管理命令中使用刷新指令。

## 单行文字修改 alignment 的 left、right 没有位置变化

在文字元素（`text`）中，`offset` 决定的是整个文字块的中心坐标，而 `alignment`（`left`、`center`、`right`）控制的是多行文本段落内部各行之间的对齐方式。当文字只有单独一行时，切换段落内对齐方式不会改变这行字中心点的位置。如果你想把单行文字往左或往右移动，直接调整它的 `offset.x` 坐标即可，详见[前端元素类型](/cai-dan-pei-zhi/menus/frontend.md)。

## 不同 Z 轴深度的背景与文字在画面边缘错位

在默认的透视模式下，Z 值更大（更靠近玩家镜头）的图层会因为近大远小的透视关系显得略微放大，越靠近屏幕四周边缘，不同 Z 层之间的视觉偏移就越明显。

如果你制作的是平面 UI 菜单，希望不同图层在任何位置都严丝合缝地对齐，可以在菜单的 `canvas` 下配置 `depth-mode: layered`。开启分层深度模式后，不同 Z 轴的图层会保持视觉尺寸与位置对齐，同时倾斜平面和 3D 物品依然保留自身的立体感，详见[画布、坐标与屏幕位置](/cai-dan-pei-zhi/menus/canvas.md)。

## 条件里的“数量 × 单价”怎么直接计算

条件表达式原生支持算术运算与比较。你可以直接在 `condition` 中写出算式，例如：

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

如果需要在前端文字或动作参数里直接显示计算后的数值，可以使用 `{math: ...}` 表达式（例如 `{math: {meta:input-x} * 24}`）。支持的所有运算符与数学函数见[数学表达式](/cai-dan-pei-zhi/menus/math-expressions.md)。

## 可视化编辑器打不开，或保存时提示异常

* **无法打开编辑器**：请确认客户端安装了与当前 Minecraft 版本匹配的 **ArcMenu Editor** 模组以及前置 **Fabric API**，并且你的账号拥有 `arcmenu.admin` 权限。若遇到连接或协议提示，请将服务端插件与客户端 Editor 模组更新到最新版本。进入服务器后可执行 `/arcmenu edit <菜单ID>` 打开菜单编辑器，或执行 `/arcmenu projects` 打开项目管理器。
* **提示编辑文字或数据包过长**：编辑器单个文本字段的传输上限为 **256 KiB**，单次完整逻辑数据包的上限为 **1 MiB**（均按 UTF-8 字节数计算）。需要注意，整个动作配置块可能会作为一个整体字段传输，因此体积按整个块的内容计算。报错提示中会明确列出超限的具体字段名称、当前字节大小与上限值，按提示精简或拆分即可，详见[可视化编辑器](/gong-neng-pei-zhi/editor.md)。
* **保存时提示文件已发生变化**：说明在你打开编辑器期间，服务器上的这份菜单 YAML 文件被其他管理员或外部文本编辑器修改并重载过了。为了防止覆盖他人的修改，此时只需重新打开一次该菜单即可继续编辑；保存前的历史版本也会自动保存在 `plugins/ArcMenu/backup-menu/` 中。

## 菜单市场如何登录与下载作品

当你打开可视化编辑器或项目管理器时，客户端会自动使用当前登录的**正版 Minecraft 账号**完成市场会话验证。验证状态会直接显示在市场界面中，若遇到网络波动可点击界面内的重试按钮。

将市场中的作品安装到服务器需要拥有 `arcmenu.admin` 权限。除了在市场界面中点击安装外，管理员也可以在游戏内或服务器控制台直接执行 `/arcmenu download pack <包ID> [版本]` 完成下载与安装。


---

# 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/pei-zhi-yu-guan-li/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.