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

# GIF 动图

你可以将 `.gif` 动图直接放进菜单界面作为动态背景、横幅、图标或装饰，也可以将它加入 Effect 过场动画中。所有原始 GIF 文件都与普通 PNG 图片一样，存放在 `plugins/ArcMenu/images/` 目录下。

## 在菜单中添加 GIF

在菜单配置文件的 `frontend` 下，将元素 `type` 设为 `gif`，并指定图片路径与播放速度即可：

```yaml
frontend:
  animated-banner:
    type: gif
    source: /ui/banner.gif
    width: 160
    height: 40
    speed: 1
    offset: {y: 30, z: 1}
```

上方示例引用的是 `plugins/ArcMenu/images/ui/banner.gif`。在可视化编辑器中，你也可以直接使用 GIF 工具从素材库里挑选动图文件。

GIF 元素的各字段填写规则如下：

* `type`：固定填写 `gif`。
* `source`：以 `/` 开头的相对路径（从 `images/` 算起），文件名与子目录使用小写字母、数字、下划线、连字符或句点。同样支持 PlaceholderAPI 占位符与 `update` 动态路径刷新。
* `width` 与 `height`：可选的画布显示宽高，填写大于 `0` 的数值；省略时使用 GIF 原始像素宽高。
* `speed`：可选的播放速度，填写大于 `0` 的数值，默认值为 `1`。
* 其他通用外观属性：支持 `offset`（位置）、`rotation`（旋转）、`scale`（缩放）、`opacity`（`0`–`255` 不透明度）以及 `color`（十六进制颜色染色），用法与普通图片完全相同。

## 控制播放速度（`speed`）

`speed` 表示**每经过 1 个 Minecraft 游戏刻（tick）向前推进多少帧**，默认值为 `1`。这个设置会接管 GIF 文件内部原有的帧延迟与循环元数据，让动图按你在配置中指定的速率稳定循环：

| `speed` 取值 | 播放效果（正常服务器速度为每秒 20 tick）                   |
| ---------- | ------------------------------------------ |
| `0.5`      | 每 2 个 tick 前进 1 帧（即每帧停留 2 tick，每秒播放 10 帧）。 |
| `1`        | 每 1 个 tick 前进 1 帧（每秒播放 20 帧）。              |
| `2`        | 每 1 个 tick 前进 2 帧，依次显示第 0、2、4… 帧。          |

当动图用于 [Effect 过场动画](/gong-neng-pei-zhi/effect.md) 时，它的播放进度会直接跟随 Effect 的时间线播放头，支持暂停、拖动定位、图层裁剪，并且可以为 `speed` 添加关键帧来实现平滑变速。

## 客户端本地播放与服务端帧播放

ArcMenu 支持两种 GIF 渲染机制，并通过 `config.yml` 中的 `client-playback.local-gifs` 控制：

```yaml
client-playback:
  local-gifs: true
```

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

* **客户端本地动画纹理（`local-gifs: true`）**：在鼠标模式下，当动图保持完全不透明（`opacity: 255` 且原图无半透明像素）、未设置 `color` 染色、并且使用固定 `speed` 时，ArcMenu 会在资源包中为其生成原生的客户端动态纹理。客户端会自动推进帧画面，无需服务端每刻发送网络更新包。
* **播放时钟说明**：客户端动态纹理的时钟从资源包加载时起算，同一素材与速度的所有实例共享同一个播放时钟。如果你希望某个动图在每次打开菜单时都严格从第 0 帧重新开始播放，可以将 `client-playback.local-gifs` 设为 `false`，改用服务端帧同步。
* **服务端帧同步**：触控模式、Vision 模式、编辑器预览、带有透明度或颜色染色的动图，以及 Effect 时间线中的动图，都会自动使用服务端帧字形渲染，确保在各自模式下呈现准确的透明混合、光影兼容与时间轴定位。

鼠标模式的本地 GIF 需要客户端已加载当前生成的配套资源包。`config.yml` 中的 `mouse.assume-resource-pack-loaded` 默认为 `true`，即信任玩家手动安装的配套资源包；设为 `false` 时则会检查服务端的资源包加载成功回执。相关细节见[图片与资源包](/gong-neng-pei-zhi/resource-packs.md)。

## 资源包构建与规格要求

在 `images/` 中添加或更换 GIF 文件后，需要重新构建并分发资源包：

* 配合自定义内容插件使用时，先执行 `/arcmenu resources`（或 `/arcmenu reload all`），再运行对应插件的打包命令（CraftEngine 执行 `/ce reload pack`，Nexo 执行 `/nexo reload pack`，ItemsAdder 执行 `/iazip`）。
* 独立管理资源包时，执行 `/arcmenu reload all`，然后将新生成的 `plugins/ArcMenu/generated/arcmenu-resourcepack.zip` 分发给客户端。

在构建资源包的过程中，ArcMenu 会自动合成 GIF 的局部帧、透明通道与处置模式，并将序列帧直接写入生成的 ZIP 包内，不会在 `images/` 目录中散落序列帧文件。当你使用 ArcPack 导出菜单包时，原始 `.gif` 文件和 `speed` 播放设置都会被完整打包带走。

单个 GIF 文件需满足以下规格：文件大小不超过 `16 MiB`，宽度与高度在 `1` 到 `4096` 像素之间，总帧数不超过 `1024` 帧，且单文件全尺寸解码总像素（`宽 × 高 × 帧数`）不超过 `16,777,216`。


---

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