docs: reorganize docs into guide/ and electron/, add 6 new guide docs, update README

2026-06-10 17:01:48 +08:00
parent 99f80147c7
commit 686b1b45ea
11 changed files with 950 additions and 75 deletions
--- a/docs/guide/BRANCHING.md
+++ b/docs/guide/BRANCHING.md
@@ -0,0 +1,138 @@
+# 分支叙事指南
+
+## 基本分支
+
+最简单的分支：一个场景 → 多个选项 → 不同目标场景。
+
+```json
+"scene_1": {
+  "id": "scene_1",
+  "videoUrl": "scene_1/video.mp4",
+  "choices": [
+    { "text": "帮助他", "targetScene": "help" },
+    { "text": "离开",   "targetScene": "leave" }
+  ]
+}
+```
+
+## 条件分支
+
+选项可以根据变量条件显示/隐藏：
+
+```json
+"choices": [
+  {
+    "text": "高信任路线",
+    "targetScene": "trust_path",
+    "conditions": [
+      { "variable": "trust", "op": ">=", "value": 80 }
+    ]
+  },
+  { "text": "普通路线", "targetScene": "normal_path" }
+]
+```
+
+`op` 支持：`>`, `<`, `>=`, `<=`, `==`, `!=`。
+
+## 变量与效果
+
+全局变量在 JSON 顶层定义初始值：
+
+```json
+{
+  "variables": { "trust": 50, "courage": 0, "investigation": 0 }
+}
+```
+
+选项选择后应用效果：
+
+```json
+{
+  "text": "与陌生人握手",
+  "targetScene": "trust_ending",
+  "effects": [
+    { "type": "add", "target": "trust", "value": 30 }
+  ]
+}
+```
+
+效果类型：
+- `"set"` — 设置变量为指定值
+- `"add"` — 增加（负数=减少）
+
+## 场景进入效果
+
+进入场景时自动触发：
+
+```json
+"ending": {
+  "id": "ending",
+  "videoUrl": "ending/video.mp4",
+  "onEnter": [
+    { "type": "set", "target": "completed_game", "value": 1 }
+  ]
+}
+```
+
+## 限时选择
+
+```json
+{
+  "text": "快速决定！",
+  "targetScene": "timeout_scene",
+  "timeLimit": 10
+}
+```
+
+10 秒内不选，自动选这个选项。`timeLimit: 0` 或省略 = 不限时。
+
+## 默认跳转
+
+无选项或有选项但都不满足条件时，自动跳转：
+
+```json
+"scene": {
+  "id": "scene",
+  "videoUrl": "scene/video.mp4",
+  "choices": [],         // 无选项时自动跳
+  "nextScene": "auto_next"
+}
+```
+
+优先级：choices > nextScene > 什么都没配（游戏结束）。
+
+## 关键选择提示（Prompt）
+
+重要选项可以配置前置金色标识 + 选后浮现提示：
+
+```json
+{
+  "text": "与陌生人握手",
+  "textKey": "left_door.choice.handshake",
+  "prompt": "陌生人会记住你的善意",
+  "promptKey": "left_door.prompt.handshake",
+  "targetScene": "trust_ending"
+}
+```
+
+- 前置：选项按钮左侧显示金色竖线 + 淡金边框
+- 后置：选择确认后，画面中央浮现 prompt 文字，2 秒淡出
+
+`promptKey` 支持 i18n，配置方法见 [国际化指南](I18N.md)。
+
+## 多国语言选项
+
+选项文案支持中/英/日等多语言，使用 `textKey` 机制：
+
+```json
+{
+  "text": "继续前进",
+  "textKey": "qte_success.choice.continue",
+  "targetScene": "continue_ending"
+}
+```
+
+- `text` 是回退值（翻译找不到时使用）
+- `textKey` 指向 `public/locales/zh.json` 中的翻译
+
+详细配置见 [国际化指南](I18N.md)。