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

# 图片与资源包

你可以将 PNG 静态图和 GIF 动图放进菜单，用来制作面板背景、标题标志、图标按钮或界面装饰。所有原始图片文件都存放在 `plugins/ArcMenu/images/` 目录下，ArcMenu 会将它们自动打包进服务器资源包中。

## 存放与引用图片

在 `images/` 下可以自由创建子目录来分类管理素材。文件夹名称与文件名只能使用小写英文字母、数字、下划线（`_`）、连字符（`-`）和英文句点（`.`）。

在菜单配置中引用图片时，路径以 `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` |
| `plugins/ArcMenu/images/ui/banner.gif`       | `/ui/banner.gif`       |

下面是一个在菜单前端添加 PNG 图片的示例：

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

各字段的填写规则如下：

* `type`：静态图片填写 `image`；动图填写 `gif`，具体用法见 [GIF 动图](/gong-neng-pei-zhi/gif.md)。
* `source`：以 `/` 开头的图片路径，支持 `.png` 或 `.gif` 后缀。
* `width` 与 `height`：图片在菜单画布上的显示宽高，填写大于 `0` 的数值。省略任一字段时，默认采用原图对应的像素尺寸。
* `opacity`：可选的不透明度，填写 `0` 到 `255` 之间的整数，`255` 为完全不透明。
* `color`：可选的图片染色，填写 `'#RRGGBB'` 或 `'&#RRGGBB'` 格式的十六进制颜色。

鼠标光标贴图与提示框九宫格皮肤同样存放在 `images/` 目录下，分别在[触控、鼠标与 Vision 输入](/gong-neng-pei-zhi/input-modes.md)和[提示框](/gong-neng-pei-zhi/tooltips.md)中配置。

## 动态切换图片

`source` 支持填入 PlaceholderAPI 占位符，再配合 `update` 刷新间隔，就能根据玩家当前状态实时切换图片。例如：

```yaml
frontend:
  rank-badge:
    type: image
    source: /ranks/%player_rank%.png
    update: 20
```

这里的 `update` 填写正整数（单位为游戏刻，`20` 刻约为 1 秒），或者填 `-1` 表示只在打开菜单时解析一次。占位符可能解析出的所有目标图片（例如 `/ranks/vip.png`、`/ranks/admin.png`）都需要提前放入 `images/` 目录并生成到资源包中。

## 生成与合并资源包

每次新增、替换或删除图片、光标与提示框皮肤后，都需要重新生成资源包，并把新包分发给客户端。

### 与自定义内容插件联动

当服务器安装了 CraftEngine、Nexo 或 ItemsAdder 时，这些插件在构建资源包时会自动拉取并合并 ArcMenu 的资源输出。

* 在游戏内通过可视化编辑器或项目管理器修改资源、安装带素材的包时，ArcMenu 会按 **CraftEngine → Nexo → ItemsAdder** 的优先级自动请求对应插件重建资源包。
* 如果你是手动把图片放进 `images/` 目录的，可以先执行 `/arcmenu resources`（或 `/arcmenu reload all`）生成 ArcMenu 资源，再根据你使用的插件执行最终打包命令：
  * **CraftEngine**：执行 `/ce reload pack`（或 `/ce reload all`）
  * **Nexo**：执行 `/nexo reload pack`
  * **ItemsAdder**：执行 `/iazip`

如果服务器同时安装了多个同类资源包插件，只保留其中一个负责最终的资源包托管与下发即可，避免重复发送。

### 独立生成与外部托管

在没有使用上述插件的服务器上，执行 `/arcmenu reload all` 或 `/arcmenu resources` 后，ArcMenu 会在以下路径生成完整的资源包文件：

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

你可以将这个 ZIP 上传到资源托管服务，并在服务端 `server.properties` 中配置下发；或者将它交给其他打包工具合并（合并时请完整保留 `assets/arcmenu/` 目录与 `pack.mcmeta` 中的叠加层定义）。如果只是调整了菜单 YAML 里的坐标或文字，没有改动图片素材，执行 `/arcmenu reload` 即可生效。

## 客户端手动安装与加载检测

除了通过服务器自动下发，玩家也可以将生成的 `arcmenu-resourcepack.zip` 直接放进本地客户端的 `resourcepacks` 文件夹并手动启用。每当服务器更新了图片或光标配置，都需要重新生成 ZIP 并让玩家替换本地的旧包。

在 `config.yml` 中，`mouse.assume-resource-pack-loaded` 用来控制鼠标模式如何判断客户端的资源包就绪状态：

```yaml
mouse:
  assume-resource-pack-loaded: true
```

该选项接受 `true` 或 `false`，默认值为 **`true`**：

* 设为 **`true`** 时：ArcMenu 默认信任玩家客户端已经启用了配套资源包。即使客户端是手动安装的资源包、没有向服务端发送“资源包加载成功”的网络回执，鼠标模式也会正常启用菜单深度、固定视角（FOV）、平面光照、本地光标以及本地 GIF 动画纹理。
* 设为 **`false`** 时：鼠标模式会严格等待服务端收到客户端的资源包加载成功回执。在等待加载或加载失败期间，不会启用依赖配套资源包的画面与光标特性。

这个开关只影响鼠标模式对配套资源包的就绪判断。触控模式采用原生渲染，Vision 模式和编辑器预览则由客户端安装的 ArcMenu Editor 直接提供独立渲染与原生光标。无论使用哪种模式，菜单里引用的自定义图片和字体依然需要客户端加载对应的资源包才能显示出来。

## 素材尺寸与规格要求

为了兼顾画面清晰度与客户端内存占用，放入 `images/` 的图片需符合以下规格：

* **PNG 静态图**：支持透明通道。单张图片的宽度与高度在 `1` 到 `4096` 像素之间，单个文件不超过 `16 MiB`。整個 `images/` 目录最多支持 `4096` 张图片与帧字形，原始文件总大小不超过 `128 MiB`。
* **自动图集适配**：Minecraft 字体图集对单个字形有 `256` 像素的尺寸上限。对于宽高超过 `256` 像素的大尺寸 PNG，ArcMenu 在构建资源包时会自动生成适配图集的缩放位图，并保持你在菜单中设置的显示尺寸不变；`images/` 目录下的原图文件不会被修改。
* **GIF 动图**：单个文件不超过 `16 MiB`，宽高不超过 `4096` 像素，最多包含 `1024` 帧，单文件全画布解码总像素不超过 `16,777,216`。构建资源包时，序列帧会直接写入生成的 ZIP 包内，`images/` 目录中只保留原始 `.gif` 文件。


---

# 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/gong-neng-pei-zhi/resource-packs.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.