tianshu-engine/docs/guide/BATTLE_SYSTEM.md

战斗系统

概述

P31 新增。分为两个独立功能：战斗 HUD（战斗中显示）和战斗结算（胜利后弹出）。

---

BattleHUD — 战斗中显示的角色属性

配置在 SceneNode.battleHUD。

{
  "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。视频播放完后自动弹出。

{
  "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 数量随意增减，面板自动适配

---

完整模板

{
  "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"
}