> 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/compatibility.md).

# 平台与插件兼容性

ArcMenu 可以直接融入现有的服务器架构中，与常见的服务端核心、自定义物品插件、经济系统和跨版本组件协同工作。

## 服务端平台

Paper、Leaf、Folia、Purpur 等 Paper 系服务端共用同一个插件 JAR 与 `plugins/ArcMenu/` 配置目录，并支持 ArcMenu 的全部功能。在 Folia 上，插件会自动遵循区域化的线程调度规则，将玩家与展示实体的操作绑定在各自所属的区域线程上安全执行。

Spigot 支持触控菜单和基础交互。Paper、Leaf、Folia、Purpur 与 Spigot 的功能对比如下：

| 功能模块                                 | Paper / Leaf / Folia / Purpur | Spigot |
| ------------------------------------ | ----------------------------- | ------ |
| 文字、矩形、边框、线条、原版物品与方块                  | 支持                            | 支持     |
| 左键、右键、Shift 组合点击、命令动作与菜单导航           | 支持                            | 支持     |
| Shift+F 打开主菜单与 Space/Shift+F 关闭快捷键   | 支持                            | 支持     |
| 图片、GIF 动图与自动资源包构建                    | 支持                            | 不支持    |
| Mouse 模式、Vision 模式、本地光标与固定 FOV       | 支持（Vision 需安装配套 Editor 模组）    | 不支持    |
| 悬浮提示框（Tooltip）、菜单动画与 Effect 过场动画     | 支持                            | 不支持    |
| CraftEngine、Nexo、ItemsAdder 自定义物品与合包 | 支持                            | 不支持    |
| 可视化编辑器、项目管理器与菜单市场                    | 支持                            | 不支持    |

关于服务端环境与 Java 版本的对应关系，请查看[运行要求](/ru-men/requirements.md)。

## 自定义物品与资源包插件（CraftEngine / Nexo / ItemsAdder）

ArcMenu 原生支持与 **CraftEngine**、**Nexo** 和 **ItemsAdder** 联动，既可以在菜单里直接展示这些插件的自定义物品模型，也可以将 ArcMenu 的资源自动合并进它们的资源包中。

### 在菜单中使用自定义物品

在前端 `type: item` 元素的 `material` 字段中，直接填写对应插件的物品标识即可：

* **CraftEngine**：填写 `命名空间:物品ID`（例如 `myitems:ruby_sword`），或加上显式前缀 `craftengine:命名空间:物品ID`。未带插件前缀的自定义命名空间 ID 默认按 CraftEngine 物品解析。
* **Nexo**：填写 `nexo:物品ID`（例如 `nexo:magic_staff`）。
* **ItemsAdder**：填写 `ia:命名空间:物品ID` 或 `itemsadder:命名空间:物品ID`（例如 `ia:custom:golden_key`）。

如果服务器同时安装了多个自定义物品插件且存在同名物品，建议使用带显式前缀的写法。搭配 `context: GUI` 可以按物品栏图标的平面朝向展示模型，更多展示角度与缩放配置见[前端元素类型](/cai-dan-pei-zhi/menus/frontend.md)。如果插件启动时自定义物品尚未加载完毕，ArcMenu 会在物品插件就绪后自动重试并完成菜单加载。

### 自动合并资源包

这三款插件都可以直接合并 ArcMenu 生成的图片、GIF、光标和着色器资源，不需要你手动复制文件夹或修改它们自身的配置文件：

* **Nexo** 会通过资源包生成前事件自动合入 ArcMenu 资源。
* **ItemsAdder** 会通过合包事件接收资源，同时完整保留原有的包元数据与 `overlays` 结构。
* **CraftEngine** 会在构建资源包时直接合入 ArcMenu 的输出。

当你新增或修改了菜单图片、GIF 后，先执行 `/arcmenu resources` 或 `/arcmenu reload all` 更新 ArcMenu 资源，再按你使用的插件执行对应的重载命令即可完成合包与分发：

* CraftEngine：`/ce reload pack`（或 `/ce reload all`）
* Nexo：`/nexo reload pack`
* ItemsAdder：`/iazip`

在项目管理器中导入或修改工作区资源时，插件也会自动请求重建资源包（同时安装多个插件时，自动触发优先级依次为 CraftEngine、Nexo、ItemsAdder；手动执行各插件的重载命令时均会正常合入）。如果服务器同时安装了多款自定义内容插件，请只配置其中一款插件负责向玩家最终发送资源包。此外，在导出 ArcPack 项目时勾选 `allowCe` 选项，也会一并允许包含 Nexo 和 ItemsAdder 的物品引用。

详细的资源包配置说明见[图片与资源包](/gong-neng-pei-zhi/resource-packs.md)。

## PlaceholderAPI

安装 PlaceholderAPI 并下载对应的扩展后，你可以在菜单文字、提示框、图片路径、物品材质以及条件和动作中直接使用来自其他插件的占位符（如金币余额、点券、等级、公会名称或任务进度）。ArcMenu 内置的玩家信息、坐标、光标偏好和菜单数据占位符无需额外依赖即可直接使用。

## Vault 与 PlayerPoints

* **Vault**：搭配任意支持 Vault 的经济插件（如 EssentialsX、CMI 等）使用时，可以在菜单条件中判断玩家余额，并通过动作直接增加、扣除或设置金币。
* **PlayerPoints**：支持在菜单中直接判断、增加、扣除或设置玩家的固定点券。

把占位符展示、条件判断和经济动作组合起来，就能直接做出商店、付费传送或强化界面，具体配置写法见[进阶动作](/cai-dan-pei-zhi/menus/advanced-actions.md)。

## 跨版本与客户端渲染（ViaVersion / 光影兼容）

当服务器安装 **ViaVersion** 允许不同版本的客户端进入时，ArcMenu 会读取每位玩家的实际客户端协议版本，自动为不同版本的客户端匹配对应的鼠标模式资源。

在客户端渲染与光影兼容性方面，三种操作模式与过场动画各自采用适合的渲染方式：

* **触控模式（Touch）**：无需安装客户端模组，完全使用原版展示实体渲染，遵循玩家当前视野（FOV）与世界方块遮挡，不加载或启用着色器资源，开启任何光影包都能保持正常的游戏画面。
* **鼠标模式（Mouse）**：无需安装客户端模组，配合配套资源包即可获得客户端本地光标、固定 FOV、菜单深度与平面光照体验。
* **Vision 模式**：玩家在客户端安装与自身游戏版本对应的 **ArcMenu Editor** 模组后即可启用。Vision 已经集成在同一个 Editor 模组中，直接提供客户端本地光标与独立的菜单画面渲染，拥有固定 FOV、明亮的物品显示、不受世界方块或实体遮挡，并且在开启光影包时依然能正常使用流畅的本地光标与系统输入法。
* **Effect 过场动画**：正式播放与编辑预览均采用原版展示实体与原生固定相机，不依赖 Mouse 着色器，普通玩家无需安装模组即可观看。

## 与其他业务插件联动

除了通过 `player:`（玩家身份执行命令）和 `console:`（控制台身份执行命令）把现有的传送、背包、抽奖、技能等插件接入菜单按钮外，第三方插件还可以使用 ArcMenu 的开发者 API 注册原生宿主应用。

接入后的插件只需通过动作 `open-app: 命名空间:应用ID` 即可在当前屏幕平面上直接打开自己的交互界面，与普通 YAML 菜单共享同一个屏幕位置、光标控制和返回历史栈。开发者接入指南见[开发者应用 API](/gong-neng-pei-zhi/application-api.md)。


---

# 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/compatibility.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.