# ichni Official 剧情系统整合、配置与测试手册

> 适用对象：程序员、Technical Designer、负责 Unity 配置和剧情 QA 的成员  
> 适用项目：`ichni Official`  
> 当前实现：Yarn Spinner `3.2.1`、Unity Localization、ES3、DOTween  
> 最后更新：2026-07-21

本文说明如何把剧本编写者交付的 Yarn Scripts 整合进游戏，并配置 StoryData、角色、Timeline、Helper、存档和测试流程。CreatorStudio 不参与本套任务；只有未来任务明确触及节奏游戏元素、共享序列化结构或 Creator 导入流程时，才需要重新评估跨项目同步。

## 1. 系统边界与数据流

```text
StoryData（静态剧情图、条件、Marker、默认变量）
    -> StoryTreeController（生成 Block、推导状态、处理回滚）
        -> TextBlockView -> StoryDialogueController -> DialogueRunner
            -> VNDialoguePresenter / VNPortraitStage / DialogUIPage
            -> StoryProgress -> StorySaveModule -> ES3
        -> SongBlockView -> SongSaves.isTried
        -> TutorialBlockView -> TutorialFlowController
    -> StoryTimelineController（Marker 投影、进度、回滚入口）
    -> StoryHelperController（全局 HelperData、条件对话池）
```

三套持久化数据必须保持隔离：

| 数据域 | 主要内容 | 回滚本章时是否变化 |
|---|---|---|
| `SongSaveModule` | `isTried`、`isCompleted`、Accuracy、MaxCombo、FC/AP、Chart Revision | 否 |
| `StorySaveModule` | Completed Blocks、章节变量、选项、Marker 快照 | 是，仅当前章节 |
| `UnlockSaveModule` | Offline 内容 Key | 否 |

## 2. 主要代码和资产

| 路径 | 职责 |
|---|---|
| `Assets/Scripts/NewStorySystem/Data/StoryData.cs` | 运行时章节数据与查询 |
| `Assets/Scripts/NewStorySystem/Data/StoryData.Editor.cs` | StoryData Validation 与 Inspector Preview |
| `Assets/Scripts/NewStorySystem/Data/StoryBlockDefinition.cs` | Block 类型、布局、条件和类型专属字段 |
| `Assets/Scripts/NewStorySystem/Data/StoryConditionNode.cs` | AND / OR / NOT / Variable / BlockCompleted 条件树 |
| `Assets/Scripts/NewStorySystem/Tree/StoryTreeController.cs` | 生成、状态推导、连接、完成、回滚 |
| `Assets/Scripts/NewStorySystem/Dialogue/StoryDialogueController.cs` | TextBlock 对话事务与 Yarn Project 切换 |
| `Assets/Scripts/NewStorySystem/Dialogue/VNDialoguePresenter.cs` | 台词、选项、快进、记录 |
| `Assets/Scripts/NewStorySystem/Dialogue/VNPortraitStage.cs` | 动态立绘实例和动画入口 |
| `Assets/Scripts/NewStorySystem/Save/StorySaveModule.cs` | 按章节 ES3 存档与事务 |
| `Assets/Scripts/NewStorySystem/Timeline/StoryTimelineController.cs` | Marker、刻度同步、进度和确认回滚 |
| `Assets/Scripts/NewStorySystem/Helper/StoryHelperController.cs` | 全局 Helper、加权随机台词和气泡 |
| `Assets/Scripts/NewStorySystem/YarnFunctions/` | 项目专有 Yarn Commands / Functions |
| `Assets/Story/Chapter0/` | Chapter 0 StoryData、Yarn Project、Yarn Scripts、CharacterRegistry |
| `Assets/Localization/Story/` | 当前 Yarn 台词 Unity String Table Collection |

## 3. 新章节整合流程

### 3.1 确定稳定 Chapter Index

`ChapterSelectionUnit.chapterIndex`、`StoryData.chapterIndex`、`StoryManager.storyDatas` 的 Dictionary Key 必须完全一致，包括大小写。

当前 Chapter 0 使用：

```text
Chapter0
```

`StoryTreeController.BuildChapter` 会在运行时报告三者不一致，但不会擅自改写资产。

### 3.2 创建章节目录和 Yarn Project

建议结构：

```text
Assets/Story/Chapter1/
    Chapter1.yarnproject
    StoryData_Chapter1.asset
    CharacterRegistry.asset（也可改为全局 Registry，需统一引用）
    C1_Intro.yarn
    C1_Checkpoint.yarn
    ...
```

Yarn Project 的 `Source Yarn Scripts` 建议使用 `**/*.yarn`，并确保不会把其它章节目录意外包含进来。Node 名必须在该 Project 内唯一。

### 3.3 创建 StoryData

使用：

```text
Create > Ichni > Story > New > StoryData
```

配置：

1. `Chapter Index`：与章节资产完全一致。
2. `Yarn Project`：拖入本章节 Yarn Project。
3. `Initial Variables`：登记章节变量的默认值和类型。
4. `Blocks`：配置完整静态剧情图。
5. `Timeline Markers`：配置重要时间点。
6. `Exclusive Route Groups`：只用于 Validation，登记互斥终点组。

最后在场景 `StoryManager.storyDatas` 中添加：

```text
Key: Chapter1
Value: StoryData_Chapter1
```

## 4. Initial Variables

每个变量定义包含：

- `Key`
- `Type`：Bool / Int / Float / String
- 对应类型的 `Default`

默认值不写入玩家存档。只有 Yarn 或其它剧情入口第一次写入同名变量时，才产生存档覆盖值。`remove_variable` 会删除覆盖值，使读取重新回到 StoryData 默认值。

建议所有 Yarn 会读写的变量都在 `Initial Variables` 登记，即使运行时允许首次写入未声明变量。这样能让策划、程序员和 Validation 审阅时看到章节完整变量表。

## 5. Block 通用配置

### 5.1 Identity 与 Layout

- `ID`：稳定唯一，连接、存档、选项和 Marker 都依赖它。
- `Type`：Text / Song / Tutorial。
- `Column`：叙事时间向右推进；列坐标代表 Block 中心点。
- `Row`：路线位置，正数向下、负数向上。

运行时默认步距：

- `columnStep = 720`
- `rowStep = 525`
- `helperReservedLeftSpace = 400`

Prefab 自己决定尺寸，控制器不覆盖 `sizeDelta`：

| Block | 当前设计尺寸 |
|---|---|
| Important Text | `600 x 375` |
| Secondary Text | `400 x 200` |
| Song | `400 x 100` |
| Tutorial | `400 x 100` |

如果未来修改 Prefab 尺寸，还要同步 `StoryData.Editor.cs` 中的 Preview 尺寸常量。

### 5.2 Next Blocks 与 Connected Rule

`Next Blocks` 同时承担：

- 运行时连接线。
- 目标 Block 的自动前置条件来源。

目标 Block 的 `Connected Rule`：

| 规则 | 语义 |
|---|---|
| `Require All Direct Predecessors` | 所有直接前置完成后可用；默认值 |
| `Require Any Direct Predecessor` | 任一直接前置完成即可；用于互斥分支汇合 |
| `Ignore Connections` | 连线只作视觉用途，不参与解锁 |

自动连接条件与手写 `Unlock Condition` 按 AND 合并。没有前置连接的入口 Block 不受自动条件限制。

### 5.3 Unlock 与 Forbidden

两者共用 `StoryCondition`：

- `All Of (AND)`
- `Any Of (OR)`
- `Not`
- `Block Completed`
- `Variable Compare`

状态优先级：

```text
Forbidden > Completed > Current > Locked
```

互斥路线应同时配置 Unlock 和 Forbidden。例如：

```text
Route A Unlock:    c0_signal_route == 1
Route A Forbidden: c0_signal_route == 2

Route B Unlock:    c0_signal_route == 2
Route B Forbidden: c0_signal_route == 1
```

不要为相同语义再增加一套 Route Binding 字段；运行时路线始终以通用条件树为准。

## 6. TextBlock 配置

字段：

- `Yarn Node`：点击时启动的入口 Node。
- `Title Key`：Block 标题的 Unity Localization Entry Key。
- `Importance`：Important / Secondary。

当前限制：`TextBlockView` 仍直接把 `titleKey` 字符串显示到 TMP，没有解析 Unity Localization。这是发布前本地化待办；配置时仍应从现在开始填写正式 Key，避免后续迁移时重新清点内容。

TextBlock 运行流程：

1. `StoryDialogueController` 检查 Runner、章节上下文和 Yarn Node 是否存在。
2. 复制 `ChapterStorySave` 并开始事务。
3. `StoryProgress.BeginBlockMutation` 捕获同列 Marker 快照。
4. Yarn 运行，选项和变量只修改内存。
5. 正常结束：完成 Block、提交 ES3、执行排队的解锁/Message。
6. Back 或启动失败：恢复进入前快照并刷新现有 StoryTree。

## 7. SongBlock 配置

字段：

- `Song ID`：必须等于目标 `SongItemData.songName`，不能使用 `displaySongName`。
- `Illustration Y`：范围 `-74.25` 到 `74.25`。

插画和曲名资料由 `ChapterSelectionUnit` 中的 `SongItemData` 提供，不在 StoryData 重复维护。

完成规则：

- 玩家确认进入目标歌曲时，`InformationTransistor.PrepareGameLaunch` 调用 `SongSaveModule.MarkSongTried`。
- `SongStatusSave.isTried = true` 是 SongBlock 的唯一持久化完成事实。
- 即使玩家进入后中途退出，也算尝试并完成对应 SongBlock。
- Timeline 回滚不会把 `isTried` 改回 false；重新构建剧情树会再次把该 SongBlock 同步为完成。

同时仍要通过 `UnlockSaveModule.CanEnterSong` 检查章节和歌曲授权，SongBlock 不能绕过普通选曲的锁定规则。

## 8. TutorialBlock 配置

字段：

- `Display Name`
- `Tutorial Key`：`TutorialCollection` 的稳定 Key。
- `Progress Variable`：玩家选择游玩或跳过后写入 `true` 的章节变量。
- `Difficulty Save ID`：目标 `DifficultyData.saveDifficultyId`，不是列表下标。

玩家每次点击 Completed TutorialBlock 都可以重新选择游玩或跳过。第一次选择任一项时会立刻完成 TutorialBlock 并解锁后续；游玩教程不等待结算。

当前 `TutorialFlowController` 的“游玩教程/跳过教程”文本仍是硬编码中文，发布前需要迁移到 Unity Localization。

## 9. Timeline Marker

每个 Marker 配置：

- `Marker ID`：章节内唯一。
- `Anchor`：必须是 TextBlock ID。
- `Label Key`：时间或特殊叙事文本的 Unity Localization Key。
- `Main Progress`：是否参与主线百分比。
- `Value`：完成 Anchor 后贡献的 `0..1` 进度；互斥结局都可以是 `1`。

显示规则：

- Anchor 为 `Current` 或 `Completed`：显示。
- Anchor 为 `Locked` 或 `Forbidden`：隐藏。

位置直接读取 Anchor TextBlock 的实际视觉中心，并监听 Story ScrollRect；装饰刻度使用一张 `Image Type = Tiled` 的 Repeat Image 跟随同一横向位移。

点击 Marker 只有在对应“列之前快照”已经创建后才可交互。确认回滚会重置目标列及右侧的 Block、选项和章节变量，并删除失效的后续 Marker 快照。

当前 Timeline 回滚确认框仍有硬编码中文；发布前需要迁移到 Unity Localization。

## 10. Exclusive Route Groups

该列表只用于编辑器 Validation，不参与 Runtime。

一个 Group 应包含同一章节中互斥的两个或多个终点 Block。Validation 会检查：

- Group ID 是否有效和重复。
- 终点 Block 是否存在和重复。
- 终点是否仍有 Next Block。
- 互斥终点是否配置了 Forbidden Condition。

通用条件树可以表达任意复杂条件，Validation 无法数学证明两条路线真正互斥，最终仍需人工测试。

## 11. Yarn 与 Unity Localization

所有新剧情文本只使用 Unity Localization。

### 11.1 Yarn Project Inspector

选中 `.yarnproject` 后检查：

1. `Source Yarn Scripts` 覆盖正确目录。
2. `Base Language` 与 Yarn 源文本语言一致。
3. 开启 `Use Unity Localisation System`。
4. `String Table Collection` 指向目标 Unity String Table Collection。
5. 点击 `Add Line Tags to Yarn Scripts`，为缺少 ID 的台词和选项生成 `#line:`。
6. 保存并重新导入，确认 Yarn Project 没有编译错误。

当前 Chapter 0 使用 `Chapter0_Lines`，而 `StoryDialogueController` 已预留统一 `yarnLinesTable`。在 Chapter 1 大量接入前，推荐把各章节 Yarn 台词统一到一个 `YarnLines` String Table Collection；这样场景中的单个 `UnityLocalisedLineProvider` 在切换 Yarn Project 时无需同时切换表。

若暂时保留 `Chapter0_Lines`：

- `UnityLocalisedLineProvider.stringsTable` 必须指向 `Chapter0_Lines`。
- `StoryDialogueController.yarnLinesTable` 留空时不会覆盖现有 Provider 配置。

### 11.2 Locale

首发至少验证：

- English：`en`
- Simplified Chinese：`zh-CN`
- Japanese：`ja`
- Korean：`ko`
- Vietnamese：`vi-VN`

新增 Yarn 行后，确认五张 String Table 都有同一 Line ID。不要通过删除并重新生成 Line Tag 的方式“整理”ID，否则会同时影响本地化和已保存选项。

### 11.3 非 Yarn 文本

建议按用途拆表：

| 内容 | 建议 String Table |
|---|---|
| Yarn 台词和选项 | `YarnLines` |
| TextBlock 标题、Timeline、章节标题 | `StoryUI` |
| Helper 名称和气泡 | `StoryHelper` |
| MessageBox / SelectionBox | `Message` |

当前场景中 `StoryTimelineController.localizationTable` 和 `StoryHelperData.localizationTable` 仍为空；完成正式文本接入时必须补齐。

## 12. 角色与立绘配置

### 12.1 CharacterData

创建：

```text
Create > Ichni > Story > New > CharacterData
```

字段：

- `Character ID`：与 Yarn 的 `CharacterName` 完全一致，例如 `Asahi`。
- `Display Name Key`：角色显示名的 Unity Localization Key。
- `Portrait Style`：Sprite / Live2D / Spine。
- `Position Offset`：归一化舞台偏移。
- `Emotion Sprites`：`normal`、`happy`、`angry` 等表情到 Sprite 的映射。
- `Dynamic Portrait Prefab`：未来 Live2D / Spine 使用，必须实现 `IPortraitRenderer`。

把 CharacterData 登记到 `CharacterRegistry.characters`，再把 Registry 赋给场景 `StoryManager.characterRegistry`。

当前限制：`VNDialoguePresenter` 的 Speaker TMP 仍直接显示 Yarn 的 `CharacterName`，尚未通过 `CharacterData.displayNameKey` 本地化。该字段先按规范配置，发布前应补上显示名解析。

### 12.2 VNPortraitStage

场景需配置：

- `_spritePortraitPrefab`
- `_portraitContainer`

Sprite Prefab 必须包含 `SpritePortraitRenderer`；Live2D / Spine Prefab 必须有实现 `IPortraitRenderer` 的组件。

当前舞台按需 Instantiate，`hide_portrait` 时 Destroy。对话数量增大后若发现频繁分配，应再评估池化；现在不要为了未知规模提前重构。

## 13. Dialog 场景装配

`StoryDialogueRoot` 应包含：

- `DialogueRunner`
- `UnityLocalisedLineProvider`
- `VNDialoguePresenter`
- `StoryDialogueController`

`StoryDialogueController`：

- `dialogueRunner`
- `storyUIPage`
- 可选的统一 `yarnLinesTable`

`DialogUIPage`：

- `portraitStage`
- `dialogueText`
- `speakerContainer` / `speakerText`
- `advanceButton`
- `fastForwardButton`
- `backButton`
- `showHistoryButton`
- `dialogueHistoryPage`
- `choiceFrame`
- `choiceButtons`

`DialogueHistoryPage` 必须有全屏可接收 Raycast 的覆盖层；打开时要阻断底层 Dialog 输入。

当前 `MenuScene` 仍启用了调试用 `ConsoleLinePresenter`。它会额外把每行本地化结果输出到 Console；发布构建前应从 DialogueRunner Presenter 列表移除或禁用，只保留 `VNDialoguePresenter`。

## 14. Helper 配置

Helper 使用全局 `StoryHelperData`，不属于单个 StoryData。

字段：

- `Helper ID`
- `Portrait Sprite`
- `Localization Table`
- `Display Name Key`
- `Fallback Dialogue Key`
- `Dialogue Pool`

每条候选包含：

- `ID`
- `Text Key`
- `Availability`：复用 StoryCondition；留空时始终可用。
- `Weight`

运行时会从满足条件的候选中加权随机抽取，并尽量避免连续重复。没有候选时使用 Fallback。`StoryHelperController` 会动态实例化独立 `HelperTalk` Prefab，不使用 MessageBox。

当前 `Assets/Story/StoryHelperData.asset` 的 Localization Table 为空且 Dialogue Pool 为空，只有 Fallback Key；正式 Helper 文本测试前需要配置对应 String Table 和至少一条候选。

## 15. StoryData Validation

在 StoryData Inspector 点击 `Validate Story Data`。Console 现在会输出：

- 一条摘要。
- 每个问题一条独立 Warning 或 Error。

不要再把整份报告拼到同一条多行日志；Unity Console 折叠行不会按内嵌换行扩展高度，会造成文字重叠。

当前 Validation 检查：

- Chapter Index 和 Yarn Project。
- Initial Variable Key 的格式和重复。
- Block ID 重复、Next Block 引用、类型必要字段。
- Yarn Node 是否存在及是否被多个 TextBlock 共用。
- 入口、不可达 Block、环路、非向前连接和终点。
- Unlock / Forbidden 条件树的空节点和无效 Block 引用。
- Timeline Marker ID、Anchor、Label 和重复 Anchor。
- Exclusive Route Groups。
- Yarn 文件中的 `<<declare>>` 和 `<<set $...>>` 旧语法。

Validation 不检查：

- Scene / Prefab 引用是否齐全。
- Song ID 是否真的存在于 ChapterSelectionUnit。
- TutorialCollection 内容。
- Unity Localization Entry 是否齐全。
- 互斥条件是否在逻辑上百分之百正确。
- 所有语言的排版和溢出。

因此 Validation 通过不等于剧情已经达到发布质量。

## 16. 当前 Chapter 0 的已知配置状态

审阅时确认：

- `StoryData_Chapter0.chapterIndex` 已修正为 `Chapter0`，与 ChapterSelectionUnit 和 StoryManager Key 对齐。
- `Chapter0.yarnproject` 的 Base Language 是 `en`，但旧 `C0_A0.yarn` 含中文原文；正式生产前应确定基础语言并统一。
- `C0_A0.yarn` 仍包含废弃的 `declare / set $` 示例，Validation 会逐条报告；此前已经明确该旧台本不作为新系统规范。
- 五份 `C0_RollbackDemo_*.yarn` 是当前永久变量、选项记忆和 Timeline 回滚的测试样例。
- `StoryTimelineController.localizationTable`、`StoryHelperData.localizationTable` 尚未配置。
- TextBlock 标题、Speaker 显示名、Tutorial 选择和 Timeline 回滚确认仍有待完成 Unity Localization 接入。

## 17. 推荐测试顺序

### 17.1 静态检查

1. Yarn Project 无编译错误。
2. StoryData Validation 没有 Error。
3. 所有 Warning 已确认是临时内容还是需要修复。
4. StoryData Preview 中 Block 尺寸、中心列和连线符合预期。

### 17.2 新档主流程

1. 清除当前章节 StorySave。
2. 打开章节，确认只有入口 Block 为 Current。
3. 完成 TextBlock，确认后继解锁并在重启后保持。
4. 在重要选择中选择 Route A，确认 Route B 变为 Forbidden。
5. 再次进入已完成 TextBlock，确认选项自动采用。

### 17.3 对话按钮

1. `Advance` 第一次补全文字、第二次下一句。
2. `FastForward` 只影响当前一次 Dialog。
3. FastForward 可跨过已记忆选项，但不会越过首次选择页面。
4. `History` 只显示当前一次对话，能滚动并阻断底层输入。
5. `Back` 中途退出后，变量、选项、Block 完成状态全部恢复。

### 17.4 Timeline

1. Marker 只在 Anchor Current / Completed 时显示。
2. 横向拖动 StoryTree，Marker 和 Repeat Tick 同步移动。
3. 完成 Marker 所在列后按钮可点击。
4. 回滚后目标列及右侧重新开放，目标列之前保持不变。
5. Song 成绩、`isTried`、Unlock Key、Settings 和其它章节不变。

### 17.5 Song 与 Tutorial

1. SongBlock 自动选中目标歌曲。
2. 只浏览选曲再返回，不写 `isTried`。
3. 确认进入目标歌曲后，即使中途退出，SongBlock 仍完成。
4. Tutorial 选择游玩或跳过都完成 Block。
5. Completed Tutorial 仍可再次点击回顾。

### 17.6 本地化

逐一切换 `en`、`zh-CN`、`ja`、`ko`、`vi-VN`：

1. Yarn 台词与选项正确。
2. Character 名称正确。
3. TextBlock 标题正确。
4. Timeline 文本和回滚确认正确。
5. Helper 名称与气泡正确。
6. MessageBox / SelectionBox 正确。
7. 长文本不溢出，CJK 与越南语字体包含所需字形。

## 18. 常见故障定位

| 现象 | 检查顺序 |
|---|---|
| 点击 TextBlock 无反应 | Block State -> Button -> StoryDialogueController -> Yarn Node -> Yarn Project |
| Yarn Node 不存在 | StoryData 的 Node 名、Yarn Project source glob、编译诊断 |
| 对话退出后变量仍存在 | 是否使用项目 `set_*`；全局副作用是否经过 Commit Queue |
| 选项被意外跳过 | Option Line ID 是否沿用；是否已有 Choice Record；是否错误修改选项组 |
| Marker 不移动 | Story ScrollRect 引用、Marker Container 坐标转换、Anchor View 是否存在 |
| SongBlock 不完成 | `PrepareGameLaunch` 是否调用、Song ID 是否匹配、`SongStatusSave.isTried` |
| SongBlock 错误完成 | 是否有多个章节/歌曲复用了同一个 `songName`；该字段必须全局稳定 |
| Helper 只显示 Key | StoryHelperData Localization Table 或 Entry 缺失 |
| Speaker 显示内部 ID | 当前显示名本地化尚未接入，不能只配置 displayNameKey 就视为完成 |
| Console 出现多份台词日志 | 调试用 ConsoleLinePresenter 仍启用 |

## 19. 发布前剧情系统 Gate

满足以下条件后，剧情和对话系统才可进入 Release 验收：

1. Chapter 0 所有正式 Yarn 台本不再使用废弃临时变量语法。
2. Yarn Base Language 与源文本一致。
3. 五种首发语言的 Yarn、Story UI、Helper、Message 文本齐全。
4. TextBlock 标题、Speaker、Tutorial、Timeline 确认框全部完成 Unity Localization。
5. ConsoleLinePresenter 从发布配置移除。
6. StoryData Validation 无 Error，所有 Warning 有明确处理结论。
7. 两个互斥结局、支线 Forbidden、选项记忆和 Timeline 回滚完成回归测试。
8. SongBlock `isTried`、Tutorial 回顾、Back 回滚、FastForward 会话边界均通过测试。
9. Android、iOS、PC 分别完成长文本、输入和场景往返测试。
10. 正式发布前冻结 Story Save v1；发布后结构变化必须编写迁移，不能继续直接删档。