ichni_Official/docs/tutorial-block-system.md

TutorialBlock 教程流程与 Chapter 0 配置

规则

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

1. 将 TutorialBlock 的 tutorialProgressVariable 写为 true。
2. 保存全局剧情变量。
3. 将该 TutorialBlock 标记为 Completed，用于故事树的节点外观和防止重复点击。
4. 重新计算所有 StoryBlock 的 UnlockCondition。

后续 Block 必须通过 VariableCondition 读取教程变量解锁，不要依赖 TutorialBlock 的完成记录。选择“游玩教程”后会进入 GameScene；选择“跳过教程”则留在故事树。教程游玩中退出、失败或关闭游戏不会回退已经确认的解锁状态。

运行时职责

模块	职责
StoryProgress	统一执行“写变量、保存、刷新故事树”；ResolveTutorial 同时更新教程节点完成状态。
TutorialFlowController	验证 TutorialBlock 配置，并临时组装教程所需的两个 SelectionBoxOption。
SelectionBoxUIPage	通用多选弹窗页面：动态生成一个 SelectionBox，阻断底层输入并在选择后销毁该实例。
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 创建一个全屏覆盖页：根节点具有 CanvasGroup 和 SelectionBoxUIPage，初始建议 alpha = 0、interactable = false、blocksRaycasts = false。
4. 在该覆盖页下创建 selectionBoxContainer，并将它赋给 SelectionBoxUIPage.selectionBoxContainer；将上一步的 SelectionBox Prefab 赋给 selectionBoxPrefab。
5. 选中 MenuManager，把该 SelectionBoxUIPage 组件拖入新的 selectionBoxUIPage 字段。

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

验证清单

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 页面，且歌曲/难度缓存不受影响。

配置错误的表现

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

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