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

# 动画时间线与轨道

通过配置动画，你可以让菜单在打开、关闭和切换时平滑过渡，也可以让前端的文字、图片、矩形、物品或整个分组产生位移、旋转、缩放、透明度渐变与色彩过渡。所有玩家在原版客户端上即可直接看到这些动画效果。

菜单动画统一在 `plugins/ArcMenu/animations.yml` 中配置（通过 ArcPack 安装的扩展包动画则会存放在 `plugins/ArcMenu/animations/` 目录下自动加载）。

## 配置文件结构

`animations.yml` 由四个顶层字段组成，我们先定义可复用的过渡和轨道，再将它们绑定到具体的菜单上：

| 顶层字段             | 用途与有效值                                        |
| ---------------- | --------------------------------------------- |
| `schema-version` | 配置文件格式版本，固定填写整数 `1`。                          |
| `transitions`    | 定义整张菜单在打开、关闭或切换时的整体进出场过渡。                     |
| `tracks`         | 定义针对单个前端元素或分组的属性关键帧动画轨道。                      |
| `menus`          | 按菜单 `id` 绑定该菜单使用的 `transition` 和 `tracks` 列表。 |

在 `transitions` 和 `tracks` 下自定义的标识名称，只能使用小写英文字母、数字、下划线（`_`）和连字符（`-`），且必须以字母或数字开头。

## 完整配置示例

假设我们有一个标识为 `menu-guide` 的菜单，其中包含一个名为 `title` 的文字元素和一个名为 `button-bg` 的矩形元素。在 `animations.yml` 中可以这样编写动画：

```yaml
schema-version: 1

transitions:
  soft-slide:
    enter:
      duration: 8
      easing: ease-out
      offset: {x: -20, y: 0, z: 0}
      scale: {x: 0.95, y: 0.95}
    exit:
      duration: 6
      easing: ease-in
      offset: {x: 0, y: -20, z: 0}
      scale: {x: 0.95, y: 0.95}

tracks:
  title-fade:
    target: title
    property: opacity
    duration: 20
    easing: linear
    loop: once
    trigger: open
    keyframes:
      - {at: 0, value: 80}
      - {at: 1, value: 255}

  title-bob:
    target: title
    property: offset
    duration: 20
    easing: ease-in-out
    loop: ping-pong
    trigger: api
    keyframes:
      - {at: 0, value: {x: 0, y: 20, z: 1}}
      - {at: 1, value: {x: 0, y: 28, z: 1}}

  button-highlight:
    target: button-bg
    property: color
    duration: 4
    easing: ease-out
    loop: once
    trigger: api
    keyframes:
      - {at: 0, value: '#181916'}
      - {at: 1, value: '&#DF432D'}

menus:
  menu-guide:
    transition: soft-slide
    tracks: [title-fade, title-bob, button-highlight]
```

在这个例子中，玩家打开 `menu-guide` 时，整张菜单会从左侧平滑滑入（`soft-slide`），同时标题透明度从 `80` 渐变到 `255`（`title-fade`）。而 `title-bob` 和 `button-highlight` 的触发方式设为了 `api`，它们会在悬停或点击按钮时按需播放。

## 菜单整体过渡（`transitions`）

每个过渡定义下可以包含 `enter`、`exit`、`switch` 三个阶段中的任意一个或多个（至少配置其中一个阶段）：

| 阶段名称     | 触发时机与动画方向                                                    |
| -------- | ------------------------------------------------------------ |
| `enter`  | 玩家首次打开菜单时播放。菜单从你设置的 `offset` 和 `scale` 状态，平滑过渡回菜单原本的正常位置与大小。 |
| `exit`   | 玩家关闭菜单时播放。菜单从正常状态平滑变化到你设置的 `offset` 和 `scale`，随后正式关闭。        |
| `switch` | 从另一个已打开的菜单切换到当前菜单时播放。菜单从设置的 `offset` 和 `scale` 平滑过渡回正常状态。    |

每个阶段内支持配置以下字段：

| 字段         | 填写内容与有效值                                                               |
| ---------- | ---------------------------------------------------------------------- |
| `duration` | 必填。过渡持续时间，填写 `1` 到 `72000` 之间的整数（单位为游戏刻，`20` 刻约为 1 秒）。                 |
| `easing`   | 速度曲线，可选 `linear`、`ease-in`、`ease-out`、`ease-in-out`。省略时默认为 `linear`。   |
| `offset`   | 起始（或结束）位置相对于菜单正常位置的偏移量，包含 `x`、`y`、`z`，每个轴的绝对值不超过 `100000`。省略的轴默认为 `0`。 |
| `scale`    | 起始（或结束）状态的整体缩放倍率，包含 `x` 和 `y`，填写非零且绝对值不超过 `1000` 的数值。省略时默认为 `1`。       |

在菜单播放整体过渡的短暂过程中，按钮点击会暂时锁定并隐藏提示框，等过渡到位后立即恢复正常交互。

## 元素属性轨道（`tracks`）

每一条轨道用来控制单个前端元素（或分组）的一项属性。轨道配置包含以下字段：

| 字段          | 填写内容与有效值                                                                | 默认值      |
| ----------- | ----------------------------------------------------------------------- | -------- |
| `target`    | 必填。目标前端元素或分组的名称（必须存在于所绑定的菜单前端中）。                                        | 无        |
| `property`  | 必填。要驱动的属性名称，可选：`offset`、`rotation`、`scale`、`content`、`opacity`、`color`。 | 无        |
| `duration`  | 必填。单程播放时长，填写 `1` 到 `72000` 之间的整数（单位为游戏刻）。                               | 无        |
| `easing`    | 整条轨道单程进度的速度曲线，可选：`linear`、`ease-in`、`ease-out`、`ease-in-out`。           | `linear` |
| `loop`      | 循环模式，可选：`once`（单次）、`repeat`（循环）、`ping-pong`（往返）。                        | `once`   |
| `trigger`   | 触发方式，可选：`open`（打开菜单自动播放）或 `api`（由动作、悬停或命令触发）。                           | `open`   |
| `keyframes` | 必填。按时间顺序排列的关键帧列表。                                                       | 无        |

当 `target` 指向一个分组（`group`）时，`offset`、`rotation` 和 `scale` 轨道会带动整个分组内的所有子元素一起运动。

### 可动画属性与关键帧取值（`property` 与 `value`）

关键帧列表 `keyframes` 中的每一项都包含 `at`（时间进度）和 `value`（属性值）。

* `at` 填写 `0` 到 `1` 之间的数值，代表整段 `duration` 的时间比例（例如 `duration: 40` 时，`at: 0.5` 对应第 `20` 刻）。
* 一条轨道至少需要 **2 个关键帧**，第一帧必须为 `at: 0`，最后一帧必须为 `at: 1`，中间各帧的 `at` 必须严格递增且不能重复。

不同 `property` 对应的 `value` 格式与适用元素类型如下：

| `property` | `value` 格式示例               | 取值范围与适用元素                                                                            |
| ---------- | -------------------------- | ------------------------------------------------------------------------------------ |
| `offset`   | `{x: 0, y: 20, z: 1}`      | 适用于所有前端元素与分组。各轴绝对值不超过 `100000`，省略的轴默认为 `0`。                                          |
| `rotation` | `{x: 0, y: 90, z: 0}`      | 适用于所有前端元素与分组，单位为度。各轴绝对值不超过 `100000`，省略的轴默认为 `0`。                                     |
| `scale`    | `{x: 1.1, y: 1.1}`         | 适用于所有前端元素与分组。`x`、`y` 必填，物品（`item`）和方块（`block`）还可额外填写 `z`；数值须为非零且绝对值不超过 `1000`。       |
| `content`  | `'&aWelcome!'`             | 仅适用于文字元素（`text`）。在到达对应关键帧时切换显示的文本内容。                                                 |
| `opacity`  | `255`                      | 仅适用于文字元素（`text`）。填写 `0` 到 `255` 之间的整数，在关键帧之间平滑插值。                                    |
| `color`    | `'#DF432D'` 或 `'&#DF432D'` | 仅适用于矩形（`rectangle`）、线条（`line`）和边框（`frame`）。填写带引号的 6 位十六进制颜色，按 RGB 通道平滑过渡并保留元素原本的透明度。 |

需要注意的是，轨道中的 `value` 在播放时会**直接替换**目标元素在菜单 YAML 中配置的对应属性值，而不是在原值基础上做加法。例如标题原本配置在 `y: 20`，如果你想让它向上浮动 `8` 个单位，关键帧应写为从 `y: 20` 变到 `y: 28`。当轨道被停止（`stop-animation`）时，元素会自动恢复为菜单 YAML 中配置的初始值。

### 速度曲线与循环方式

`easing` 作用于整条轨道单程播放的总体归一化进度（`0` 到 `1`），先计算曲线映射后的整体时间进度，再据此定位所处的关键帧区间并执行线性插值，而不是在每对相邻关键帧之间单独重置速度曲线：

* `linear`：全程匀速推进。
* `ease-in`：单程起步较慢，随后逐渐加速。
* `ease-out`：单程起步较快，临近结束时平滑减速。
* `ease-in-out`：单程起步与结束均平缓，中段速度较快。

`loop` 控制轨道到达 `at: 1` 之后的行为：

* `once`：播放一次，到达末帧后一直保持末帧的值（直到轨道被手动停止）。当文字元素的 `content` 轨道处于生效状态时，该元素原本的定时刷新会暂停，以免覆盖动画文字。
* `repeat`：每次到达末帧后，立即跳回首帧重新播放。
* `ping-pong`：从首帧播放到末帧，再原路反向播放回首帧，如此持续往返。`duration` 计算的是单程时间，因此一次完整的往返耗时为 `2 × duration`。

## 将动画绑定到菜单（`menus`）

定义好 `transitions` 和 `tracks` 后，还需要在 `menus` 下将它们关联到具体的菜单 ID 上：

```yaml
menus:
  menu-guide:
    transition: soft-slide
    tracks: [title-fade, title-bob, button-highlight]
```

* 如果菜单只需要元素轨道、不需要整体进出场过渡，可以省略 `transition`。
* 如果菜单只需要整体过渡，可以将轨道列表写为 `tracks: []`。
* 同一个元素的**不同属性**（例如 `offset` 和 `opacity`）可以同时各自运行一条 `trigger: open` 的自动轨道；但同一个元素的**同一属性**最多只能绑定一条 `trigger: open` 轨道。对于 `trigger: api` 的手动轨道则没有数量限制，当新轨道启动并控制同一属性时，会自动接管该属性。
* 菜单里的动作如果要调用某条轨道，该轨道必须先列在当前菜单的 `tracks` 列表中。

## 触发与停止轨道动画

对于设置了 `trigger: api` 的轨道，你可以通过按钮点击动作、悬停事件或管理员命令来控制播放。

### 悬停高亮与按钮点击触发

在菜单 `backend` 交互区域中，可以使用 `animate: 轨道标识`（或等价的 `animation: 轨道标识`）启动轨道，使用 `stop-animation: 轨道标识` 停止轨道并恢复元素初始值。

比如结合前文的 `button-highlight` 颜色轨道，制作一个鼠标指向时平滑变色、移开时恢复原色的按钮：

```yaml
frontend:
  button-bg:
    type: rectangle
    width: 80
    height: 30
    color: '#181916'

backend:
  button-area:
    x: 0
    y: 0
    width: 80
    height: 30
    on-hover: 'animate: button-highlight'
    on-leave: 'stop-animation: button-highlight'
    actions:
      left: 'animate: title-bob'
      shift-left: 'stop-animation: title-bob'
```

当玩家指向 `button-area` 时，`on-hover` 会触发一次 `button-highlight` 颜色过渡，悬停期间不会重复从头重启；移开时 `on-leave` 停止轨道并恢复 `#181916` 底色。如果你想让移开时也有一段平滑的退色动画，可以再写一条从高亮色变回底色的轨道，放在 `on-leave` 中触发。

### 使用管理命令调试动画

拥有 `arcmenu.admin` 权限的管理员，在游戏内打开已绑定轨道的菜单后，可以直接使用以下命令查看或测试轨道：

```
/arcmenu animations
/arcmenu animate title-bob
/arcmenu stop-animation title-bob
```

## 客户端插值优化

在 `config.yml` 中，`client-playback.linear-offsets` 默认设为 `true`：

```yaml
client-playback:
  linear-offsets: true
```

开启后，满足条件的线性位移轨道（`property: offset` 且 `easing: linear`）会交由 Minecraft 原生展示实体的客户端插值机制来平滑移动，从而减少服务端逐刻发送位置更新包的频率。关键帧节点切换、循环重置以及播放/停止控制依然由服务端精确同步。

修改并保存 `animations.yml` 后，执行 `/arcmenu reload` 即可生效。如果你需要制作带音频同步、固定视角画面编排与多图层时间线的全屏过场动画，请参阅 [Effect 过场动画](/gong-neng-pei-zhi/effect.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/gong-neng-pei-zhi/animations.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.