aibis-dream/Docs/D2Sleep表现系统拆分与存档重构方案.md

D2 Sleep 表现系统拆分与存档重构方案

目标

将 D2 Sleep 新增的轱辘、风筝、全屏序列帧、虚焦和门近景控制从通用 SpriteShowcase 中剥离，同时为通用图片与 D2 专属表现分别建立可扩展的语义快照。

本次重构保持 Yarn 命令名、参数默认值、Addressable key、场景视觉参数和剧情文本不变。

职责边界

SpriteShowcase

只保留跨章节可复用的能力：

• 普通小图显示、隐藏。
• 普通大图显示、隐藏。
• 背景淡入淡出。
• 通用即时清理。
• 通用图片终态的捕获与恢复。
• 在图片切换、隐藏或清理前触发 PresentationChanging，通知场景专属表现清除叠加层。

SpriteShowcase 不再持有 D2 配置、运行时节点、遮罩、序列帧协程、虚焦材质或 D2 Tween。

Day2SleepPresentationController

D2 Sleep 场景级统一入口，负责：

• 普通小图、轱辘、风筝和大图特效的互斥。
• 监听 SpriteShowcase.PresentationChanging 并停止全部 D2 表现。
• 为 Yarn 和 DreamDoorSystem 提供稳定 API。
• 捕获、恢复 D2 专属表现的语义终态。

内部 Presenter：

类型	职责
ReelMotionPresenter	轱辘底图/运动层、SpriteMask、reel_tension 常驻拉锯循环
KitePresentation	风筝相机节点、底图、遮罩、sway/accent 层、资源加载与显隐
KiteRigDriver	风筝连续运动、风况、高度、镜头补偿与对焦算法
LargeSpriteEffectsPresenter	全屏序列帧、虚焦、大图缩放/透明度及 Tween

Yarn 与系统调用

D2 专属命令移动到 Day2SleepYarnCommand：

• show_sprite_motion
• sprite_motion
• kite_show
• kite_state
• kite_wind
• kite_accent
• kite_hide
• show_large_sprite_animation
• set_large_sprite_blur
• tween_large_sprite_blur
• tween_large_sprite_blur_async

普通 show_sprite、show_large_sprite、hide_* 和 Showcase 背景命令仍由 BaseYarnCommand 调用 SpriteShowcase。

DreamDoorSystem 的大图换图、近景缩放和透明度控制调用 Day2SleepPresentationController。Bloom、曝光、海浪和终端逻辑仍属于 DreamDoorSystem。

存档模型

存档只记录可重建的语义终态，不保存 Coroutine、Tween、运行时 GameObject、SpriteMask、材质实例或随机运动瞬时相位。

showcase section

稳定 id：showcase，RestoreOrder：69。

ShowcaseSnapshotDto：

• displayMode：None / Small / Large。
• picName：逻辑图片名，不保存加载后的 Sprite。
• isBackgroundVisible：背景遮罩终态。

恢复时通过 ResourceSystem 重新加载图片，并以 0 秒时长应用终态。

day2SleepPresentation section

稳定 id：day2SleepPresentation，RestoreOrder：70。

Day2SleepPresentationSnapshotDto 按模式保存：

模式	保存内容
SmallMotion	图片名、motion profile
Kite	目标高度、风向、乱度
LargeEffects	序列帧前缀/帧数/帧间隔、虚焦参数、缩放倍率、透明度

kite_accent 属于一次性顿挫，不进入快照；轱辘和风筝的随机相位在恢复后从对应语义状态重新开始。

若当前没有 D2 专属状态，Provider 返回 null，不写入该 section。通用大图叠加了 D2 虚焦或门近景效果时，会同时写入 showcase 与 day2SleepPresentation：先恢复底图，再恢复特效。

恢复顺序

相关表现 Provider 顺序为：

1. showcase（69）：恢复普通底图和背景。
2. day2SleepPresentation（70）：恢复 D2 动态层或大图特效。
3. playTool（71）：恢复物品展示 UI。
4. screen（80）：恢复饱和度和全屏遮罩。

旧存档没有新增 section 时直接跳过，不提升 schemaVersion。旧 showcase JSON 中的额外字段由 Json.NET 忽略。

场景迁移

梦境 场景保留原 SpriteShowcase 组件及脚本 GUID，只留下三个 Renderer 引用。新增 Day2SleepPresentationController，迁移原对焦材质和三组风筝设置。轱辘、风筝和遮罩节点仍在运行时动态创建。

生命周期清理

• 普通图片切换前：PresentationChanging 清理 D2 表现。
• D2 模式切换前：控制器清理普通图片与上一种 D2 表现。
• 返回菜单、切章和读档前：GameManager 分别清理 D2 控制器与 SpriteShowcase。
• 组件禁用或销毁：停止 Coroutine/Tween、隐藏运行时节点、关闭 SpriteMask，并恢复大图材质属性、缩放和透明度。

验证范围

• Unity 编译和现有 EditMode 测试通过。
• FP/Fiction Day1 普通小图、大图和背景淡入淡出无回退。
• D2 Sleep 轱辘、风筝、全屏序列帧、星图虚焦和 DreamDoor 近景表现保持一致。
• 普通图片命令能中断并清理任意 D2 动效。
• 通用小图/大图、风筝、轱辘、序列帧和大图特效可按快照恢复。
• 返回菜单、切章、读档和重复进入梦境后没有残留动态节点、材质属性或 DOTween。

不在本次范围

• 不保存动画的逐帧进度、Tween 中间值或随机种子。
• 不重构 Bloom、曝光和 DreamDoorSystem 自身状态机。
• 不修改 Yarn 剧情内容或 #line: 标签。
• 不修改现有资源名、Addressable key 和视觉参数。