docs: add battle system, conditional routing, key moments, and creators guide docs

docs/guide/BATTLE_SYSTEM.md

@@ -0,0 +1,112 @@
+# 战斗系统
+
+## 概述
+
+P31 新增。分为两个独立功能：**战斗 HUD**（战斗中显示）和**战斗结算**（胜利后弹出）。
+
+---
+
+## BattleHUD — 战斗中显示的角色属性
+
+配置在 `SceneNode.battleHUD`。
+
+```json
+{
+  "battleHUD": [
+    {
+      "label": "主角",
+      "labelKey": "battle.hud.player",
+      "portrait": "images/player.jpg",
+      "stats": [
+        { "variable": "player_hp", "label": "HP", "labelKey": "stat.hp", "max": 100 },
+        { "variable": "player_mp", "label": "MP", "labelKey": "stat.mp", "max": 50 },
+        { "variable": "score", "label": "连击", "labelKey": "stat.combo" }
+      ]
+    }
+  ]
+}
+```
+
+| stat 字段 | 说明 |
+|-----------|------|
+| `variable` | 变量名，值随 effect 实时变化 |
+| `label` | 显示标签（回退值） |
+| `labelKey` | i18n key |
+| `max` | 最大值，有则为进度条，无则为纯数字 |
+| `style` | 强制 `"bar"` 或 `"number"`。没配时根据有无 `max` 自动 |
+
+进度条颜色根据百分比自动变化：100-50% 绿色 / 50-25% 橙色 / 25-0% 红色。
+
+---
+
+## BattleResult — 胜利结算面板
+
+配置在 `SceneNode.battleResult`。视频播放完后自动弹出。
+
+```json
+{
+  "battleResult": {
+    "title": "击退成功！",
+    "titleKey": "battle.result.victory",
+    "stats": [
+      { "label": "勇气", "labelKey": "stat.courage", "variable": "courage", "max": 100 },
+      { "label": "QTE 成功", "labelKey": "stat.qte_succeeded", "variable": "qte_succeeded" }
+    ]
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 结算标题（回退值） |
+| `titleKey` | 标题 i18n key |
+| `stats` | 统计项数组。`variable` / `label` / `labelKey` / `max` |
+
+### 关键规则
+
+- 战败场景**不配** `battleResult`——战败直接走视频叙事
+- 结算面板关闭后自动跳转到 `nextScene` 或第一项 `choice` 目标
+- stats 数量随意增减，面板自动适配
+
+---
+
+## 完整模板
+
+```json
+{
+  "id": "combat",
+  "videoUrl": "combat/video.mp4",
+  "battleHUD": [ ... ],
+  "qte": {
+    "successScene": "combat_router",
+    "failScene": "defeat",
+    "effects": {
+      "success": [{ "type": "add", "target": "enemy_hp", "value": -25 }],
+      "fail": [{ "type": "add", "target": "player_hp", "value": -20 }]
+    }
+  },
+  "nextScene": "combat_router"
+},
+{
+  "id": "combat_router",
+  "keyMoment": false,
+  "nextScene": [
+    { "conditions": [{ "variable": "enemy_hp", "op": "<=", "value": 0 }], "targetScene": "victory" },
+    { "conditions": [{ "variable": "player_hp", "op": "<=", "value": 0 }], "targetScene": "defeat" },
+    { "targetScene": "combat" }
+  ]
+},
+{
+  "id": "victory",
+  "videoUrl": "victory/video.mp4",
+  "battleResult": { "title": "胜利！", "stats": [ ... ] },
+  "nextScene": "next_chapter"
+},
+{
+  "id": "defeat",
+  "videoUrl": "defeat/video.mp4",
+  "keyMoment": true,
+  "onEnter": [{ "type": "set", "target": "player_dead", "value": 1 }],
+  "nextScene": "game_over"
+}
+```