# 武器系统扩展设计方案 (Weapon System Expansion Design)

> **⚠️ 实现现状 (2026-07-20 审计)**：本文档为**扩展蓝图，大部分未实现**。§1 轨迹修正器（正弦 / 回旋镖 / 环绕，含 `is_orbiting`/`wave_frequency` 等字段）**完全未落地**；文中引用的 `ProjectileDef` 字段属**死类**（代码 `spawn_bullet` 走扁平参数 + cold_data，从不实例化 ProjectileDef）。已实现的触发器/子母弹见 `spell_evaluator.gd`。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。

本文档旨在描述基于现有的 **HMWS (Hackable Modular Weapon System)** 和 **ECS BulletManager** 架构，可以进一步扩展的玩法机制。

当前的系统已经支持了基础的投射物、霰弹、激光，以及修正器（多重施法、弹射、追踪、穿透、连锁、冰冻）。在此基础上，我们可以引入更高级的策略组合和“涌现式”玩法。

## 1. 轨迹修正 (Trajectory Modifiers)

通过修改子弹在 `_physics_process` 中的运动逻辑，创造独特的弹道体验。

### 1.1 正弦/波浪弹道 (Sine/Wave Pattern)
*   **机制**: 子弹不再直线飞行，而是沿着正弦波轨迹运动。
*   **实现**:
    *   新增 `ModifierSine`.
    *   在 `BulletManager` 的 Data Stride 中增加 `waveFrequency` 和 `waveAmplitude` (或复用 `customData`)。
    *   在 `_physics_process` 积分位置时，叠加垂直于速度方向的偏移量。
*   **玩法**: 直线命中率低，但能绕过正面护盾，或者覆盖更宽的横向区域。

### 1.2 回旋镖 (Boomerang)
*   **机制**: 子弹飞出一定距离后，反向加速飞回玩家。
*   **实现**:
    *   新增 `ModifierBoomerang`.
    *   在 `BulletManager` 中逻辑：当 `lifetime` 经过一半时，给予一个反向的加速度 `Acceleration` 指向玩家。
*   **玩法**: 高风险高回报，利用回程的子弹对追击的敌人造成“背刺”双倍伤害。

### 1.3 轨道环绕 (Orbiting/Shield)
*   **机制**: 子弹不飞远，而是围绕玩家旋转，形成护盾。
*   **实现**:
    *   轨道参数 `is_orbiting: bool`、`orbit_radius: float`、`orbit_angle: float`、`orbit_speed: float` 均存入 `_bullet_contexts: Dictionary`（**冷数据字段，P6-N9 权威定义**），BulletManager SoA 热数组不新增字段。
    *   **双写优化（P6-N15 规范）**：环绕子弹的位置由圆周公式 100% 决定，不依赖速度积分。因此在 `BulletManager._physics_process` 中，**必须先判断 is_orbiting，再决定是否执行常规物理积分**：
        ```gdscript
        # BulletManager._physics_process 热路径（伪代码）
        for i in _active_count:
            var ctx = _bullet_contexts.get(i, null)
            if ctx and ctx.get(“is_orbiting”, false):
                # 跳过速度积分，直接覆写位置（避免无意义的双写开销）
                var angle: float = ctx.orbit_angle + ctx.orbit_speed * delta
                ctx.orbit_angle = fmod(angle, TAU)
                var px := _player_x + cos(ctx.orbit_angle) * ctx.orbit_radius
                var py := _player_y + sin(ctx.orbit_angle) * ctx.orbit_radius
                _data[i * BULLET_STRIDE + 0] = px
                _data[i * BULLET_STRIDE + 1] = py
                # vx/vy 保持 0，lifetime 正常递减
            else:
                # 常规物理积分（速度 + 加速度）
                _data[i * BULLET_STRIDE + 0] += _data[i * BULLET_STRIDE + 2] * delta
                _data[i * BULLET_STRIDE + 1] += _data[i * BULLET_STRIDE + 3] * delta
        ```
    *   **性能评估**：环绕子弹数量通常不超过 20 颗（护盾构建），`is_orbiting` 冷数据查询 20 次/帧可接受；若未来出现大量环绕子弹需求，再评估是否升居热数组（SoA 增加 1 bit flag）。
*   **玩法**: 仅近战流派，配合”击退”修正器保命。

## 2. 触发器系统 (Trigger System) - "Noita" 风格的核心

这是 roguelike 构建深度玩法的关键，即“子弹生子弹”。

### 2.1 击中施法 (Cast On Hit)
*   **机制**: 当母弹击中敌人时，以击中点为原点，释放另一个法术。
*   **案例**: "毒箭" + "击中施法" + "爆炸" = 毒箭射中敌人后产生爆炸。
*   **架构实现**（✅ 已完成）：
    `ProjectileDef.on_hit_payload_id`（`int`，-1=无触发）存储 `SubPayloadRegistry` 中预注册的子法术 ID。
    `SpellEvaluator` 预编译时将 TRIGGER 节点后续法术打包为 SubPayload 并注册到表；
    `BulletManager` 在 `_on_bullet_hit()` 回调中查表、通过 `SpellEvaluator.execute_sub()` 执行。
    弹体本身仅携带整数 ID，无需存储复杂对象引用，完全兼容 SoA PackedFloat32Array 布局。
    详见 `architecture_design.md §3.2.A`（ProjectileDef 完整字段）与 `implementation_plan.md §2.2`（SubPayloadRegistry）。

### 2.2 死亡/超时施法 (Cast On Death/Timer)
*   **机制**:
    *   **On Timer**: 子弹飞行亦段时间后，变成另一种子弹（或释放子弹）。例如：集束手雷（飞行 -> 分裂成小炸弹）。
    *   **On Death**: 子弹消失/撞墙时触发。
*   **玩法**: 延迟伤害、陷阱布局。

## 3. 元素交互 (Elemental Synergy)

扩展现有的 `Ice` (冰冻) 机制，引入状态反应。

### 3.1 状态定义
*   **冰 (Wet/Freeze)**: 减速。
*   **火 (Burn)**: 持续扣血 (DoT)。
*   **毒 (Poison)**: 持续扣血 + 易伤 (受到的伤害增加)。
*   **雷 (Shock)**: 间歇性打断动作。

### 3.2 组合反应 (Combo)
*   **热休克 (Fire + Ice)**: 解除冰冻，但在解除瞬间造成一次巨额爆发伤害 (Steam Burst)。
*   **导电 (Water/Ice + Lightning)**: 如果敌人处于冰冻/潮湿状态，被雷电击中时，触发大范围 AoE 连锁伤害。
*   **毒爆 (Poison + Fire)**: 毒气被点燃，移除中毒状态，产生一次性范围爆炸。

## 4. 或者是召唤物 (Summons)

将 `ActionNode` 的产物从子弹变为独立的实体单位。

### 4.1 炮台 (Turret)
*   **机制**: 在玩家位置放置一个静止单位，它拥有独立的射击逻辑（自动瞄准最近敌人）。
*   **实现**: 需要新增 `TurretManager` 或在 `EnemyManager` 扩展一个 "Friendly" 阵营。
*   **玩法**: 塔防流，玩家只负责跑位和放置。

### 4.2 浮游炮 (Funnel/Bit)
*   **机制**: 跟随玩家移动的无敌单位，复制玩家的射击行为（类似《沙罗曼蛇》的 Option）。

## 5. 开发路线图建议

1.  **Phase 1 (Easy)**: 实现 **ModifierSize** (巨大化) 和 **ModifierSplit** (击中分裂 - 简易版 Trigger)。这两个只需要修改 `BulletManager` 的数值逻辑，无需重构 ECS。
2.  **Phase 2 (Medium)**: 实现 **状态交互 (Elemental)**。完善 `EnemyManager` 的状态槽位（目前只有 `freezeTimer`，可以用位运算扩展状态标记）。
3.  **Phase 3 (Hard)**: 实现 **Trigger System**。✅ 架构已在 `implementation_plan.md §2.2` 完成（SubPayloadRegistry + on_hit_payload_id 方案）。本阶段实施重点：编写多层 TRIGGER 嵌套的单元测试，接入 VFXManager 命中回调。

## 6. 数值与平衡参考

| 扩展类型 | 开发难度 | 趣味增益 | 性能消耗 |
| :--- | :--- | :--- | :--- |
| 正弦弹道 | 低 | 中 | 极低 |
| 击中分裂 | 中 | 高 | 高 (子弹数指数增长) |
| 元素反应 | 中 | 高 | 低 |
| 召唤炮台 | 高 | 中 | 中 |