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/INTERACTIONS.md
+++ b/docs/guide/INTERACTIONS.md
@@ -0,0 +1,123 @@
+# 交互指南 — QTE / Hotspot / Loop
+
+## QTE 快速反应事件
+
+在视频播放到特定时间点时弹出按键提示，玩家在倒计时内按下指定按键。
+
+```json
+"qte": {
+  "triggerTime": 1.0,
+  "prompt": "躲避飞来的石块！",
+  "promptKey": "right_door.qte.dodge",
+  "keys": ["ArrowLeft", "ArrowRight", "a", "d"],
+  "timeLimit": 3.0,
+  "successScene": "qte_success",
+  "failScene": "qte_fail",
+  "effects": {
+    "success": [{ "type": "add", "target": "courage", "value": 15 }],
+    "fail": [{ "type": "add", "target": "trust", "value": -20 }]
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `triggerTime` | 触发时间（秒） |
+| `prompt` / `promptKey` | 提示文字 / i18n key |
+| `keys` | 有效按键（键盘 key 名，不区分大小写） |
+| `timeLimit` | 倒计时（秒） |
+| `successScene` / `failScene` | 成功/失败目标场景 |
+| `effects` | 成功/失败分别触发效果 |
+
+**注意：** QTE 是模态交互。视频播放到 QTE 触发时暂停场景流程，QTE 期间视频结束事件被忽略。
+
+**可访问性：** 玩家可在设置中开启"QTE 按键简化"（所有 QTE 统一为空格键）和"QTE 时限放宽 ×1.5"。
+
+**禁止跳过：** QTE 场景建议设 `"skippable": false`，防止玩家跳过 QTE。
+
+## 图片/视频热点（Hotspot）
+
+在画面中划定可点击区域，玩家点击后触发分支。
+
+### 图片热点
+
+```json
+"investigation_site": {
+  "type": "image",
+  "imageUrl": "investigation_site/scene.jpg",
+  "contentSize": { "w": 1280, "h": 720 },
+  "hotspots": [
+    {
+      "id": "hs_desk",
+      "label": "查看书桌",
+      "labelKey": "investigation_site.hotspot.desk",
+      "targetScene": "desk_detail",
+      "x": 154, "y": 144, "width": 230, "height": 101
+    }
+  ]
+}
+```
+
+### 视频热点（按时间显隐）
+
+```json
+"corridor": {
+  "videoUrl": "corridor/video.mp4",
+  "contentSize": { "w": 1280, "h": 720 },
+  "hotspots": [
+    {
+      "id": "hs_left",
+      "label": "走向左边通道",
+      "targetScene": "left_door",
+      "x": 26, "y": 216, "width": 384, "height": 324,
+      "showAt": 1.5
+    },
+    {
+      "id": "hs_right",
+      "label": "走向右边通道",
+      "targetScene": "alone_ending",
+      "x": 870, "y": 216, "width": 384, "height": 324,
+      "showAt": 5.0
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `showAt` | 视频播放到此秒数后才显示热点（可选） |
+| `hideAt` | 视频播放到此秒数后隐藏热点（可选） |
+| `conditions` | 条件满足时才显示（可选） |
+
+### 坐标系统
+
+Hotspot 坐标使用**绝对像素**，基于 `contentSize` 指定的基准分辨率：
+
+- `x, y` — 左上角像素坐标
+- `width, height` — 热点区域像素尺寸
+
+引擎自动处理 `object-fit: contain` 的黑边偏移和屏幕缩放。
+
+**制作建议：** 在 Photoshop 中测量坐标，直接写入 JSON。
+
+## 循环等待（Loop）
+
+视频播放到指定区间后自动循环，适合"等待玩家做决定"的桥段。
+
+```json
+"stay": {
+  "videoUrl": "stay/loop.mp4",
+  "loopStart": 3.0,
+  "loopEnd": 6.0,
+  "choices": [
+    { "text": "站起来离开", "targetScene": "alone_ending" }
+  ]
+}
+```
+
+- 视频 0-3s 正常播放（正文段）
+- 到 3s 时循环开始，选项面板同时弹出
+- 视频在 3.0-6.0s 之间反复播放，直到玩家做出选择
+- BGM 不受循环影响（独立音频轨道）
+
+**视频制作技巧：** 正文段和循环段合成为一个文件。循环段首尾画面应自然衔接。