chore: initial commit

2026-05-08 11:04:00 +08:00
commit f55d2a57c3
6278 changed files with 866081 additions and 0 deletions
--- a/Docs/DesignSpec/04_CombatSystem.md
+++ b/Docs/DesignSpec/04_CombatSystem.md
@@ -0,0 +1,271 @@
+# 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 获得灵力 |