# 分支叙事指南

## 基本分支

最简单的分支：一个场景 → 多个选项 → 不同目标场景。

```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)。