48 lines
2.2 KiB
Markdown
48 lines
2.2 KiB
Markdown
# FrameAnimation Actor 接入说明
|
||
|
||
帧动画角色通过 `ActorManager` 的显式 `FrameAnimation` 类型接入。旧的 `Sprite`、`Anima`、`AnimaEx` 行为不变。
|
||
|
||
## 资源约定
|
||
|
||
1. 为角色制作并校验 `FrameAnimationGraph`。
|
||
2. 将 Graph 加入对应场景的 Addressable Group，地址必须是：
|
||
|
||
```text
|
||
FrameAnimation/{actorName}
|
||
```
|
||
|
||
例如角色名为 `测试角色`，Graph 地址就是 `FrameAnimation/测试角色`。
|
||
3. 通用角色 Prefab 使用 `Prefab/FrameAnimationActor`，由框架持久化加载；角色 Graph 由当前场景的 `ResourceSystem` 加载并随场景释放。
|
||
|
||
Graph 必须通过 `FrameAnimationGraphValidator` 校验。帧动画角色不会自动播放 `defaultPlayableId`，初始化后等待剧情或业务代码明确指定 playable。
|
||
|
||
## Yarn 用法
|
||
|
||
初始化时显式传入类型：
|
||
|
||
```yarn
|
||
<<init_actor 测试角色 clinic FrameAnimation>>
|
||
<<change_actor_state Idle 测试角色>>
|
||
```
|
||
|
||
等待一次性动画播放完成，或按 Flow 配置等待 Loop：
|
||
|
||
```yarn
|
||
<<change_actor_state_async Intro 测试角色>>
|
||
```
|
||
|
||
`init_actor` 会等待 Prefab 和 Graph 加载完成，因此紧随其后的状态切换可以安全执行。直接异步播放 Loop Clip 时，完成第一轮后继续执行 Yarn。对于“前置节点 → 终点 Loop”的 Flow，等待时机由 Flow 的 **Async Completion** 决定：默认在前置节点结束、终点 Loop 首帧显示后继续；也可以配置为等待终点 Loop 完整播放第一轮。命令返回后动画仍会继续循环，直到被新状态替换或主动停止。完全无需等待时仍可使用 `change_actor_state` 立即继续 Yarn。
|
||
|
||
## 存档行为
|
||
|
||
帧动画角色复用 `sections["actor"]`，保存角色类型、名称、槽位、透明度和当前 playable id，不记录中途帧进度。
|
||
|
||
读档时：
|
||
|
||
- `HoldLastFrame`：直接显示最后一帧；
|
||
- `Clear`：清空 Sprite；
|
||
- `HideTarget`：禁用 SpriteRenderer；
|
||
- `Loop`：从第一帧重新开始播放，且不会阻塞读档恢复流程。
|
||
|
||
如果 Prefab、Graph 或 playable 缺失，该角色会被跳过并输出结构化错误日志，不会覆盖 ActorManager 中已有的同名有效角色，也不会阻断其他存档 Provider。
|