aibis-dream/.cursor/skills/narrative-timeline-flow/SKILL.md

name, description

name	description
narrative-timeline-flow	叙事 Timeline：aseprite/静图改 Timeline、Addressable 登记、黑屏防穿帮、替换 show_full_screen。 Use when 加叙事 timeline、aseprite 转 timeline、英里初登场、CG 演出、替换 show_full_screen、 hide_full_screen、黑屏穿帮、fade_out 时机、wait_timeline、Day1 begin / Day2 night 天桥 CG、 或用户提到 TimelineKit 叙事接入。

叙事 Timeline 接入（Aseprite / 静图 → Yarn）

API 细节见 Assets/Scripts/SceneManagement/TimelineKit/README_TimelineKit.md。本 skill 只记本仓库约定与踩坑。

1. 何时用哪种 Yarn 命令

场景	命令
播完再往下走	<<play_timeline 名>>（阻塞）
黑屏下先起播 / 与对白并行 / Loop CG	<<start_timeline 名>>
已 start_timeline，要等播完	<<wait_timeline 名>>（不重头播）
关掉整棵 Director GO	<<hide_timeline 名>>

名称与场景里 DirectorHandler.timelineName 完全一致（叙事多用中文单名，内嵌 Playable）。

2. 资产与 Addressable

1. Aseprite → Assets/GameContent/Scene_{场景}/animationRaw/（或现有 AnimationRaw/）
2. Timeline → GameContent/Scene_{场景}/Timeline/{名}.playable
3. Addressable Group = 对应场景线（如 Scene_ClinicOut、Scene_Bridge）
4. Address = Timeline/{名}（必须带 Timeline/ 前缀）
5. 叙事 Timeline 一般不加 TimelineAssetRef（维修玩法才用）

参考范本：医生出地铁、day2夕阳医生看佩佩侧脸、英里初登场。

3. 场景 GO 约定

• 根节点挂 PlayableDirector（Play On Awake = false）+ DirectorHandler
• 根节点默认 Active：Start 里要注册到 TimelineCenter；关掉根节点会注册失败
• 带 Sprite 的子物体（如 Visual）默认 Inactive；用 ActivationTrack 或播放时再显
• hide_timeline = 根 SetActive(false)；之后再播时 PlayTimeline 会重新打开
• 全屏 CG 常需调位置（例：天桥侧脸根节点 Y = -5）；PPU / scale 按相机再调

4. 黑屏防穿帮（必做）

错误：fade_out 揭开场景 → 再 play_timeline（先露底再播 CG）。

正确（切场景后的 intro CG）：

<<fade_in>>
<<load_scene Scene/ClinicOut>>
<<init_actor ...>>
<<start_timeline 英里初登场>>
<<wait 0.2>>
<<fade_out>>
<<wait_timeline 英里初登场>>
<<hide_timeline 英里初登场>>
<<show_actor ...>>
<<play_timeline 医生出地铁>>

要点：黑屏内起播并稳住首帧 → 再结束黑屏 → 再等播完。CG 盖住初登场时，角色可延后到 hide_timeline 后再 show_actor。

5. 替换 show_full_screen 静图

常驻 / Loop 演出（对白期间一直播）：

<<start_timeline day2夕阳医生看佩佩侧脸>>
<<fade_out 1>>
# ... 对白 ...
<<fade_in 1>>
<<hide_timeline day2夕阳医生看佩佩侧脸>>
<<fade_out 1>>

不要再用 show_full_screen / hide_full_screen 播同一段。

6. 其它坑

• <<load_scene>> 只需场景名。旧脚本第二参数（如 1）已兼容忽略，新代码不要写。
• 改 .yarn：不要动已有 #line:；新行不加 #line:。
• 只改运行时实际绑定的 Yarn（如 Day1_begin → FP，不是 Fiction 草稿）。
• Aseprite 多 tag：选主演出 clip；Loop CG 用循环 clip + Director Loop 或长轨；一次性 intro 用有限时长 + wait_timeline。

7. 落地检查清单

• Timeline 在正确 GameContent/Scene_* /Timeline/
• Addressable：Timeline/{名} + 正确 Group
• timelineName 与 Yarn 一致；Play On Awake = false
• Visual 默认关；进 Play 不会提前露 CG
• 切场景 intro：黑屏内 start → 短 wait → fade_out → wait_timeline
• 静图替换：start / hide 成对
• 跑一次确认无先露场景、无 load_scene 参数错误