> 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-wen-dang/gong-neng-pei-zhi/resource-packs.md).

# 图片与资源包

自定义图片用于菜单背景、标志、按钮和装饰。图片文件保存在服务端，ArcMenu 将它们生成到资源包中；玩家加载该资源包后，才能正常显示图片。

本页适用于 Paper、Folia、Leaf 等服务端。Spigot 不支持自定义图片、ArcMenu 资源包生成或 CraftEngine 资源合并。

## 准备图片

将 PNG 文件放入 `plugins/ArcMenu/images/`，可按用途创建子目录，例如：

```
plugins/ArcMenu/images/ui/logo.png
plugins/ArcMenu/images/ui/background.png
plugins/ArcMenu/images/buttons/confirm.png
```

### 文件与路径要求

* 使用有效的 PNG 文件，支持透明背景。不能通过修改扩展名将 JPEG 等文件变成 PNG。
* 文件名和目录名使用小写英文字母、数字、下划线、连字符或点，不使用空格或中文名称。
* 菜单引用以 `/` 开头，以 `.png` 结尾，目录之间使用 `/`。
* 不使用 `.`、`..` 作为目录名，也不使用连续的 `//`。
* `source` 引用本地图片，不接受网页链接或服务端完整文件路径。

菜单中的路径从 `images/` 目录开始计算：

| 服务端图片                                        | 菜单中的 `source`          |
| -------------------------------------------- | ---------------------- |
| `plugins/ArcMenu/images/example.png`         | `/example.png`         |
| `plugins/ArcMenu/images/ui/logo.png`         | `/ui/logo.png`         |
| `plugins/ArcMenu/images/buttons/confirm.png` | `/buttons/confirm.png` |

### 图片大小限制

| 项目           | 限制                     |
| ------------ | ---------------------- |
| 单张图片宽度和高度    | 每个方向为 `1` 至 `4096` 像素。 |
| 单张 PNG 文件大小  | 不超过 `16 MiB`。          |
| 全部 PNG 文件总大小 | 不超过 `128 MiB`。         |
| PNG 文件数量     | 不超过 `4096` 张。          |

这些限制适用于图片目录中的全部 PNG，包括内置图片和子目录中的文件。建议按菜单的实际显示需求准备图片，避免使用远大于所需尺寸的素材。

## 在菜单中引用图片

图片元素位于 `frontend` 下，使用 `type: image`：

```yaml
frontend:
  server-logo:
    type: image
    source: /ui/logo.png
    width: 96
    height: 32
    offset: {x: 0, y: 40, z: 1}
```

将此片段合并到已有菜单的 `frontend`，并确保 `images/ui/logo.png` 已存在。

`width` 与 `height` 是画布上的显示尺寸，不会修改原 PNG 文件。两项可分别设置，省略的尺寸使用原图对应的像素数。保持与原图相同的宽高比例，可避免图片被拉伸。

图片的透明度、着色和通用位置属性见[前端元素类型](https://simple.superiormc.cn/arcmenu-wen-dang/gong-neng-pei-zhi/pages/phk8Dy6jQrfp3TU7d7xK#图片image)，单位与坐标见[画布、坐标与屏幕位置](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/canvas.md)。

图片只负责显示。若用作按钮，还需在 `backend` 中创建对应点击区域。

### 动态图片

Paper 系服务端允许通过占位符改变 `source`，并通过图片的 `update` 设置定时刷新。可能显示的图片都应提前放入图片目录并生成到资源包中，替换后的路径也必须符合本页规则。

`update` 重新判断要显示的图片路径，不会读取修改后的 PNG 文件，也不会向玩家发送资源包。修改图片内容仍需完成下方更新流程。

## 生成与更新资源

图片准备完成后，推荐执行：

```
/arcmenu validate
/arcmenu reload all
```

命令需要 `arcmenu.admin`，可在游戏内或控制台执行；控制台不需要开头的 `/`。

| 命令                    | 用途                       |
| --------------------- | ------------------------ |
| `/arcmenu validate`   | 检查配置；不生成资源包。             |
| `/arcmenu reload`     | 重新加载配置；不重建图片资源。          |
| `/arcmenu reload all` | 重新加载配置与模板，并重建资源包。        |
| `/arcmenu resources`  | 使用已加载的配置重建资源包；不重新读取菜单定义。 |

同时修改菜单文件与图片时，使用 `reload all`。只修改图片文件且不需要重新加载配置时，可使用 `resources`。

生成的 ZIP 位于：

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

`generated/` 中的资源由 ArcMenu 生成，不应作为图片素材目录。直接修改生成文件会在下次重建时被覆盖。

## 分发资源包

资源包生成与玩家加载是两步操作。生成成功不代表玩家已经获得新内容；应根据服务器使用的分发方式继续处理。

### 未使用 CraftEngine

1. 执行 `/arcmenu reload all`，确认资源生成成功。
2. 将生成的 `arcmenu-resourcepack.zip` 上传至服务器使用的资源包托管位置，或交由现有资源包工具处理。
3. 在服务器的资源包分发设置中更新下载地址及该方式要求的校验信息。
4. 让玩家接受并加载更新后的资源包，再重新打开菜单检查。

下载地址应直接提供 ZIP 文件，不能使用需要登录或只显示下载网页的地址。ArcMenu 不会自动托管或向玩家发送这个文件。

如果服务器已有资源包，应使用现有合并流程加入完整的 ArcMenu 资源，不应只复制原始 PNG 图片。合并时应保留资源包根目录结构，并处理同名文件冲突；随后分发合并后的包。

### 使用 CraftEngine

修改菜单图片或相关配置后，按顺序执行：

```
/arcmenu reload all
/ce reload all
```

先等待 ArcMenu 生成成功，再重建 CraftEngine 资源包。正常连接时，CraftEngine 会将 ArcMenu 资源合并到自己的资源包中。

之后通过服务器已有的 CraftEngine 资源包分发方式，让玩家加载新的合并包。玩家需要得到合并结果，而不是仍使用上一次的包。

如果日志提示合并失败，应先修正错误，再重新生成和分发；不要只依据 CraftEngine 的重载完成提示判断 ArcMenu 图片是否已加入。

## 鼠标、提示框与资源更新

鼠标模式也需要配套资源。仅使用文字和原版物品的菜单，在鼠标模式下仍应分发 ArcMenu 资源包。

修改光标图片、灵敏度、大小或相关屏幕设置后，应重新生成资源包并让玩家更新。具体设置见[触摸与鼠标输入](/arcmenu-wen-dang/gong-neng-pei-zhi/input-modes.md)。

提示框使用的图片同样放在 `images/` 中。新增或更换图片背景后，需重新生成和分发资源；具体设置及重载范围见[提示框](/arcmenu-wen-dang/gong-neng-pei-zhi/tooltips.md)。

## 显示异常排查

| 情况                  | 检查方法                                                   |
| ------------------- | ------------------------------------------------------ |
| 图片没有显示              | 检查 `source` 对应的 PNG 是否存在，路径和文件名是否一致，资源是否已重建。缺失的图片会隐藏。  |
| 显示方框、异常字符或错误图片      | 确认玩家加载的是包含当前 ArcMenu 内容的最新资源包，并检查合并包是否保留完整资源。          |
| 修改 PNG 后仍显示旧图       | 重建资源包，更新托管或合并结果，并让玩家加载新包；仅执行 `reload` 不足以更新图片。         |
| 图片显示被拉伸             | 对照原图宽高比例检查元素的 `width`、`height` 与 `scale`。              |
| 资源生成失败              | 根据提示检查 PNG 格式、小写路径、图片尺寸与文件大小限制。                        |
| 切换动态图片后消失           | 检查占位符替换后的实际路径，以及对应图片是否已生成到资源包。                         |
| CraftEngine 中缺少菜单图片 | 检查合并错误，按 ArcMenu 重建、CraftEngine 重建的顺序重新处理，并确认玩家加载新合并包。 |

可先用内置 `/example.png` 图片判断资源包是否正常，再检查自定义图片。显示检查应覆盖服务器允许进入的实际客户端版本；玩家端加载与合并包效果需要在游戏中验证。