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

# Effect 过场动画

Effect 是 ArcMenu 的过场动画与演出模块。它提供了一个类似影视后期软件的时间线工作区，可以把前端视觉元素、图片、GIF 动图、三维物品模型、音效、NBS 红石音乐以及服务器命令编排成一段完整的视听演出。无论是新玩家入服剧情、副本传送过场、节日活动开场，还是抽奖结算展示，都可以用它来制作。

管理员使用 ArcMenu Editor 在游戏内可视化编排，而普通玩家无需安装任何客户端模组，直接通过服务端即可观看。播放与预览均采用原版展示实体与固定摄像机视角，保留真实的世界光照、阴影与方块遮挡，在开启各类光影包时也能自然融入游戏环境。如果演出中用到了自定义图片、字体或新增的本地音乐，只需让客户端正常加载服务器资源包即可。

## 创建与播放命令

管理员（需具备 `arcmenu.admin` 权限）站在地面上执行以下命令，即可新建或打开一个 Effect 项目：

```
/arcmenu editeffect intro
```

如果直接执行 `/arcmenu editeffect` 且服务器上还没有任何项目，系统会自动生成并打开内置示例。如果你想以某张现有菜单的画面为基础来制作过场动画，可以在项目 ID 后面加上来源菜单的 ID：

```
/arcmenu editeffect intro main
```

这会把 `main` 菜单的前端元素复制一份到 `effects/intro/scene.yml` 中，后续在 Effect 里的修改完全独立，不会影响原本的菜单。

编辑完成并保存后，可使用以下命令控制播放与管理目录：

| 命令                             | 说明                                                              |
| ------------------------------ | --------------------------------------------------------------- |
| `/arcmenu effect <项目ID>`       | 为自己播放指定的过场动画。播放期间视角固定，结束后自动恢复正常视角。                              |
| `/arcmenu effect <项目ID> <玩家名>` | 管理员或控制台为指定在线玩家播放过场动画。                                           |
| `/arcmenu effect pause [玩家名]`  | 暂停当前正在播放的动画与音乐。                                                 |
| `/arcmenu effect resume [玩家名]` | 从暂停位置继续播放。                                                      |
| `/arcmenu effect stop [玩家名]`   | 立即停止播放并恢复玩家视角。                                                  |
| `/arcmenu effect list`         | 查看当前已加载的全部 Effect 项目。                                           |
| `/arcmenu effect reload`       | 校验并重载所有 Effect 配置文件。常规的 `/arcmenu reload` 也会一并刷新已启用的 Effect 目录。 |

玩家自己触发播放需要具备默认的 `arcmenu.effect` 权限，以及该项目在 `timeline.yml` 中配置的 `permission`（留空则不额外限制权限）。编辑、重载与指定其他玩家操作均需要 `arcmenu.admin` 权限。

## 时间线工作区

打开 Effect 编辑器后，界面分为四个协同工作的区域：左侧是可搜索的**项目与素材浏览器**，中间是实时渲染的**画面合成视口**，右侧是**属性检查器**，底部则是完整的多轨**时间线面板**。各面板之间的分隔线都可以自由拖动调整宽度。

### 画面预览与工具

视口默认采用 **Playback（实际播放比例）** 模式，严格按照项目的画布尺寸、`pixels-per-block` 和设计距离还原玩家观看时的真实大小。需要精细对齐细节时，可以切换到 **Fit（适应窗口）** 模式，将画布放大铺满预览区，并使用 `Ctrl + 滚轮` 缩放或按住鼠标中键平移画面。

你可以使用快捷键 `V`（选择）、`H`（抓手平移）、`Z`（缩放）、`W`（旋转）和 `Q`（绘制图形）切换工具。在右侧属性面板中，直接在数值标签上左右拖动即可快速微调参数（按住 `Shift` 精细调节，按住 `Ctrl` 大幅调节），点击颜色框则会弹出 RGBA 与十六进制拾色器。

### 图层、关键帧与曲线

在左侧或时间线中选中一个元素图层后，展开其属性即可在当前播放头（Playhead）位置添加关键帧。开启 **自动关键帧（Auto-key）** 后，只要拖动播放头并修改属性面板中的数值，编辑器就会在当前帧自动记录关键帧。

支持设置关键帧动画的属性包括：

* **空间变换与显示**：位置偏移（`offset.x` / `offset.y` / `offset.z`）、三轴旋转（`rotation.x` / `y` / `z`）、三轴缩放（`scale.x` / `y` / `z`）、宽高尺寸、可见性（`visible`）以及不透明度（`opacity`，适用于支持透明度的文本与图形节点）。
* **外观与内容**：RGB 颜色、文本内容、字体、字号、对齐方式、行宽、图片路径、物品材质与展示上下文、方块状态等。其中数值与颜色通道会在关键帧之间平滑插值，文本、布尔值与资源路径则会在到达关键帧的那一刻直接切换。

每个关键帧都可以设置通往下一帧的插值方式（`interpolation`），可选值包括：

* `linear`：匀速线性变化。
* `hold`：定格保持当前值，直到下一关键帧才瞬间跳变。
* `ease-in` / `ease-out` / `ease-in-out`：预设的缓入、缓出与缓入缓出过渡。
* `bezier`：三次贝塞尔曲线，通过 `curve: [x1, y1, x2, y2]` 控制时间与数值的变化速率。
* `auto-bezier`：根据前后相邻关键帧自动计算平滑连续的切线。

点击时间线切换按钮可以打开**曲线编辑器（Graph Editor）**，在数值曲线（Value Graph）或速度曲线（Speed Graph）视图下直观地拉动贝塞尔手柄。双击关键帧还可以直接输入精确的帧号、数值与曲线参数。

在时间线中，你可以拖动图层的左右边缘来裁剪它的显示区间 `[start, end)`，按住 `Alt` 拖动图层条整体平移时间，或者使用开关单独隐藏图层、开启 **Solo（独奏）** 只看当前分支。

## 常用快捷键

| 操作                               | 快捷键                                  |
| -------------------------------- | ------------------------------------ |
| 保存项目（同时保存场景与时间线）                 | `Ctrl + S`                           |
| 撤销 / 重做（场景与时间线统一撤销）              | `Ctrl + Z` / `Ctrl + Shift + Z`      |
| 复制 / 剪切 / 粘贴图层或关键帧               | `Ctrl + C` / `Ctrl + X` / `Ctrl + V` |
| 原地复制选中图层（含动画轨道）                  | `Ctrl + D`                           |
| 在播放头位置将图层拆分为两段（保留完整连续曲线）         | `Ctrl + Shift + D`                   |
| 播放 / 暂停预览                        | `Space`（空格键）                         |
| 逐帧前进 / 后退                        | 左右方向键                                |
| 将选中关键帧设为柔和缓动（Easy Ease）          | `F9`                                 |
| 快速筛选位置 / 缩放 / 旋转 / 透明度 / 已设动画的属性 | `P` / `S` / `R` / `T` / `U`          |
| 打开命令面板搜索操作与快捷键                   | `Ctrl + Shift + P`                   |

在时间线上直接拖动关键帧可以调整时间，按住 `Alt` 拖动可复制关键帧，按住 `Ctrl` 点击可多选关键帧。项目树、视口、属性、关键帧、图层、事件和标记区域均支持右键菜单。

## 声音预览与时间线事件（Cues）

除了画面动画，时间线还可以挂载声音轨道与触发事件。

### 音频轨道与波形预览

Effect 支持四种声音来源：

* **原版音效**：填写 Bukkit 枚举名（如 `ENTITY_PLAYER_LEVELUP`）或原版命名空间 ID（如 `minecraft:block.note_block.chime`）。
* **CraftEngine 自定义音效**：填写已注册的命名空间音效 ID（如 `custom:cinematic.whoosh`）。
* **本地 OGG 音频**：将小写的 `.ogg` 文件放入 `plugins/ArcMenu/effects/assets/` 目录下（如 `music/intro.ogg`），在轨道中填写相对路径 `music/intro.ogg`。新增 OGG 文件后，按[图片与资源包](/gong-neng-pei-zhi/resource-packs.md)流程重新构建并分发资源包即可。
* **NBS 红石音乐**：将 `.nbs` 文件（支持 NBS 0–5 版本、原版与自定义音色、音量、声像与微调音高）放入 `effects/assets/` 目录下（如 `songs/intro.nbs`），由服务端直接解析播放。

在编辑器中，**音频预览（Audio Preview）** 会自动读取客户端已加载资源包中的 OGG 音频（包括原版音效、CE 音效和本地 OGG），异步解码并在时间线上绘制出真实的**音频波形**与片段长度。你可以把播放头拖到任意一帧直接试听该位置的音乐，也可以来回拖动播放头听取短促的声音采样，非常适合用来做卡点动画。音频预览支持片段重叠、静音、音高倍速（`pitch`）与工作区循环。

### 触发命令与动作

你还可以在时间线的指定帧添加命令或动作事件。在编辑器里预览或拖动时间线时，所有的命令与动作都会保持静默，不会误触发；只有通过 `/arcmenu effect` 正式播放时，服务端才会在对应帧号准时执行它们。

例如，在动画第 90 帧结束前自动为玩家打开主菜单：

```yaml
cues:
  - id: open-main
    frame: 90
    kind: action
    source: 'open: main'
```

## 文件结构与配置详解

每个 Effect 项目都存放在 `plugins/ArcMenu/effects/<项目ID>/` 目录下，由两个 YAML 文件组成，公共音频素材则统一放在 `effects/assets/` 下：

```
plugins/ArcMenu/effects/
  intro/
    scene.yml       # 画面场景定义（与常规菜单的 canvas 和 frontend 结构一致）
    timeline.yml    # 时间线、图层区间、动画轨道、事件与标记
  assets/
    music/intro.ogg
    songs/intro.nbs
```

下面是一个完整的 `timeline.yml` 示例：

```yaml
schema-version: 1
id: intro
fps: 20
duration: 100
loop: false
work-start: 0
work-end: 100
permission: ''
layers:
  - {target: title, start: 0, end: 100, enabled: true, solo: false}
tracks:
  - target: title
    property: offset.x
    enabled: true
    keys:
      - {frame: 0, value: '-100', interpolation: bezier, curve: [0.25, 0.1, 0.25, 1]}
      - {frame: 30, value: '0', interpolation: hold}
      - {frame: 75, value: '0', interpolation: ease-in}
      - {frame: 100, value: '100'}
cues:
  - {id: chime, frame: 10, kind: sound, source: 'minecraft:block.note_block.chime', volume: 0.8, pitch: 1.0}
  - {id: bgm, frame: 0, end: 100, kind: sound, source: 'music/intro.ogg', volume: 1.0, pitch: 1.0}
  - {id: song, frame: 0, end: 80, kind: nbs, source: 'songs/intro.nbs'}
  - {id: player-cmd, frame: 40, kind: command, source: 'me 正在观看开场演出'}
  - {id: console-cmd, frame: 50, kind: console, source: 'say 欢迎来到服务器'}
  - {id: next-menu, frame: 95, kind: action, source: 'open: main'}
markers:
  - {frame: 30, label: 标题定格}
```

各字段的有效取值说明如下：

* `schema-version`：固定填整数 `1`。
* `id`：项目唯一标识符，需与所在文件夹名称及 `scene.yml` 中的 `id` 保持一致。
* `fps`：每秒钟包含的时间线帧数，可填写 `1` 到 `120` 之间的有限数值（支持整数与小数，常用 `20`）。
* `duration`：时间线结束帧号，填写 `1` 到 `432000` 之间的整数，且总时长 `duration / fps` 不超过 `3600` 秒（1 小时）。比如 `fps: 20` 且 `duration: 100` 代表整段动画长 5 秒。正式播放会完整演完第 `100` 帧后再清理画面。
* `loop`：填 `true` 或 `false`。设为 `true` 时，正式播放与预览都会循环执行，每轮循环都会触发一次时间线事件。
* `work-start` 与 `work-end`：整数帧号，用于限定编辑器内预览播放与循环的起止区间，需满足 `0 <= work-start < work-end <= duration`，不影响正式播放的总时长。
* `permission`：字符串。填写玩家观看该动画所需的额外权限节点；留空 `''` 表示只需默认的 `arcmenu.effect` 权限即可观看。
* `layers`：定义各元素图层的生命周期与状态。`target` 填 `scene.yml` 中的前端元素 ID，`start` 和 `end` 为半开区间 `[start, end)` 的起止帧号，`enabled` 控制图层是否显示，`solo` 控制是否独奏该图层及其子元素。
* `tracks`：属性动画轨道列表。`target` 为目标元素 ID，`property` 为属性路径，`enabled` 控制该轨道是否生效，`keys` 为按 `frame` 升序排列的关键帧列表。
* `cues`：时间线事件列表。每项包含唯一 `id`、触发帧 `frame`（声音与 NBS 可选填结束帧 `end`）、类型 `kind` 以及内容 `source`：
  * `kind: sound`：播放原版音效、CE 音效或 `effects/assets/` 下的相对 `.ogg` 路径，可选填 `volume`（音量，取值范围 `0` 到 `4`，默认为 `1`）和 `pitch`（音高，取值范围 `0.01` 到 `4`，默认为 `1`）。
  * `kind: nbs`：播放 `effects/assets/` 下的相对 `.nbs` 路径。
  * `kind: command`：以观看玩家的身份执行一条不含斜杠的命令，支持占位符解析。
  * `kind: console`：以服务端控制台身份执行命令，支持占位符解析。
  * `kind: action`：执行一条标准 ArcMenu 动作表达式（语法见[动作与导航](/cai-dan-pei-zhi/menus/actions.md)）。
* `markers`：时间线标记列表，包含 `frame`（帧号）与 `label`（备注文字），方便在编排时标记节奏点。


---

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