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

# 动画时间线与轨道

动画可让菜单打开时平滑进入、关闭时退出，也可让文字或其他前端元素移动、旋转、缩放和变化。

动画配置位于 `plugins/ArcMenu/animations.yml`，适用于 Paper、Folia、Leaf 等服务端。Spigot 不支持动画。普通玩家无需安装客户端模组；动画中的图片仍按[图片与资源包](/arcmenu-wen-dang/gong-neng-pei-zhi/resource-packs.md)配置。

## 文件结构

| 顶层字段             | 用途              |
| ---------------- | --------------- |
| `schema-version` | 使用 `1`，表示配置格式。  |
| `transitions`    | 按名称定义整个菜单的过渡效果。 |
| `tracks`         | 按名称定义前端元素的属性动画。 |
| `menus`          | 按菜单标识选用过渡和轨道。   |

层级分别为 **`transitions` → 过渡标识 → 阶段 → 阶段属性**、**`tracks` → 轨道标识 → 轨道属性**，最后在 **`menus` → 菜单标识** 中绑定。

过渡与轨道标识使用小写字母、数字、下划线和连字符，并以字母或数字开头。它们不是菜单标识，也不是目标元素名称。

## 配置示例

以下示例使用[菜单文档结构](/arcmenu-wen-dang/cai-dan-pei-zhi/menus.md)中的 `menu-guide` 菜单及其 `title` 文字元素。先创建并加载该菜单，再将以下内容合并到 `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}}

  title-message:
    target: title
    property: content
    duration: 40
    easing: linear
    loop: once
    trigger: api
    keyframes:
      - {at: 0, value: '&fMenu guide'}
      - {at: 0.5, value: '&aWelcome!'}
      - {at: 1, value: '&fMenu guide'}

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

打开菜单时执行滑入过渡和标题渐显。`title-bob` 与 `title-message` 等待动作或命令触发，不会自动播放。

## 菜单整体过渡：`transitions`

每个过渡可包含以下阶段，至少配置一项：

| 阶段       | 播放时机与效果                       |
| -------- | ----------------------------- |
| `enter`  | 首次打开菜单时，从指定偏移与缩放恢复到正常状态。      |
| `exit`   | 关闭菜单时，从正常状态变化到指定偏移与缩放。        |
| `switch` | 从其他菜单切换到该菜单时，从指定偏移与缩放恢复到正常状态。 |

未配置的阶段不播放对应过渡。示例没有 `switch`，因此切换到该菜单时不会使用 `enter` 代替切换过渡。

### 阶段属性

| 字段         | 用途                             |
| ---------- | ------------------------------ |
| `duration` | 必填，持续时间为 `1` 至 `72000` 游戏刻的整数。 |
| `easing`   | 变化速度曲线，省略时为 `linear`。          |
| `offset`   | `x`、`y`、`z` 偏移，省略时各为 `0`。      |
| `scale`    | `x`、`y` 缩放，省略时各为 `1`。          |

`offset` 是相对于整个菜单正常位置的偏移；横纵方向与菜单坐标一致。示例的 `enter.offset.x: -20` 表示从左侧进入，不会改写菜单元素的配置位置。

缩放以 `1` 为正常大小。缩放值不能为 `0`，绝对值不能超过 `1000`；通常使用正值。整体过渡不配置旋转、文字内容或 `scale.z`。

整体过渡期间暂不执行按钮点击，并隐藏提示框。过渡结束后恢复正常交互；退出过渡完成后关闭菜单。

## 元素轨道：`tracks`

一条轨道控制一个前端元素的一项属性。

### 轨道属性

| 字段          | 用途                           | 默认值       |
| ----------- | ---------------------------- | --------- |
| `target`    | 必填，目标前端元素或分组的名称。             | 无。        |
| `property`  | 必填，要变化的属性，见下表。               | 无。        |
| `duration`  | 必填，单程持续时间，`1` 至 `72000` 游戏刻。 | 无。        |
| `easing`    | 变化速度曲线。                      | `linear`。 |
| `loop`      | 播放一次、重复或往返。                  | `once`。   |
| `trigger`   | 打开时自动播放或等待手动触发。              | `open`。   |
| `keyframes` | 必填，按时间排列的关键帧列表。              | 无。        |

`target` 必须存在于绑定菜单的 `frontend` 中，可以是分组或分组内的元素，不能是后端区域。目标为分组时，位置、旋转或缩放会影响其显示子元素。

### 属性与关键帧值

| `property` | `value` 写法            | 适用范围                    |
| ---------- | --------------------- | ----------------------- |
| `offset`   | `{x: 0, y: 20, z: 1}` | 前端元素与分组的位置。             |
| `rotation` | `{x: 0, y: 90, z: 0}` | 前端元素与分组的旋转，单位为度。        |
| `scale`    | `{x: 1.1, y: 1.1}`    | 前端元素与分组的缩放。             |
| `content`  | `'&aWelcome!'`        | 仅文字元素。                  |
| `opacity`  | `255`                 | 仅文字元素，整数范围 `0` 至 `255`。 |

轨道值替换目标自身的对应属性，不是在原值上累加。例如标题原来位于 `y: 20`，上方 `title-bob` 从 `20` 移到 `28`，不是从 `40` 移到 `48`。

位置与旋转值省略的轴为 `0`。`scale` 必须同时填写 `x` 与 `y`；只有物品和方块目标可额外填写 `z`，省略 `z` 时保留原深度缩放。缩放值不能为 `0`，绝对值不超过 `1000`。位置与旋转各轴绝对值不超过 `100000`。

### 关键帧：`keyframes`

每帧包含 `at` 与 `value`：

* 至少两帧，首帧为 `at: 0`，末帧为 `at: 1`。
* `at` 为整段动画的进度，必须从小到大排列，不能重复。
* `value` 必须符合该轨道的属性类型。

`duration: 40`、`easing: linear` 时，`at: 0.5` 对应开始后的 `20` 游戏刻。正常服务器速度下，`20` 游戏刻约为 `1` 秒。

位置、旋转、缩放和透明度在关键帧间逐渐变化；文字内容在到达对应帧时切换，不会逐字生成。使用其他速度曲线时，中间帧的实际到达时间也会改变。

### 速度曲线：`easing`

| 值             | 效果            |
| ------------- | ------------- |
| `linear`      | 匀速变化。         |
| `ease-in`     | 开始较慢，随后加快。    |
| `ease-out`    | 开始较快，结束放缓。    |
| `ease-in-out` | 开始与结束较慢，中段较快。 |

过渡阶段与元素轨道使用相同的曲线名称。

### 循环：`loop`

| 值           | 行为                   |
| ----------- | -------------------- |
| `once`      | 播放一次，到达末帧后保持末帧值。     |
| `repeat`    | 到达一轮结束后，从首帧重新播放。     |
| `ping-pong` | 从首帧到末帧，再反向回到首帧，持续往返。 |

`duration` 是单程时间。示例的 `title-bob` 上行 `20` 游戏刻，下行再用 `20` 游戏刻，一次完整往返共 `40` 游戏刻。

### 触发：`trigger`

`open` 表示菜单打开时自动播放；`api` 表示等待动画动作或管理命令触发。配置值虽然叫 `api`，手动播放不需要编写代码。

同一菜单可同时播放同一元素不同属性的轨道，例如标题的位置与透明度。不能为同一元素的同一属性绑定多条 `open` 轨道；手动启动另一条同属性轨道时，会替换正在播放的轨道。

再次播放同一轨道会从头开始。`once` 到达末帧后仍保持该属性的动画结果；停止轨道后恢复菜单中原配置的值。文字 `content` 轨道保持生效期间，对应元素的定时文字刷新会暂停。

## 绑定菜单：`menus`

每个菜单标识下的 `transition` 选用一套整体过渡，`tracks` 列出该菜单可用的轨道标识。不需要整体过渡时可省略 `transition`；只使用过渡时可填写 `tracks: []`。

定义轨道但没有加入菜单的 `tracks`，不能在该菜单中播放它。菜单不存在、轨道不存在或目标不匹配时，配置检查会报错。同一轨道可被多个菜单选用，但每个菜单都必须具有符合要求的目标元素。

## 播放与停止

普通按钮使用以下动作：

```yaml
backend:
  animation-area:
    x: 50
    y: 0
    width: 30
    height: 18
    actions:
      left: 'animation: title-bob'
      right: 'animation: title-message'
      shift-left: 'stop-animation: title-bob'
```

此片段加入 `menu-guide` 后，左键播放标题往返，右键播放标题消息，Shift+左键停止往返。显示按钮仍需单独配置；动作参数使用轨道标识，不使用 `soft-slide` 等过渡标识。

管理员也可在正常打开的菜单中执行：

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

命令需要 `arcmenu.admin`。播放与停止命令需要在游戏内执行，并已打开绑定对应轨道的菜单。

## 显示与交互限制

元素轨道只改变 `frontend` 显示，不会同步移动、旋转或缩放 `backend` 点击区域。动画隐藏文字或改变透明度，也不会自动禁用按钮。

持续移动的装饰适合使用元素轨道；移动可点击按钮时，应考虑固定点击区域是否仍与显示一致。若要统一处理整个菜单的进出过程，使用整体过渡，而不是分别移动所有按钮。

动画不会修改保存的菜单文件。关闭后重新打开菜单，会重新开始自动播放的轨道；预览不用于检查正常播放与按钮触发。

## 加载与检查

修改菜单或 `animations.yml` 后，执行 `/arcmenu validate` 和 `/arcmenu reload`，重新打开菜单检查自动播放、手动触发、循环和停止恢复。只修改动画参数不需要重建资源包。

检查长时间循环是否符合预期，文字末帧是否应保持，以及动画按钮的点击区域是否正确。整体过渡应在结束后恢复点击与提示框；这些显示与交互效果需要在游戏中验证。