# 04 · 战斗系统规范

> **所属文档集** [← 返回索引](./README.md)  
> **摘要**：伤害数据模型、命中/受击管线、弹反系统、状态效果与连击规范。  
> **关联**：[03_PlayerSystem](./03_PlayerSystem.md) · [07_EnemySystem](./07_EnemySystem.md)

---

## 目录

1. [战斗设计原则](#1-战斗设计原则)
2. [DamagePacket — 伤害数据模型](#2-damagepacket--伤害数据模型)
3. [命中/受击管线](#3-命中受击管线)
4. [弹反系统](#4-弹反系统)
5. [霸体与打断系统](#5-霸体与打断系统)
6. [状态效果系统](#6-状态效果系统)
7. [战斗配置参数](#7-战斗配置参数)

---

## 1. 战斗设计原则

| 原则 | 说明 |
|------|------|
| **数据驱动** | 伤害、击退、硬直全部封装在 DamagePacket 中传递，不通过直接引用 |
| **物理解耦** | 攻击方和受击方通过碰撞区域交互，不互相持有引用 |
| **事件广播** | 命中确认后广播事件，让灵力积累、反馈系统等独立响应 |
| **可弹反标记** | 每次攻击明确标记是否可被弹反，由 DamagePacket.flags 决定 |

---

## 2. DamagePacket — 伤害数据模型

DamagePacket 是一次攻击行为的完整数据描述，**只读值类型**，在管线中传递不可修改：

```
DataModel DamagePacket {
    rawDamage       : Integer              // 基础伤害（未经减免）
    finalDamage     : Integer              // 实际伤害（由受击方计算后填写）
    damageType      : DamageType           // 伤害类型
    flags           : Flags<DamageFlags>   // 属性标记
    ──────────────────────────────────────
    knockbackDir    : Vector2              // 击退方向（单位向量）
    knockbackForce  : Number               // 击退力度
    stunDuration    : Duration             // 受击硬直时长（秒）
    breakLevel      : BreakLevel           // 打断等级（影响霸体穿透）
    ──────────────────────────────────────
    sourceId        : ID                   // 攻击来源标识（用于特殊规则）
    sourcePosition  : Vector2              // 攻击来源位置
    sourceLayer     : AttackerType         // 来源类型（玩家/敌人/环境）
    hitFxType       : HitFxType            // 命中特效类型
}
```

### DamageType 枚举

| 值 | 说明 |
|----|------|
| `Normal` | 普通物理伤害 |
| `Fire` | 火焰伤害（可点燃）|
| `Poison` | 毒素伤害（可中毒）|
| `Void` | 虚空伤害（忽略所有减免，用于特定 Boss）|
| `True` | 真实伤害（固定量，忽略防御）|
| `Environmental` | 环境伤害（棘刺/熔岩）|

### DamageFlags 标记

| 标记 | 说明 |
|------|------|
| `CanBeParried` | 可被弹反（移动弹射物/近身攻击）|
| `Unblockable` | 不可被格挡或弹反（特殊攻击）|
| `IgnoreIFrame` | 忽略受击无敌帧（毒素持续伤害）|
| `PerfectParryOnly` | 只能被完美弹反（高难度攻击）|
| `AoE` | 范围伤害（爆炸/冲击波）|
| `DotTick` | 持续伤害跳数（由状态效果发出）|

---

## 3. 命中/受击管线

### 3.1 管线流程

```
攻击方激活 HitArea（攻击判定区域）
  │
  ├─ 与 HurtArea（受击判定区域）发生碰撞检测
  │    └─ 确认碰撞：攻击方的 AttackerLayer 与受击方的 HurtableLayer 匹配
  │
  ├─ 受击方 HurtArea 接收 DamagePacket
  │    └─ 检查：是否处于无敌帧？
  │         ├─ 是（且非 IgnoreIFrame）→ 丢弃，不处理
  │         └─ 否 → 继续
  │
  ├─ 受击方计算 finalDamage
  │    └─ rawDamage × 攻击倍率 × 防御减免
  │
  ├─ 受击方本地响应
  │    ├─ 扣减 HP
  │    ├─ 应用击退
  │    ├─ 进入硬直状态
  │    └─ 启动无敌帧计时
  │
  └─ 广播 OnHitConfirmed 事件（全局）
       ├─ 玩家系统：攻击命中敌人 → 增加灵力
       ├─ 反馈系统：播放命中特效、震屏、音效
       └─ 进程系统：记录伤害统计
```

### 3.2 攻击判定区域（HitArea）规范

| 属性 | 说明 |
|------|------|
| 形状 | 矩形（主要）或圆形（AoE 攻击）|
| 激活时机 | 由动画事件驱动（某一帧开启，某一帧关闭）|
| 打击次数 | 默认一次攻击只打击一个目标一次 |
| 层级过滤 | 只与己方对立层级的 HurtArea 发生碰撞 |

### 3.3 受击判定区域（HurtArea）规范

| 属性 | 说明 |
|------|------|
| 形状 | 矩形（贴近实体碰撞箱）|
| 常态 | 始终激活（死亡后关闭）|
| 无敌帧 | 无敌期间 HurtArea 不响应伤害（仍检测碰撞）|

---

## 4. 弹反系统

### 4.1 设计目标

弹反是游戏的**核心差异化机制**：
- 高风险（窗口极短）→ 高回报（大量灵力 + 反击机会）
- 成功弹反会产生"子弹时间"效果，强调成功感
- 所有标记 `CanBeParried` 的攻击都可以弹反

### 4.2 弹反流程

```
玩家按弹反键 → 进入 ParryState

ParryState 开始:
  ├─ 弹反激活期（parryActiveWindow）开始
  │    └─ 激活期内接收到带 CanBeParried 标记的 DamagePacket
  │         → 弹反成功
  │              ├─ 丢弃该 DamagePacket（伤害不生效）
  │              ├─ 触发子弹时间（游戏速度降至 slowMotionScale，持续 hitStopDuration）
  │              ├─ 播放弹反成功动画/特效/音效
  │              ├─ 发出 OnParrySuccess 事件
  │              ├─ 为玩家增加 +33 灵力
  │              └─ 开启反击窗口（counterWindow）
  │
  ~~parryActiveWindow 超时~~ → 弹反失败，回到正常状态

反击窗口内:
  ──攻击输入──► ParryCounter 攻击（×3 伤害，不可弹反）
  ~~反击窗口超时~~ → IdleState/RunState
```

### 4.3 弹反参数

| 参数 | 推荐值 | 说明 |
|------|--------|------|
| `parryActiveWindow` | 0.15s | 弹反激活期（可弹反的时间窗口）|
| `parryStartupDelay` | 0.05s | 按键到激活期的前摇 |
| `hitStopDuration` | 0.1s | 子弹时间持续 |
| `slowMotionScale` | 0.15 | 子弹时间游戏速度倍率（0=完全静止）|
| `counterWindowDuration` | 0.6s | 弹反成功后的反击窗口 |
| `parryCounterMultiplier` | 3.0 | 弹反反击伤害倍率 |
| `soulPowerOnParry` | 33 | 弹反成功获得灵力 |

> **设计决策**：弹反前摇 0.05s  
> **原因**：消除"垃圾反弹"（无脑按弹反躲伤害），要求玩家预判攻击时机

### 4.4 弹反优先级规则

| 情况 | 处理 |
|------|------|
| 多个攻击同时到达 | 优先弹反第一个判定的攻击，其余正常受击 |
| 弹反期间受到 `Unblockable` 攻击 | 正常受伤，弹反状态中断 |
| 弹反期间受到 `PerfectParryOnly` | 需在激活期的前 1/3 时间内（完美窗口）|

---

## 5. 霸体与打断系统

### 5.1 概念

**霸体（Poise）**：实体在受到攻击时抵抗动作打断的能力。  
**打断等级（BreakLevel）**：一次攻击能打断多高等级霸体的能力。

### 5.2 等级体系

| 打断等级 | 含义 | 典型来源 |
|---------|------|---------|
| `0 - None` | 无打断力 | 环境持续伤害 |
| `1 - Light` | 打断低级霸体 | 玩家普通攻击 |
| `2 - Medium` | 打断中级霸体 | 玩家重击（Attack3）|
| `3 - Heavy` | 打断高级霸体 | 弹反反击、魂技能 |
| `4 - Force` | 无条件打断（无视霸体）| 特定 Boss 技能 |

### 5.3 霸体等级

| 霸体等级 | 含义 | 适用实体 |
|---------|------|---------|
| `0 - Fragile` | 任意攻击均可打断 | 普通小怪 |
| `1 - Standard` | 普通攻击可打断 | 常规敌人 |
| `2 - Armored` | 需重击才能打断 | 精英怪 |
| `3 - Boss` | 仅弹反反击/强力技能可打断 | Boss |

### 5.4 判定规则

```
attackBreakLevel >= targetPoiseLevel → 动作打断（进入受击状态）
attackBreakLevel < targetPoiseLevel  → 伤害照常，但不打断动作
ForceBreak 标记 → 无条件打断，忽略霸体等级
```

---

## 6. 状态效果系统

### 6.1 状态效果模型

```
DataModel StatusEffect {
    effectId       : ID
    effectType     : StatusEffectType
    duration       : Duration           // 持续时间（0 = 永久直到治疗）
    tickInterval   : Duration           // DoT 跳数间隔（仅伤害类）
    damagePerTick  : Integer            // 每跳伤害（仅伤害类）
    stackBehavior  : StackBehavior      // 叠加规则
    sourceId       : ID                 // 施加方标识
}
```

### 6.2 效果类型

| 类型 | 效果 | 可叠加 | 治疗方式 |
|------|------|--------|---------|
| `Poison` | 每 0.5s 扣 1 HP，持续 6s | 延长时间（不叠加层数）| 解毒药 / 离开毒素区 |
| `Burn` | 每 0.3s 扣 2 HP，持续 3s | 刷新时间 | 水体 / 时间 |
| `Stun` | 完全硬直，无法行动 | 刷新时间 | 时间 |
| `Slow` | 移动速度 ×0.5 | 不叠加（取最强）| 时间 |
| `Frozen` | 完全冻结，无敌但也无法行动 | 不叠加 | 火焰攻击 |

### 6.3 叠加规则（StackBehavior）

| 规则 | 说明 |
|------|------|
| `RefreshDuration` | 已有效果时重置持续时间 |
| `ExtendDuration` | 已有效果时延长持续时间 |
| `AddStack` | 叠加层数，每层独立计时 |
| `IgnoreIfActive` | 已激活时忽略新施加 |

---

## 7. 战斗配置参数

| 参数 | 推荐值 | 说明 |
|------|--------|------|
| `baseAttackDamage` | 10 | 玩家基础攻击伤害 |
| `attack1Multiplier` | 1.0 | 第一击倍率 |
| `attack2Multiplier` | 1.0 | 第二击倍率 |
| `attack3Multiplier` | 2.0 | 第三击（重击）倍率 |
| `parryCounterMultiplier` | 3.0 | 弹反反击倍率 |
| `knockbackForceNormal` | 5.0 | 普通击退力度 |
| `knockbackForceHeavy` | 10.0 | 重击击退力度 |
| `defaultStunDuration` | 0.3s | 默认受击硬直时长 |
| `soulPowerPerHit` | 10 | 命中普通敌人获得灵力 |
| `soulPowerPerBossHit` | 5 | 命中 Boss 获得灵力 |