# 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。