# 交互指南 — 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 不受循环影响（独立音频轨道）

**视频制作技巧：** 正文段和循环段合成为一个文件。循环段首尾画面应自然衔接。