ichni_Official/docs/tutorial-block-system.md

# TutorialBlock 教程流程与 Chapter 0 配置

## 规则

TutorialBlock 点击后通过通用 `SelectionBox` 动态生成“游玩教程 / 跳过教程”两个选项。玩家选择任一选项的瞬间，系统都会：

1. 将 TutorialBlock 的 `tutorialProgressVariable` 写为 `true`。
2. 保存全局剧情变量。
3. 将该 TutorialBlock 标记为 Completed，用于故事树的节点外观；Completed 状态仍允许玩家再次点击回顾教程。
4. 重新计算所有 StoryBlock 的 `UnlockCondition`。

后续 Block 必须通过 `VariableCondition` 读取教程变量解锁，不要依赖 TutorialBlock 的完成记录。选择“游玩教程”后会进入 GameScene；选择“跳过教程”则留在故事树。教程游玩中退出、失败或关闭游戏不会回退已经确认的解锁状态。教程节点完成后仍可再次点击；重复游玩只会重写相同的已处理状态，不会影响已解锁的后续剧情。

## 运行时职责

| 模块 | 职责 |
|---|---|
| `StoryProgress` | 统一执行“写变量、保存、刷新故事树”；`ResolveTutorial` 同时更新教程节点完成状态。 |
| `TutorialFlowController` | 验证 TutorialBlock 配置，并临时组装教程所需的两个 `SelectionBoxOption`。 |
| `MessageUIPage` | MessageBox 与 SelectionBox 共用的弹窗页面：使用同一遮罩、容器和 FIFO 队列，动态生成并依次显示弹窗。 |
| `SelectionBox` / `SelectionBoxButton` | 动态生成任意数量的选项按钮并确保一次显示只执行一个回调。 |
| `TutorialCollection` | 用 `tutorialKey` 查询教程曲目的 `SongItemData`。 |
| `InformationTransistor` | 用 `MenuReturnDestination` 保存唯一的返回目标，替代旧的两个返回 bool。 |

`MenuReturnDestination.SongSelection` 供普通选曲使用；`MenuReturnDestination.Story` 供教程使用。教程从 GameScene 返回时，MenuScene 会显式重建来源章节的 StoryTree。

## Key 命名规则

所有新 Tutorial Key 和剧情变量 Key 只使用小写英文、数字和下划线：

| 用途 | Chapter 0 示例 |
|---|---|
| Tutorial Key | `chapter0_intro` |
| 教程进度变量 | `story_tutorial_chapter0_intro_resolved` |
| TutorialBlock ID（建议） | `tutorial_0_intro` |

不要用显示名称、空格、点号或本地化文本作逻辑 Key。`blockId` 是 StoryTree 内部节点标识，旧内容可继续保留既有的 `A-0` 格式；新内容建议使用清晰且稳定的名称。

## 配置 Chapter 0

当前 `Assets/Story/Chapter0/StoryData_Chapter0.asset` 还没有 TutorialBlock；需要在 Unity Inspector 中按以下步骤添加。

### 1. 配置教程曲目表

1. 打开 `Assets/Resources/TutorialCollection.asset`。
2. 在 `songs` 字典中将现有 Chapter 0 教程条目的 Key 调整为 `chapter0_intro`。保留其对应的 `SongItemData`，不要重新手工复制曲目数据。
3. 检查该教程条目的 `difficultyDataList`：目标难度应为 `isAvailable = true`，并确认它的 `saveDifficultyId`。当前 Chapter 0 Tutorial 的 Easy 难度应使用 ID `0`；以 Inspector 实际显示为准。

### 2. 在 StoryData 新增起始教程节点

1. 打开 `Assets/Story/Chapter0/StoryData_Chapter0.asset`。
2. 在 `blocks` 新增一个条目，或按你的章节布局将其放在第一个剧情节点之前：

| 字段 | 建议值 |
|---|---|
| `blockId` | `tutorial_0_intro` |
| `blockType` | `Tutorial` |
| `tutorialName` | 当前阶段可先填临时显示名，例如 `Chapter 0 Tutorial` |
| `tutorialKey` | `chapter0_intro` |
| `tutorialProgressVariable` | `story_tutorial_chapter0_intro_resolved` |
| `tutorialDifficultySaveId` | `0`（以教程曲目的实际 `saveDifficultyId` 为准） |
| `nextBlockIds` | 第一个后续剧情节点，例如 `A-0` |
| `unlockCondition` | 留空，使教程节点在章节开始时可点击 |

3. 为原本的第一个剧情节点 `A-0` 设置 `UnlockCondition`：选择 `VariableCondition`，并填写：

| 字段 | 值 |
|---|---|
| `variableName` | `story_tutorial_chapter0_intro_resolved` |
| `comparison` | `Equal` |
| `value` | `1` |

如果该节点还有其它前置要求，请使用 `AllOfCondition` 将原条件与上述 `VariableCondition` 组合。不要把它改成 `BlockCompletedCondition(tutorial_0_intro)`，否则会失去与 Yarn 和其它剧情变量共用条件系统的优势。

### 3. 配置通用 SelectionBox

TutorialBlock 不再需要专属弹窗。只需配置一套可供其它系统复用的 SelectionBox：

1. 创建一个 `SelectionBoxButton` Prefab：根节点具有 `Button` 与 `SelectionBoxButton`，子节点具有 `TMP_Text`。将 Button 和文本分别赋给 `button`、`labelText`。
2. 创建一个 `SelectionBox` Prefab：根节点具有 `CanvasGroup` 与 `SelectionBox`；配置标题 `TMP_Text`、可选内容 `TMP_Text`、选项容器 `RectTransform`，并把上一步 Prefab 赋给 `optionButtonPrefab`。
3. 打开 `Assets/Scenes/MenuScene.unity` 中现有的 `MessagePage`。该节点已有 `CanvasGroup` 与 `MessageUIPage`，无需创建新的全屏覆盖页或在 `MenuManager` 新增引用。
4. 将上一步的 `SelectionBox` Prefab 赋给 `MessageUIPage.defaultSelectionBoxPrefab`。它会与现有 `MessageBox` 共用 `messageContainer`。

教程点击时会运行时生成一个 SelectionBox，并生成两个按钮：`游玩教程` 与 `跳过教程`。未来其它非 Yarn 的交互（例如奖励二选一、离开确认、章节分支）可以传入自己的标题、内容和 `SelectionBoxOption` 列表复用这套 UI。按钮正式本地化留待剧情文本与本地化阶段处理。

### 4. 推荐按钮排版（SelectionBox 宽度 1200）

建议所有 2～3 个选项统一使用纵向等宽排列，而不是根据数量切换横向布局。这样在英文、日文、韩文和越南文的按钮文字长度不同时，仍有稳定的触控面积和视觉节奏。

| 配置项 | 推荐值 |
|---|---|
| `optionContainer` | `VerticalLayoutGroup` |
| 左右 Padding | 72 |
| 上下 Padding | 48 |
| 按钮间距 | 24 |
| 按钮高度 | 112（通过 Button Prefab 的 `LayoutElement.preferredHeight`） |
| 按钮宽度 | 填满可用宽度，约 1056 |
| 对齐方式 | `Middle Center` |

两按钮时，选项区高度约为 248；三按钮时约为 384，均适合固定宽度 1200 的弹窗。若存在“取消 / 返回”一类非主要操作，应固定放在最后一项，并以较弱的颜色或描边区分，不要仅通过位置变化表达危险性。横向三等分在 1200 宽度下每项只有约 336 宽，对越南文和未来较长的本地化文本余量不足，因此不建议作为通用 SelectionBox 的默认布局。

## 验证清单

1. 使用新存档或 StoryTree 的 `DebugResetChapterProgress` 重置 Chapter 0；该调试重置现在也会清除本章节的教程变量。
2. 进入 Chapter 0，确认只有 TutorialBlock 可点击，`A-0` 保持 Locked。
3. 点击 TutorialBlock，再点击“跳过教程”：节点应变为 Completed，`A-0` 应立即成为 Current；重进游戏后状态应保留。
4. 重置后选择“游玩教程”：确认进入 Chapter 0 Tutorial 的指定难度，且 `A-0` 在确认按钮点击后已解锁。
5. 在教程暂停页或结算页返回菜单：应回到 Chapter 0 的 StoryPage，而不是 SongSelection 页面。
6. 通过普通选曲进入歌曲后返回菜单：应仍回到 SongSelection 页面，且歌曲/难度缓存不受影响。
7. 在 TutorialBlock 已完成后再次点击它：应再次显示 SelectionBox，选择“游玩教程”后能够重新进入教程，且后续剧情解锁状态不变化。

## 配置错误的表现

以下任一配置缺失时，TutorialBlock 会输出警告且不会解锁后续剧情：`tutorialKey`、`tutorialProgressVariable`、`tutorialDifficultySaveId`、TutorialCollection 中的曲目、可用的目标难度、场景中的 `MessageUIPage`、`defaultSelectionBoxPrefab` 或选项按钮 Prefab。

这是一项运行时保护；本阶段不增加导入器或 Editor 阶段的额外防呆校验。