> 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/ru-men/install.md).

# 安装与更新

## 安装插件

先关闭服务端，将下载好的 ArcMenu 插件 JAR 放入服务端的 `plugins/` 目录，然后启动服务器。

首次启动时，插件会在 `plugins/ArcMenu/` 下生成 `config.yml`、语言文件、图片资源以及一套开箱即用的默认菜单（包含 `main` 主菜单、`start`、`cursor-setting` 光标设置、商店分类、`teleport` 传送示例，以及 `rtp-overworld`、`rtp-nether`、`rtp-end` 三个随机传送 Effect 示例）。如果你后续删除了某些自带的示例菜单、图片或动画，插件在重启、重载或升级时会尊重你的修改，不会把已删除的示例文件重新释放出来。

进入游戏后，输入以下命令即可打开默认主菜单：

```
/arcmenu open main
```

在默认配置下，玩家在游戏里直接按 **Shift+F**（副手交换键）就能唤出主菜单；当菜单或应用处于打开状态时，再按一次 **Shift+F** 或按下 **Space**（跳跃键）即可关闭（菜单与应用各自的 `close-on-shift-f` 和 `close-on-space` 均独立默认为 `true`），也可以随时执行 `/arcmenu close`。为了保证视角与屏幕平面稳定，玩家在跳跃腾空时请求打开菜单会等待落地后自动展开；处于创造模式、旁观模式或拥有飞行能力的玩家则可以在空中直接打开。

要打开某个菜单，玩家需要同时拥有默认的 `arcmenu.use` 权限和该菜单自身配置的权限。各类重载、校验与编辑命令则由 `arcmenu.admin` 权限控制，默认已授予服务器 OP。

## 配置资源包

当菜单中用到了图片、GIF 动图、自定义提示框外观，或者玩家使用 **Mouse（鼠标）模式** 时，客户端需要加载包含 ArcMenu 资源的材质包。

### 与自定义物品插件自动合包

如果服务器上安装了 **CraftEngine**、**Nexo** 或 **ItemsAdder**，ArcMenu 会在这些插件构建资源包时自动把生成的图片、字体和着色器合入进去，无需手动复制文件夹：

1. 当你在 `plugins/ArcMenu/images/` 中新增或替换图片后，先执行 `/arcmenu resources`（或 `/arcmenu reload all`）重建 ArcMenu 自身的资源。
2. 根据你使用的插件，执行对应的打包命令完成合并与分发：
   * **CraftEngine**：执行 `/ce reload pack`（或 `/ce reload all`）。
   * **Nexo**：执行 `/nexo reload pack`。
   * **ItemsAdder**：执行 `/iazip`。

通过客户端编辑器里的项目管理器安装 ArcPack 资源包或修改工作区资源时，服务端会自动请求重建资源包（若同时安装了多个插件，自动触发顺序依次为 CraftEngine、Nexo、ItemsAdder）。多插件共存时，建议在服务端只保留其中一个插件负责向玩家最终发送资源包。

### 独立分发或客户端手动安装

如果服务器没有使用上述资源包管理插件，可以在修改资源后执行：

```
/arcmenu reload all
```

插件会将打包好的完整资源包输出到以下位置：

```
plugins/ArcMenu/generated/arcmenu-resourcepack.zip
```

你可以将这个 ZIP 文件上传到自己的资源包托管地址并在服务端 `server.properties` 中配置分发，也可以直接发给玩家放进客户端的 `resourcepacks/` 目录手动启用。

`config.yml` 中的 `mouse.assume-resource-pack-loaded` 默认设为 `true`。这意味着只要玩家客户端手动装好了匹配的 ArcMenu 资源包，即使服务端没有收到资源包下载回执，Mouse 模式也会正常启用固定视角、平面光照、本地光标以及客户端本地 GIF 播放。如果你希望严格以服务端的资源包加载成功回执为准，可以将该项改为 `false`（详见[图片与资源包](/gong-neng-pei-zhi/resource-packs.md)）。

## 日常修改与重载

在制作和调整菜单的过程中，可以根据修改的内容选择对应的生效方式：

| 你所做的操作                             | 让修改生效的方式                 |
| ---------------------------------- | ------------------------ |
| 修改菜单 YAML、动画、语言文件或 `config.yml`    | 执行 `/arcmenu reload`     |
| 在 `menus/` 下新建空白 `.yml` 文件自动生成画布骨架 | 执行 `/arcmenu reload`     |
| 在 ArcMenu Editor 可视化编辑器中点击保存       | 保存后立即更新，重新打开该菜单即可看到新画面   |
| 仅重新生成 ArcMenu 的资源包文件               | 执行 `/arcmenu resources`  |
| 重载全部配置文件并同时重新生成资源包                 | 执行 `/arcmenu reload all` |
| 检查所有菜单配置是否存在语法或字段错误（不写入文件）         | 执行 `/arcmenu validate`   |

每次执行重载时，ArcMenu 都会先校验配置文件的格式与字段。如果某个文件填写有误，插件会在后台与聊天栏指出具体错误位置，同时在内存中保留上一份正常的菜单状态，不会导致正在运行的菜单崩溃。

## 更新插件与编辑器

升级版本时，建议先备份 `plugins/ArcMenu/` 目录，随后关闭服务端，用新版本的插件 JAR 替换旧文件并重新启动。

启动或重载时，插件会自动向 `config.yml` 补齐新版本增加的配置项，同时完整保留你原有的配置值（包括显式填写的 `false`、`0`、空字符串与空列表）、自定义键名和文件注释。

更新服务端后：

* 如果新版更新了内置着色器或图片资源，请按上文步骤重新生成并更新客户端资源包。
* 使用编辑器的管理员以及启用 **Vision 模式** 的玩家，请前往 [ArcMenu Editor 发布页](https://github.com/FENTAIIII/ArcMenu-Editor/releases) 下载与当前游戏客户端版本匹配的最新版模组 JAR，替换客户端 `mods/` 目录中的旧文件后重启游戏。


---

# 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/ru-men/install.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.