docs(save): 更新存档系统设计与 README
This commit is contained in:
@@ -41,9 +41,9 @@ SaveSystem/
|
||||
├── SaveSnapshot.cs 快照根对象 + 各 section DTO
|
||||
├── SnapshotProviderIds.cs section 稳定 id（"actor" 等）
|
||||
├── SnapshotRegistry.cs provider 注册表
|
||||
├── SnapshotBootstrap.cs 启动时注册 7 个 provider
|
||||
├── SnapshotCapture.cs 组装 SaveSnapshot
|
||||
├── SnapshotRestore.cs 写回运行时 + 锚点重进节点
|
||||
├── SnapshotBootstrap.cs 启动时注册 6 个 provider
|
||||
├── SnapshotCapture.cs 组装 SaveSnapshot（scene / anchor 由框架直管）
|
||||
├── SnapshotRestore.cs 写回运行时（scene / anchor 由框架直管）
|
||||
├── SnapshotService.cs Capture / Restore 对外 API
|
||||
├── SnapshotPersistence.cs 文件读写、旧档检测
|
||||
├── SnapshotSerializer.cs JSON + schemaVersion
|
||||
@@ -52,13 +52,12 @@ SaveSystem/
|
||||
├── DeepRepairSnapshot.cs 深度维修占位（P5）
|
||||
├── DeepRepairDataRegistry.cs 旧 IData 容器（P5 前）
|
||||
├── ScreenSnapshotHelper.cs screen section 实现细节
|
||||
└── Providers/ 各子系统薄适配层
|
||||
├── SceneSnapshotProvider.cs order 10
|
||||
└── Providers/ 表现层子系统薄适配层
|
||||
├── EnvironmentSnapshotProvider.cs order 20
|
||||
├── MacroSnapshotProvider.cs order 30
|
||||
├── ActorSnapshotProvider.cs order 40
|
||||
├── AudioSnapshotProvider.cs order 50
|
||||
├── TimelineSnapshotProvider.cs order 60
|
||||
├── FixSnapshotProvider.cs order 65
|
||||
└── ScreenSnapshotProvider.cs order 70
|
||||
```
|
||||
|
||||
@@ -68,7 +67,7 @@ SaveSystem/
|
||||
存盘:
|
||||
SaveRestoreOrchestrator
|
||||
→ SnapshotService.Capture()
|
||||
→ SnapshotCapture（锚点 + Yarn 变量 + 各 Provider）
|
||||
→ SnapshotCapture（场景 + 锚点 + Yarn 变量 + 各 Provider）
|
||||
→ SnapshotPersistence.Save()
|
||||
|
||||
读盘:
|
||||
@@ -84,30 +83,34 @@ SaveSystem/
|
||||
|
||||
### 终态：Phase + Barrier
|
||||
|
||||
读档不是「每个 Provider 串行协程链」，而是分阶段推进，仅在**必须等待**的边界上 `yield`：
|
||||
读档分阶段推进，仅在**必须等待**的边界上 `yield`：
|
||||
|
||||
```
|
||||
Phase 0 Yarn 变量（sync）
|
||||
↓
|
||||
Phase 1 场景加载（Barrier：LoadSceneAsync）
|
||||
Phase 1 场景加载（Barrier：LoadSceneAsync）← 框架直管，不走 Provider
|
||||
↓
|
||||
Phase 2 macro / env / actor / audio / timeline / screen（sync 批量，同帧连续调用）
|
||||
Phase 1.5 设置章节 SO（sync）← 框架直管，从 anchor.sceneSoName 读取
|
||||
↓
|
||||
Phase 2 env / actor / audio / timeline / fix / screen（Provider 按 RestoreOrder）
|
||||
↓
|
||||
Phase 2′ 可选 Barrier（如 Timeline Addressable 须显式等待）
|
||||
↓
|
||||
Phase 3 RestoreAnchor（Barrier：StartDialogue）
|
||||
Phase 3 加载对话工程 + RestoreAnchor（Barrier：StartDialogue）← 框架直管
|
||||
↓
|
||||
Phase 4 P4：淡入淡出等演出时序
|
||||
```
|
||||
|
||||
- **核心层**（`scene`、`anchor`、`yarnVariables`）由 `SnapshotRestore` 框架直管，不通过 Provider 注册。
|
||||
- **表现层**（`sections` 内各子系统）通过 `ISnapshotProvider` 扩展；`RestoreOrder` 表示同 Phase 内的建议顺序或软依赖。
|
||||
- **逐项还原（D1）**指各子系统各自写回状态，**不是** Provider 之间逐步 `yield return`。
|
||||
- **`RestoreOrder`** 表示同 Phase 内的建议顺序或软依赖（scene 先于 env/actor 等），**不是**「每步必须挂协程」。硬依赖用 Phase / Barrier 表达。
|
||||
|
||||
### P1 临时形态 vs P4 目标
|
||||
|
||||
| | P1（当前） | P4 目标 |
|
||||
| --- | --- | --- |
|
||||
| Provider 还原 | 全部 `IEnumerator Restore` | 默认 `void Restore`；仅 scene 等实现显式 async |
|
||||
| 核心层还原 | 硬编码在 `SnapshotRestore` | 保持框架直管 |
|
||||
| Provider 还原 | 全部 `IEnumerator Restore` | 默认 `void Restore`；仅需 async 加载的实现显式协程 |
|
||||
| 编排 | `foreach` 逐步 `yield return` | Phase 编排，仅 Barrier 步骤 `yield` |
|
||||
| Manager | 部分 `IEnumerator RestoreSnapshot` 仅 `yield break` | 默认 `void`；真有 async 才保留协程 |
|
||||
|
||||
@@ -120,14 +123,17 @@ Phase 4 P4：淡入淡出等演出时序
|
||||
|
||||
| 字段 | 含义 |
|
||||
| --- | --- |
|
||||
| `anchor` | 恢复锚点：`nodeName` + `yarnProjectId`（独立阶段重进节点的自洽校验） |
|
||||
| `scene` | 当前场景名（Addressable key），读档时最先加载 |
|
||||
| `anchor` | 恢复锚点：`sceneSoName` + `yarnProjectId` + `nodeName`；最后阶段加载对话并重进节点 |
|
||||
| `yarnVariables` | floats / strings / bools |
|
||||
| `sections` | key 为 `SnapshotProviderIds`，值为各 DTO；**宏观信息（场景/SceneSO/YarnProject）以 `scene`/`macro` 两节为唯一来源** |
|
||||
| `deepRepair` | P1 通常为空，P5 再填 |
|
||||
| `sections` | key 为 `SnapshotProviderIds`，值为各 DTO；**表现层状态（env / actor / audio / timeline / fix / screen）** |
|
||||
| `deepRepair` | **P5 深度维修**（BlockPuzzle / Cutting / AnalysisMode 等）。P1 阶段已预留 `DeepRepairSnapshotDto`，但详细子系统状态暂不捕获；待存档系统主干稳定后再补充并测试 |
|
||||
|
||||
> 宏观阶段摘要不再冗余到顶层；槽位 / 「继续游戏」UI 需要展示场景名、章节、YarnProject 时，调用 `SaveSnapshotSummary.From(snapshot)` 从 `sections` 现算派生。
|
||||
> 宏观信息（场景、章节、节点）直接位于 `SaveSnapshot` 根对象，不再冗余到 `sections`；槽位 / 「继续游戏」UI 需要展示时，从 `scene` / `anchor` 直接读取。
|
||||
|
||||
## 新增一个可存子系统
|
||||
## 新增一个可存子系统（表现层）
|
||||
|
||||
表现层子系统通过 Provider 注册到 `sections`：
|
||||
|
||||
1. 在 `SaveSnapshot.cs` 增加 DTO 类。
|
||||
2. 在 `SnapshotProviderIds` 增加稳定 id，并加入 `RequiredForCapture`（若 P1 必须存）。
|
||||
@@ -138,6 +144,39 @@ Phase 4 P4：淡入淡出等演出时序
|
||||
|
||||
**禁止**在 Provider 内私自 `StartCoroutine` 而不纳入编排 Barrier。
|
||||
|
||||
> **例外**：`scene`（场景加载）与 `anchor`（章节+节点重进）属于**核心叙事坐标**，由 `SnapshotCapture` / `SnapshotRestore` 框架直管，不走 Provider 注册。新增「核心层」字段需修改 `SaveSnapshot` 根对象与对应编排方法。
|
||||
|
||||
## Fix 场景快照（P1 接口层完成）
|
||||
|
||||
Fix 场景（维修场景）的快照存储在 `sections["fix"]`，由 `FixSnapshotProvider`（order 65）管理。
|
||||
|
||||
### 为什么 FixStateMachine 放在 sections 而不是 deepRepair？
|
||||
|
||||
FixStateMachine 不仅管理深度维修（Eye、Memory、EmoWave 等），还管理 **Clinic（诊所）** 和 **BodyModule（插线维修）** 等非深度维修状态。把它放在 `sections` 中作为表现层子系统之一，可以避免概念错位。
|
||||
|
||||
### 双入口设计：Enter vs EnterImmediate
|
||||
|
||||
Fix 场景各 State 的 `Enter()` 通常包含相机过渡、Timeline 播放、Fade 等动画。读档时需要跳过这些动画直接到达终态，因此为 `IFixState` 增加了 `EnterImmediate()` 入口：
|
||||
|
||||
- 正常游戏流程 → `Enter()`（完整动画）
|
||||
- 读档恢复 → `SwitchStateImmediate()` → `EnterImmediate()`（跳过动画）
|
||||
|
||||
读档时 `SwitchStateImmediate` **不调用前一个状态的 Exit()**，因为读档本质是覆盖当前状态，不需要清理。
|
||||
|
||||
### P1 已落地的接口
|
||||
|
||||
- `FixSnapshotDto`：state、args、moduleState、eyeColorState、isSystemOn、currentRepairSystemType
|
||||
- `IFixState` 接口 + `EnterImmediate()` 默认实现
|
||||
- `FixStateMachine.SwitchStateImmediate()`
|
||||
- `FixSystemCenter.CaptureSnapshot()` / `RestoreSnapshot()`
|
||||
- `FixSnapshotProvider` 注册到 `SnapshotBootstrap`
|
||||
|
||||
### 尚未实现（P4/P5）
|
||||
|
||||
- 各 State 的 `EnterImmediate()` 具体逻辑（当前默认 `yield break`）
|
||||
- 深度维修子系统详细状态（BlockPuzzle grid、Cutting 进度等）→ P5 `deepRepair`
|
||||
- Fix 场景读档的 Fade 时序 → P4 编排层
|
||||
|
||||
## 相关阶段（未在本目录完整实现）
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
fileFormatVersion: 2
|
||||
guid: 640eb38f8d444db448a71058005e1c7b
|
||||
TextScriptImporter:
|
||||
externalObjects: {}
|
||||
userData:
|
||||
assetBundleName:
|
||||
assetBundleVariant:
|
||||
+7
-7
@@ -14,8 +14,8 @@
|
||||
|
||||
- 需求来源：`Docs/存档系统需求.md`
|
||||
|
||||
- 当前阶段：**P1 快照层已实现**；原 `StorageSystem` 已重命名为 `YarnVariableStorage` 并完成职责拆分。
|
||||
- 最近更新：2026-06-02（明确读档还原编排终态与 P1 Provider 临时形态）。
|
||||
- 当前阶段：**P1 快照层已实现**；原 `StorageSystem` 已重命名为 `YarnVariableStorage` 并完成职责拆分；FixStateMachine 接口与 DTO 已接入。
|
||||
- 最近更新：2026-06-11（Fix 场景快照接口层落地，P1 DTO 设计告一段落；深度维修待 P5）。
|
||||
|
||||
|
||||
|
||||
@@ -187,7 +187,7 @@
|
||||
|
||||
| `SnapshotSerializer` | `SaveSystem/` | schemaVersion、稳定 SaveId key |
|
||||
|
||||
| `SnapshotRegistry` + `Providers/*` | `SaveSystem/` | 7 个表现类 / 宏观 provider |
|
||||
| `SnapshotRegistry` + `Providers/*` | `SaveSystem/` | 6 个表现层 Provider（env / actor / audio / timeline / fix / screen） |
|
||||
|
||||
|
||||
|
||||
@@ -251,7 +251,7 @@ Phase 1 Barrier（异步）
|
||||
|
||||
Phase 2 同步批量还原（同帧连续调用，不逐步 yield）
|
||||
|
||||
└─ macro / env / actor / audio / timeline / screen …
|
||||
└─ macro / env / actor / audio / timeline / fix / screen …
|
||||
|
||||
│
|
||||
|
||||
@@ -295,7 +295,7 @@ Phase 4 Barrier（P4：淡入淡出等演出时序）
|
||||
|
||||
| 场景加载 | **是** | 唯一 P1 中 Provider 层真正需要等待的 async |
|
||||
|
||||
| macro / env / actor / audio / screen | 否（Phase 2 sync） | 当前实现均为同步写回 |
|
||||
| macro / env / actor / audio / fix / screen | 否（Phase 2 sync） | 当前实现均为同步写回；fix 的 `EnterImmediate` 默认 `yield break` |
|
||||
|
||||
| timeline（本地终态） | 否（Phase 2 sync） | `RestoreAtEndLocal` 等 |
|
||||
|
||||
@@ -317,7 +317,7 @@ Phase 4 Barrier（P4：淡入淡出等演出时序）
|
||||
|
||||
- 硬依赖应通过 **Phase 划分 + Barrier** 表达，而不是无限细化 RestoreOrder 数字。
|
||||
|
||||
- scene（10）必须在 Phase 2 之前完成；macro 必须在 RestoreAnchor 之前完成；env / actor / audio / timeline / screen 之间目前无硬依赖，Phase 2 内一批执行即可。
|
||||
- scene 加载（Phase 1 Barrier）必须在 Phase 2 之前完成；设置章节 SO（Phase 1.5）必须在 RestoreAnchor 之前完成；env / actor / audio / timeline / fix / screen 之间目前无硬依赖，Phase 2 内一批执行即可。
|
||||
|
||||
|
||||
|
||||
@@ -413,7 +413,7 @@ P7 横切
|
||||
|
||||
- `SaveSnapshot` 纯数据结构 + `ISnapshotProvider` 逐项还原（D1/D1.1）。
|
||||
|
||||
- Provider：`scene` / `macro` / `env` / `actor` / `audio` / `timeline` / `screen`。
|
||||
- Provider：`scene` / `macro` / `env` / `actor` / `audio` / `timeline` / `fix` / `screen`。
|
||||
|
||||
- Yarn 变量经 `YarnVariableStorage` 纳入快照；`$data.*` 死路径已移除。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user