AdLike2048/assets/script/battle/docs/需求说明.md

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

本文档为战斗模块的需求与架构约束，与 接入指南.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 §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=战斗技能；去掉词条模型