# 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 和视觉参数。