设置扩展

docs/tutorial-block-system.md

@@ -6,10 +6,10 @@ TutorialBlock 点击后通过通用 `SelectionBox` 动态生成“游玩教程 /
 
 1. 将 TutorialBlock 的 `tutorialProgressVariable` 写为 `true`。
 2. 保存全局剧情变量。
-3. 将该 TutorialBlock 标记为 Completed，用于故事树的节点外观和防止重复点击。
+3. 将该 TutorialBlock 标记为 Completed，用于故事树的节点外观；Completed 状态仍允许玩家再次点击回顾教程。
 4. 重新计算所有 StoryBlock 的 `UnlockCondition`。
 
-后续 Block 必须通过 `VariableCondition` 读取教程变量解锁，不要依赖 TutorialBlock 的完成记录。选择“游玩教程”后会进入 GameScene；选择“跳过教程”则留在故事树。教程游玩中退出、失败或关闭游戏不会回退已经确认的解锁状态。
+后续 Block 必须通过 `VariableCondition` 读取教程变量解锁，不要依赖 TutorialBlock 的完成记录。选择“游玩教程”后会进入 GameScene；选择“跳过教程”则留在故事树。教程游玩中退出、失败或关闭游戏不会回退已经确认的解锁状态。教程节点完成后仍可再次点击；重复游玩只会重写相同的已处理状态，不会影响已解锁的后续剧情。
 
 ## 运行时职责
 
@@ -17,7 +17,7 @@ TutorialBlock 点击后通过通用 `SelectionBox` 动态生成“游玩教程 /
 |---|---|
 | `StoryProgress` | 统一执行“写变量、保存、刷新故事树”；`ResolveTutorial` 同时更新教程节点完成状态。 |
 | `TutorialFlowController` | 验证 TutorialBlock 配置，并临时组装教程所需的两个 `SelectionBoxOption`。 |
-| `SelectionBoxUIPage` | 通用多选弹窗页面：动态生成一个 `SelectionBox`，阻断底层输入并在选择后销毁该实例。 |
+| `MessageUIPage` | MessageBox 与 SelectionBox 共用的弹窗页面：使用同一遮罩、容器和 FIFO 队列，动态生成并依次显示弹窗。 |
 | `SelectionBox` / `SelectionBoxButton` | 动态生成任意数量的选项按钮并确保一次显示只执行一个回调。 |
 | `TutorialCollection` | 用 `tutorialKey` 查询教程曲目的 `SongItemData`。 |
 | `InformationTransistor` | 用 `MenuReturnDestination` 保存唯一的返回目标，替代旧的两个返回 bool。 |
@@ -78,12 +78,27 @@ TutorialBlock 不再需要专属弹窗。只需配置一套可供其它系统复
 
 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` 字段。
+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；该调试重置现在也会清除本章节的教程变量。
@@ -92,9 +107,10 @@ TutorialBlock 不再需要专属弹窗。只需配置一套可供其它系统复
 4. 重置后选择“游玩教程”：确认进入 Chapter 0 Tutorial 的指定难度，且 `A-0` 在确认按钮点击后已解锁。
 5. 在教程暂停页或结算页返回菜单：应回到 Chapter 0 的 StoryPage，而不是 SongSelection 页面。
 6. 通过普通选曲进入歌曲后返回菜单：应仍回到 SongSelection 页面，且歌曲/难度缓存不受影响。
+7. 在 TutorialBlock 已完成后再次点击它：应再次显示 SelectionBox，选择“游玩教程”后能够重新进入教程，且后续剧情解锁状态不变化。
 
 ## 配置错误的表现
 
-以下任一配置缺失时，TutorialBlock 会输出警告且不会解锁后续剧情：`tutorialKey`、`tutorialProgressVariable`、`tutorialDifficultySaveId`、TutorialCollection 中的曲目、可用的目标难度、`SelectionBoxUIPage` 引用、SelectionBox Prefab 或选项按钮 Prefab。
+以下任一配置缺失时，TutorialBlock 会输出警告且不会解锁后续剧情：`tutorialKey`、`tutorialProgressVariable`、`tutorialDifficultySaveId`、TutorialCollection 中的曲目、可用的目标难度、场景中的 `MessageUIPage`、`defaultSelectionBoxPrefab` 或选项按钮 Prefab。
 
 这是一项运行时保护；本阶段不增加导入器或 Editor 阶段的额外防呆校验。