aibis-dream/Docs/FrameAnimationActor接入说明.md

FrameAnimation Actor 接入说明

帧动画角色通过 ActorManager 的显式 FrameAnimation 类型接入。旧的 Sprite、Anima、AnimaEx 行为不变。

资源约定

1. 为角色制作并校验 FrameAnimationGraph。

2. 将 Graph 加入对应场景的 Addressable Group，地址必须是：

   FrameAnimation/{actorName}
   

   例如角色名为 测试角色，Graph 地址就是 FrameAnimation/测试角色。

3. 通用角色 Prefab 使用 Prefab/FrameAnimationActor，由框架持久化加载；角色 Graph 由当前场景的 ResourceSystem 加载并随场景释放。

Graph 必须通过 FrameAnimationGraphValidator 校验。帧动画角色不会自动播放 defaultPlayableId，初始化后等待剧情或业务代码明确指定 playable。

Yarn 用法

初始化时显式传入类型：

<<init_actor 测试角色 clinic FrameAnimation>>
<<change_actor_state Idle 测试角色>>

等待一次性动画播放完成，或按 Flow 配置等待 Loop：

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