# 战斗系统需求说明（逻辑层 / 表现层）

> 本文档为战斗模块的**需求与架构约束**，与 `接入指南.md` 互补。  
> 完整技能方案见 [`docs/方案-战斗技能逻辑层.md`](../../../docs/方案-战斗技能逻辑层.md)。  
表现数据驱动见 [`docs/方案-战斗表现数据驱动.md`](../../../docs/方案-战斗表现数据驱动.md)。

---

## 1. 术语（必读）

| 对外说法 | 配表 / 代码名 | 含义 |
|----------|---------------|------|
| **技能** | `Skill` 表 / `ITableSkill` | 战斗技能配置：普攻形态、主动、被动、额外效果。 |
| **普攻** | `Hero.atk_id[level-1]` → `Skill.id` | 每塔 1 个，随合成等级取数组索引。 |
| **英雄技能** | `Hero.act_skill[level-1]` → `Skill.id` | 可无；按合成等级取索引。 |
| **武器技能** | `Weapon.act_skill` → `Skill.id` | 局外装备确定；`type=1` 主动 / `type=2` 被动。 |
| **词条** | — | 旧三选1表已删；遗留代码须空操作。 |

代码中历史名 `weapon1Id` 表示 **Hero.id**；新增优先用 `heroId`。

---

## 2. PVP：当前不实现，架构必须预留

**现状**：仅 solo 完整跑通；PVP **不做联机与匹配**，但**禁止**为赶进度写死「只有一个玩家」的逻辑。

### 2.1 必须遵守

| 规则 | 做法 |
|------|------|
| 玩家上下文 | 业务入口用 `Player` / `match.players` / `match.getPlayer(id)`，**不要**在战斗逻辑里散落 `gg.game.localPlayer`（UI 层可缓存 `_player`）。 |
| 部署与同步 | `DeploySync` / `SkillController` 均带 **`playerId`**，远端玩家无 `bagSession` 时走 map 扫描 fallback。 |
| 事件监听 | 每玩家一个 `SkillController`；表现 cue 用 `_ownsEntity` 过滤。 |
| 模式参数 | `BattleStartParams.mode: 'solo' \| 'pvp'`、`localPlayerId` 已存在；新功能不得假设 `players.length === 1`。 |

### 2.2 刻意不做（后续 PVP 迭代）

- 词条选择的网络同步（词条玩法已移除）
- 远端 `bagSession` / 背包 UI

### 2.3 验收标准（架构预留）

- [ ] 新增战斗逻辑函数签名包含 `playerId` 或 `Player` 参数
- [ ] 无全局可变「本局唯一塔列表」；按玩家槽位查询 `deployedUnits`

---

## 3. 塔战斗能力（优先级 P0）

### 3.1 三槽模型

```
Hero
  ├─ atk_id[level-1]     → Skill（普攻）
  ├─ act_skill[level-1]  → Skill（英雄主动；可空）
  └─ 装备武器
        └─ Weapon.act_skill → Skill（武器技能；0=无）
```

- 允许同一塔同时挂 **普攻 + 英雄主动 + 武器主动**（有配置才挂）。
- 主动技（英雄+武器）按 `Skill.priority` **降序** 入队，**串行**释放。
- 被动（`Skill.type=2`）走 condition/result，不进施法队列。

### 3.2 部署时初始化

1. 解析武器：`getHeroDisplayWeaponId(heroId)`。
2. 从 `Hero` + `level` + 武器计算 `CombatComp`。
3. 绑定普攻 / 英雄主动 / 武器主动 Ability；注册被动。
4. 词条物化：空操作（表已删）。

### 3.3 实现模块

| 模块 | 职责 |
|------|------|
| `SkillAbilityBuilder` | `Skill` → MX `AbilityDef` |
| `TowerCombatSetup` | 部署后写 Combat + Ability |
| `TowerLoadoutService` | 实体 loadout、刷新 Ability 绑定 |
| `PassiveSkillRuntime` | type=2 被动 |
| `SkillPickApplier` | 遗留空操作 |

---

## 4. 表现层需求

### 4.1 逻辑 → 表现

- MX 发出 `PresentationCue`（timeline 内 `PlayPresentation`）。
- `SkillController` 按 cue 调用 `onAttack` / `onSkill` / `onWeaponSkill`。
- **cue**：普攻 `attack`，英雄主动 `skill`，武器主动 `weaponSkill`。
- 默认经 `SkillPresenterRouter`：按 `skillId` 覆盖或 `Skill.atk_type` 通用播控（三槽同一管线）。
- 伤害归逻辑层；表现不通过碰撞 AABB 作为唯一命中源。

### 4.2 表现 params

见 [`docs/方案-战斗技能逻辑层.md`](../../../docs/方案-战斗技能逻辑层.md) §6。

---

## 5. 配表依赖

| 表 | 用途 |
|----|------|
| `Hero` | 塔数值、`atk_id`、`act_skill`、`startweapon` |
| `Weapon` | 局外装备、`atk` 加成、`act_skill` |
| `Skill` | 战斗技能（普攻/主动/被动） |
| `Text` | 背包字块合成 |
| `Level` / `Monster` | 关卡与出怪 |

---

## 6. 修订记录

| 日期 | 说明 |
|------|------|
| 2026-07-08 | 初版：PVP 架构预留、一塔一普攻一主动 |
| 2026-08-29 | 改为三槽（普攻+英雄技能+武器技能）；Skill=战斗技能；去掉词条模型 |