# 方案：战斗技能逻辑层（普攻 + 英雄技能 + 武器技能）

> 状态：已落地（2026-08-29）  
> 日期：2026-08-29  
> 关联：[需求-新项目概述.md](./需求-新项目概述.md)、[`assets/script/battle/docs/需求说明.md`](../assets/script/battle/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表已删；代码遗留路径须空操作，禁止把新 Skill 当词条 |

代码里历史变量名 `weapon1Id` 仍表示 **Hero.id**，新增代码优先用 `heroId`。

## 2. 三槽模型

```
Hero（合成等级 level）
  ├─ atk_id[level-1]     → 普攻 Skill
  ├─ act_skill[level-1]  → 英雄主动 Skill（可空）
  └─ 装备武器 weaponId
        └─ Weapon.act_skill → 武器技能（0=无；type 分流主动/被动）
```

装备解析：`gg.equip.getHeroDisplayWeaponId(heroId)`（穿戴 >0 用穿戴，否则 `Hero.startweapon`）。

## 3. Ability id

| 种类 | id 格式 |
|------|---------|
| 普攻 | `ability_norm_{skillId}` |
| 英雄主动 | `ability_hero_{skillId}_e{entityId}` |
| 武器主动 | `ability_weapon_{skillId}_e{entityId}` |
| 怪物技能 | `ability_monster_{skillId}_e{entityId}` |

## 4. 主动技施法队列

- 普攻：OnTick + 攻速；`interruptibleByCast`，施法锁期间冻结
- 英雄主动 + 武器主动（`Skill.type=1`）：`Skill.priority` **只排序**，同时就绪必须全部排队串行释放，禁止因 priority 高低丢掉
- 同 tick / 施法锁占用：只放队头一个；其余 timer 保持就绪，锁解开后立刻放下一个；同 priority 保持 abilityIds 原序
- 施法锁未释放时不叠放下一主动，也不放普攻

## 5. 被动（`Skill.type=2`）

读 `condition` / `result`，挂实体被动运行时；不进 OnTick 施法队列。

**不回触发**：`result` 字段产生的一切效果不再回判任何 condition。其伤害不进条件 1/4，其击杀不进条件 5；结算期间抬闸，连同该次伤害带出的额外伤/击杀一并排除。不靠伤害类型白名单。经验/掉落仍结算。condition 3/6 只听 `AbilityCast`（普攻/主动），被动 result 不走施法，不会叠次数。

**result 1（剑阵）**：同施法者同 `Skill.id` 只保留一团，再次触发刷新落点与剩余持续，不叠多团。例：诛仙剑 `1,100,0.3,3000,5`。

**击退落点**：须可走且能寻路到攻击点（距离场有限）。直线推出场外/断路格则沿射线回退；再不行沿进路退。禁止落到无法 `assignPath` 的格。

**result 7（爆炸火球）**：参数 `最大数量,伤害系数万分比,飞行速度像素/秒,飞行时间秒`。在触发点（击杀目标）按 `360/数量` 均分方向直线飞出，穿透且每敌只伤一次；飞满配表时间后逻辑结束、表现到终点回池。例：火尖枪 `7,8,4000,320,1`。

**result 9（直线火龙）**：参数 `飞行速度像素/秒,伤害系数万分比,持续秒`。从施法者沿触发目标方向匀速飞满持续时间，穿透且每敌只伤一次；不因命中消失。体盒按预制体 100×30 再加半格占地（与 atk_type 12 一致）。表现沿**同一逻辑方向**飞（Cocos Y 取反），不跟腰点重瞄。例：龙舌弓 `9,400,10000,4`。

**result 10（改普攻）**：触发后覆盖**该宿主**普攻 Skill 的 `atk_type` / `atk_para`，按实体重建 `ability_norm_{id}_e{entity}`。不改共享配表，避免同技能其他塔串台。例：`10,12,5,12,10000` → `atk_type=12`，`atk_para=5,12,10000`。

**result 11（直线剑气）**：参数 `数量,间隔秒,伤害系数万分比`。按间隔连发；优先各朝不同敌人（触发主目标优先，其余随机），敌数不足则循环复用同一批目标仍发满数量。穿透且每敌只伤一次；飞出地图边界结束。表现用 `battleHero/prefab/skill/玉帝刀光`，飞出可视区后回池。飞行速度代码常量（表无速度段）。动画：轩辕剑 `剑气蓝`，吴钩双剑 `剑气红`。例：轩辕剑 `11,3,0.3,15000`。

**result 12（闪电链）**：参数 `蔓延范围像素,蔓延数量,伤害系数万分比`。从触发目标起跳，向范围内**未打过**的最近敌蔓延（触发目标算第 1 跳，不重复）。每跳先出电弧/受击，间隔后再结算该落点伤害。表现用老项目 `电母-大招`（`普通雷电`）与 `电母-大招受击`（`普通受击`），传导间隔对齐资源时长/2。例：三尖两面刀 `12,200,5,120000`。

## 6. 逻辑 / 表现契约

| 逻辑 | 表现 |
|------|------|
| 索敌、命中、伤害、buff、CD | 动画 / 弹道 / 特效 |

打敌方时索敌一律按**威胁**：沿当前路离目标营地越近越优先（已抵墙最高）；剩余相同则离施法者更近者优先。友军/自身仍按原 selector。`monsterRandomPick`（怪技 atk_buff 6）仍洗牌。
| `PlayPresentation` 发出 cue | `SkillController` → `onAttack` / `onSkill` / `onWeaponSkill` |
| DealDamage 在 deferred 或逻辑几何结算 | **禁止**碰撞 AABB 作为唯一伤害源 |

### cue

| cue | 含义 | Skill 方法 |
|-----|------|------------|
| `attack` | 普攻 | `onAttack` |
| `skill` | 英雄技能 | `onSkill` |
| `weaponSkill` | 武器主动 | `onWeaponSkill` |
| `monsterSkill` | 怪物技能 | `MonsterSkillHost` 播 `Skill.animation`（见 [方案-怪物技能.md](./方案-怪物技能.md)） |

### PlayPresentation.params

| 字段 | 类型 | 说明 |
|------|------|------|
| `skillKind` | `'normal'\|'hero'\|'weapon'\|'monster'` | 槽位 |
| `skillId` | number | Skill.id |
| `heroId` | number | Hero.id |
| `weaponId` | number | 当前武器 id |
| `composeLevel` | number | 合成等级 |
| `animation` | string | 动画名 |
| `atkType` / `atkPara` | string | 形态与参数 |
| `fly` | string | 投射物 |
| `showeffect` | string | 预兆：`延迟秒,预制体名`（`battleHero/prefab/skill`）；空则无。有值时命中/buff/extra 等预兆起播后 0.33s 再施加 |
| `priority` / `cd` | number | 优先级 / CD |
| `extraSkill` | string | `Skill.skill` 额外效果 |
| `buff1` / `buff2` | string | 命中 buff |
| `targetEntityIds` | number[] | 逻辑锁定目标快照 |

表现只读上述字段；时刻对齐可调 `ctx.hit()` / `ctx.finish()`，不自行算伤害目标。

### atk_type 2 / 5 前向矩形

朝威胁最高的敌开口：长=射程（沿朝向），宽=`atk_para` 第 1 段像素（左右各一半）。占地盒与该条带相交即命中，不再外扩半格。

### atk_type 14 360° 多段

圈半径=`Skill.range`（≤0 则塔射程）。`atk_para`=`段数,间隔秒,伤害万分比`（例 `5,0.2,5000` = 5 段、间隔 0.2s、每段 50%）。开战锁圈内敌，每段 `hit()` 结算一段。有 `showeffect` 也只播预兆，**多段伤害出手即按 `PRES_HIT_AT_BASE` 起跳**，不等预兆。

### atk_type 10 连续多个单体

`atk_para`=`次数,间隔秒,伤害万分比`（例如如意金箍棒 20501 `8,0.2,25000` = 连砸 8 次、间隔 0.2s、每次 250%）。`Skill.range` 内按威胁锁最多 N 个单体；按间隔砸满 N 次，每次只打一个（不足则循环仍存活目标）。目标全死则提前结束伤害，已生成的砸击实例播完再收招。每次砸是独立结算与独立武器实例（克隆 `weaponType*`，播 `Skill.animation`，互不打断）。从原武器处朝向目标，按砸出帧 `击中光` 到目标的距离沿 X 拉伸。首次命中对齐砸出帧 0.8667s，其后按间隔 `hit()`。全部实例播完才收招。

### atk_type 15 目标圆形

`Skill.range` 内先锁主目标，再以主目标为圆心、`atk_para`=`半径(px),伤害万分比` 收圆内敌（可含射程外）。半径与黄圈同一套：配表像素/83=格，按格心距；并扫格子占地，避免漏塔。圆内仍排除组合字。表现层瞬时类；怪物 `skill=9` 时在主目标处挂 `干扰迷雾`（尺寸由资源控制，不等于逻辑半径）。

## 6b. 血量上限（配表）

`Skill.atk_buff` type 4、营召唤 `atk_buff` type 4、局外被动 functiontype=15：上限 `×(1+万分比/10000)`，**保持原当前血量/上限比**（例：100 上限 70 当前 +20% → 120 / 84）。允许时播 `血量上限` 并飘「血上限」+`上箭头`，**不播** `怪物加血`；**营召唤出生加成不播**。不是单纯加血（type 10 / skill extra 4）。

`atk_type=7` 的 `atk_para` 第 1 段是**最多目标数上限**（如悟净治疗术 `100,0`），`target_stage=2` 锁己方行军怪/友方召唤，每人只结算一次，不足不循环补位。

## 7. 修订记录

| 日期 | 说明 |
|------|------|
| 2026-08-29 | 初版：三槽、priority 队列、逻辑伤害、表现 cue |
| 2026-08-31 | 表现层见 [方案-战斗表现数据驱动.md](./方案-战斗表现数据驱动.md) |
| 2026-09-02 | 被动 result 10：按宿主覆盖普攻 atk_type / atk_para |
| 2026-09-03 | 配表血量上限保持原血量比，当前血量增加时播加血特效 |
| 2026-09-04 | 怪物技能框架：出怪绑定 + 播释放动画；效果逐个实现见方案-怪物技能 |
| 2026-09-04 | Skill.skill 类型 9：干扰迷雾，参数为显示秒；奔波儿灞 30105 |
| 2026-09-04 | Skill.atk_para 伤害万分比写 0 表示无直伤（悟能/悟净/玉帝） |
| 2026-09-05 | 打敌方索敌优先离目标营地最近（威胁最高） |
| 2026-09-07 | atk_type 2/5 前向矩形去掉半格 pad，宽高只按配表 |
| 2026-09-07 | atk_type=14：360° 圈内多段伤害 |
| 2026-09-07 | 营召唤出生 type4 血量上限不播加血特效 |
| 2026-09-08 | atk_type=15：主目标圆心范围；奔波儿灞迷雾改挂主目标（尺寸由资源控制） |
| 2026-09-08 | 被动 result 11：轩辕剑直线剑气（玉帝刀光，间隔连发，穿透出界回收） |
| 2026-09-08 | 被动 result 7：击杀点爆炸火球多向穿透（数量角分、速度/时间配表，到终点回收） |
| 2026-09-09 | 被动 result 9：直线火龙穿透体盒按半格放大；表现与逻辑同向，不跟腰点重瞄 |
| 2026-09-10 | 被动 result 12：三尖两面刀闪电链（从目标起跳，范围/数量/系数配表，电母大招表现） |
| 2026-09-11 | 血量上限提升飘「血上限」并显示 battleText `上箭头` |
| 2026-09-11 | 血上限播 `血量上限` 不播 `怪物加血`；阎王生死簿对敌直伤播 `怪_流血` |
| 2026-09-11 | 被动 result 伤害/击杀不回触发 condition 1/4/5 |
| 2026-09-12 | result 全程抬闸 + fromPassiveResult，不再用伤害类型白名单；其伤害/击杀不回判任何 condition |
| 2026-09-12 | result 伤害立即派发 DamageDealt，跳伤结束前 flush 残留事件，避免帧末出闸后回触发（诛仙剑阵） |
| 2026-09-12 | 剑阵同塔同技能不叠加，再次触发刷新落点与持续 |
| 2026-09-11 | 击退落点须在攻击点距离场内，避免推出后无法寻路 |
| 2026-09-11 | atk_type=15 圆半径按配表 83px/格 + 占地扫描；奔波儿灞迷雾起播即降攻速 |
| 2026-09-11 | atk_type=10：连续多个单体（次数,间隔秒,伤害万分比），如意金箍棒 20501 |
| 2026-09-11 | atk_type=10：每次砸独立武器实例，不在原武器上重播 |
| 2026-09-11 | target_stage=2：maxCount 仅为上限，每人一次，不循环补位（悟净治疗术/悟能疾行术） |