# 程序架构设计与实施计划 (Implementation Plan & Technical Architecture)

## 1. 核心设计原则 (Core Design Principles)

### 1.1 性能优先 (Performance First)
鉴于已确定的"海量弹幕+同屏千人"需求，本项目的核心代码将偏离标准的 Godot 节点组件模式，采用更底层的 **Data-Oriented (面向数据)** 思想。
*   **原则 A**: 战斗循环中尽量避免 `new`（GDScript 实例化）。所有高频对象（Context, Bullet, Enemy）必须池化。
*   **原则 B**: 逻辑与渲染分离。位置更新在 Autoload Manager 的 `_physics_process` 中批量处理，节点的 `_process` 仅负责同步 View。
*   **原则 C**: 避免匿名函数与 Lambda。解释器核心循环使用 `match` 和 `for` 循环，减少函数调用开销。

### 1.2 极度模块化 (Extreme Modularity)
法术系统的每个功能点（如：追踪、分裂）都必须封装为独立的 `Strategy` 类，通过 ID 动态加载。核心系统不能直接依赖具体法术。

**法术注册表 (Spell Registry)** 技术方案：
```gdscript
# spell_registry.gd (Autoload)
# 启动时自动扫描 res://resources/spells/ 目录，加载所有 .tres SpellNode Resource
var _registry: Dictionary = {}  # spell_id (String) -> SpellNode

func _ready() -> void:
    # ⚠️ F13 注意：当前使用同步 load()，主线程阻塞直到所有法术资源加载完毕。
    # 法术数量较少（< 50）时可接受；若未来资源增多，应改用异步预加载：
    #   ResourceLoader.load_threaded_request(path) → 在 Loading 界面 _process 中轮询
    #   load_threaded_get_status()，加载完成后发出信号，不阻塞主线程。
    # P2 路线图：引入 SpellRegistry.preload_async(on_complete: Callable) 接口。
    var dir := DirAccess.open("res://resources/spells/")
    if dir == null:
        push_error("SpellRegistry: 无法打开 res://resources/spells/ 目录")
        return
    dir.list_dir_begin()
    var file := dir.get_next()
    while file != "":
        if file.ends_with(".tres"):
            var res: SpellNode = load("res://resources/spells/" + file)
            if res != null:
                _registry[res.id] = res
            else:
                push_warning("SpellRegistry: 加载失败 - %s" % file)
        file = dir.get_next()
    dir.list_dir_end()  # ⚠️ 必须调用，否则目录句柄不会释放

func get(id: String) -> SpellNode:
    return _registry.get(id, null)

func all_ids() -> Array:
    return _registry.keys()  # ⚠️ keys() 返回无类型 Array，不可声明为 Array[String]
                              # GDScript 4.x 中 Dictionary.keys() 的静态返回类型为 Array
```
*   新增法术只需在 `res://resources/spells/` 中放入一个 `.tres` 文件，无需修改任何代码。
*   `SpellNode.id` 字段必须全局唯一，推荐使用 `category_name` 格式（如 `modifier_damage_plus`）。

### 1.3 零 GC 与内存高效架构 (Zero-GC & Memory Efficiency)
GDScript 的垃圾回收虽不如 JavaScript 激进，但频繁实例化 RefCounted 对象同样会带来性能抖动。架构上强制执行以下模式：
*   **Struct-like Classes**: 核心算子类（如 `Vector2`）优先使用 GDScript 内置值类型（Value Type），它们在栈上分配，无 GC 压力。自定义数据类继承 `RefCounted` 并通过对象池复用。
*   **Ring Buffers**: 音频、粒子、伤害数字使用环形缓冲区，覆盖旧数据而非销毁。
*   **Integer IDs > Objects**: 在 `EventBus` 和 ECS 中，传递整数 ID (entity_id) 而非传递整个对象引用，减少引用计数复杂度。

---

## 2. 模块详细设计 (Detailed Module Design)

### 2.1 核心库层 (Layer 0: Core Libs)

| 模块 | 类名/文件 | 职责说明 | 性能关键点 |
| :--- | :--- | :--- | :--- |
| **Object Pool** | `ObjectPool` (Autoload) | 通用对象池，支持 `reset()` 接口。 | 使用 `Array` 做栈，`append`/`pop_back` 操作。 |
| **Event Bus** | `EventSystem` (Autoload) | 类型安全的全局事件总线。 | 使用整数 ID 代替字符串 Key，减少哈希查找开销；也可直接使用 Godot 原生 Signal。 |
| **Spatial Hash** | `SpatialGrid` | 2D 空间网格，替代 Quadtree。 | 使用 `PackedInt32Array` 一维数组模拟二维网格，直接索引访问 `grid[x + y * width]`。 |
| **Timer** | `TimeManager` (Autoload) | 缩放时间、帧率节流控制。 | 支持 `GameTick` (physics) 与 `RenderFrame` (process) 分离。 |

#### EventBus 事件目录 (Event Catalog)

所有跨系统通信必须通过此表对齐，不得私自定义事件 ID。

> **E-N1 规范**：事件 ID 必须使用以下具名常量（`EventID` 枚举或 Autoload 常量），禁止在业务代码中直接写裸整数，防止撞号和可读性问题。
```gdscript
# event_ids.gd (Autoload: EventID)
const APPLY_DAMAGE:       int = 1
const ENEMY_KILLED:       int = 2
const SPELL_CAST_BEGIN:   int = 3
const BULLET_HIT:         int = 4
const PLAYER_DAMAGED:     int = 5
const PLAYER_DIED:        int = 6
const WAVE_COMPLETE:      int = 7
const STATUS_APPLIED:     int = 8
const CHARGE_STATE_CHANGED: int = 9  # 停步蓄力进度变化 → UIManager
const ON_PLAYER_HURT:       int = 10 # 玩家受到伤害时触发（用于受击释放法术/反弹尖刺等 OnHurt 钩子）
const MINION_SPAWNED:        int = 11 # 召唤物创建 → UIManager 更新召唤物计数显示
const MINION_EXPIRED:        int = 12 # 召唤物消亡 → UIManager 更新召唤物计数显示
const DASH_TRIGGERED:        int = 13 # 玩家执行冲刺动作时触发（dash 输入按下瞬间）→ SpellEvaluator(OnDash 钩子，dash-wave Core 附加法术), UIManager(清除蓄力进度 UI)
                                       # 负载: { "caster_id": int, "stationary_time": float }（冲刺前已积累的静止时长，供 dash-wave Core 读取）
                                       # ⚠️ 与 CHARGE_FIRED(14) 的区别：DASH_TRIGGERED 由冲刺操作触发；CHARGE_FIRED 由停步静止时长首次超阈值触发（无冲刺）。
const CHARGE_FIRED:          int = 14 # 停步蓄力首次达到阈值时发出（仅一次，非每帧）→ SpellEvaluator(执行超载版法术)
                                       # 区别于 CHARGE_STATE_CHANGED（每帧进度，仅供 UI）：
                                       # CHARGE_STATE_CHANGED 持续更新进度环动画；
                                       # CHARGE_FIRED 是一次性触发信号，SpellEvaluator 只订阅此事件来实际释放法术。
                                       # 负载: { "caster_id": int }
const BOSS_PHASE_CHANGED:    int = 15 # boss_design.md §6：Boss 阶段切换 → HUD、AudioManager（BGM 分层）
const BOSS_KILLED:           int = 16 # boss_design.md §6：Boss 死亡 → WaveManager、AchievementManager
const GAME_CLEARED:          int = 17 # boss_design.md §6：通关 → GameCycleManager、排行榜
const ACHIEVEMENT_UNLOCKED:  int = 18 # certification_checklist.md ST-10：Steam 成就解锁（须幂等）
                                       # 负载: { "achievement_id": String }
const SETTINGS_CHANGED:      int = 19 # architecture_design.md ADR-C1 / SettingsManager：字体缩放、高对比度等
                                       # 负载: { "key": String }（例：`font_scale`、`high_contrast`）
const GAME_STATE_CHANGED:    int = 20 # architecture_design.md §5.1：FSM 状态切换（GameCycleManager 发出）
                                       # 负载: { "prev": GameState, "next": GameState }
                                       # 订阅方：UIManager（路由 UI 切换）、AudioManager（切换 BGM/SFX）
const SPELL_DROP_PICKUP:     int = 21 # architecture_design.md §5.3：法术掉落拾取弹 UI 事件
                                       # 负载: { "spell_id": String, "auto_equip": bool }
                                       # 发出方：DropManager（掉落拾取）、ShopManager.offer_free_spell()
                                       # 订阅方：UIManager（弹背包选 Core 界面）、PlayerManager（auto_equip=true 时直接装备）
# 新增事件从 22 起递增，并向下表登记
```

| 事件 ID | 具名常量 | 名称 | 负载内容 | 发出方 | 订阅方 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `1` | `EventID.APPLY_DAMAGE` | `APPLY_DAMAGE` | `damage_context_id: int` | `SpellEvaluator` / `StatusManager` | `EnemyManager` |
| `2` | `EventID.ENEMY_KILLED` | `ENEMY_KILLED` | `enemy_id: int, killer_id: int` | `EnemyManager` | `PlayerStats`, `DropManager`, `MissionTracker` |
| `3` | `EventID.SPELL_CAST_BEGIN` | `SPELL_CAST_BEGIN` | `caster_id: int, deck_id: int` | `SpellEvaluator` | `VFXManager`, `AudioManager` |
| `4` | `EventID.BULLET_HIT` | `BULLET_HIT` | `bullet_id: int, target_id: int` | `BulletManager` | `SpellEvaluator`(proc), `VFXManager` |
| `5` | `EventID.PLAYER_DAMAGED` | `PLAYER_DAMAGED` | `amount: float, source_id: int` | `PlayerManager` | `UIManager`, `AudioManager` |
| `6` | `EventID.PLAYER_DIED` | `PLAYER_DIED` | 无 | `PlayerManager` | `GameCycleManager` |
| `7` | `EventID.WAVE_COMPLETE` | `WAVE_COMPLETE` | `wave_num: int` | `WaveManager` | `ShopManager`, `GameCycleManager` |
| `8` | `EventID.STATUS_APPLIED` | `STATUS_APPLIED` | `target_id: int, status_type: int, stacks: int` | `StatusManager` | `VFXManager`, `EnemyManager` |
| `9` | `EventID.CHARGE_STATE_CHANGED` | `CHARGE_STATE_CHANGED` | `caster_id: int, progress: float` | `PlayerManager` | `UIManager` |
| `10` | `EventID.ON_PLAYER_HURT` | `ON_PLAYER_HURT` | `amount: float, source_id: int` | `PlayerManager` | `SpellEvaluator`(OnHurt 钩子), `VFXManager`, `AudioManager` |
| `11` | `EventID.MINION_SPAWNED` | `MINION_SPAWNED` | `minion_id: int, owner_id: int, current_count: int` | `MinionManager` | `UIManager`(召唤物计数显示) |
| `12` | `EventID.MINION_EXPIRED` | `MINION_EXPIRED` | `minion_id: int, owner_id: int, current_count: int` | `MinionManager` | `UIManager`(召唤物计数显示) |
| `13` | `EventID.DASH_TRIGGERED` | `DASH_TRIGGERED` | `caster_id: int, stationary_time: float` | `PlayerManager` | `SpellEvaluator`(OnDash钩子，dash-wave Core 附加法术), `UIManager`(蓄力UI清除) |
| `14` | `EventID.CHARGE_FIRED` | `CHARGE_FIRED` | `caster_id: int` | `PlayerManager` | `SpellEvaluator`(执行超载版法术) |
| `15` | `EventID.BOSS_PHASE_CHANGED` | `BOSS_PHASE_CHANGED` | `boss_id, phase, bgm_layer` | `BossManager` | `UIManager`, `AudioManager` |
| `16` | `EventID.BOSS_KILLED` | `BOSS_KILLED` | `boss_id, wave_num` | `BossManager` | `WaveManager`, `AchievementManager` |
| `17` | `EventID.GAME_CLEARED` | `GAME_CLEARED` | `elapsed_sec, wave_num` | `BossManager` / `GameCycleManager` | `GameCycleManager`, 排行榜 |
| `18` | `EventID.ACHIEVEMENT_UNLOCKED` | `ACHIEVEMENT_UNLOCKED` | `achievement_id: String` | 各游戏系统 | `AchievementManager` → Steam |
| `19` | `EventID.SETTINGS_CHANGED` | `SETTINGS_CHANGED` | `key: String` | `SettingsManager` | `UIManager`（全局主题/字体重载） |
| `20` | `EventID.GAME_STATE_CHANGED` | `GAME_STATE_CHANGED` | `prev: int, next: int` | `GameCycleManager` | `UIManager`, `AudioManager` |
| `21` | `EventID.SPELL_DROP_PICKUP` | `SPELL_DROP_PICKUP` | `spell_id: String, auto_equip: bool` | `DropManager`, `ShopManager` | `UIManager`, `PlayerManager` |
> 新增事件从 **22** 起递增，并向下表登记。规则：编号永不重用（可标 DEPRECATED 但不删除）。

> **E-N2 跨语言边界协议（GDScript ↔ C#）**：`architecture_design.md §6` 规定跨语言只传基本类型（int/float/Vector2/Godot.Array）。`DamageContext`（RefCounted）**不得直接穿越语言边界**。约定如下：
> - `EnemyManager` 遵循与 `BulletManager` 相同的 **ADR-L1 规则 4** 模式：`enemy_manager.gd`（GDScript Autoload）持有 `_data: PackedFloat32Array` 并对外暴露接口；`EnemyManagerCs.cs`（C# 子节点）处理 `_PhysicsProcess` 热路径（Boid 分离力、SoA 积分），预期帧时间 GDScript ≈6ms → C# ≈0.6ms（见 §6.1 语言分工表）。
> - `APPLY_DAMAGE` 事件的处理逻辑位于 GDScript Autoload 层，负载 `damage_context_id: int` 是 `DamageContextPool` 的槽位索引，GDScript 层调用 `DamageContextPool.get_context(id)` 取得对象后处理伤害，处理完毕立即 `release(id)`。`DamageContext` 不穿越 GDScript ↔ C# 语言边界。

> **DamageContextPool 定义**：E-N2 中引用的 `DamageContextPool` 为伤害上下文对象池 Autoload，定义如下：
> ```gdscript
> # ── damage_context.gd ──────────────────────────────────────────────────────────
> # DamageContext 数据类必须单独放在 damage_context.gd 中，
> # 禁止将 class_name DamageContext 写在 damage_context_pool.gd 里（否则 Autoload 实例自身就是
> # DamageContext 类型，导致 _pool: Array[DamageContext] 存入了具有池管理方法的对象，语义错误）。
> class_name DamageContext
> extends RefCounted
> var base_damage: float = 0.0
> var mult:        float = 1.0
> var damage_type: int   = DamageType.PHYSICAL  # 使用枚举常量，禁止裸整数
> var owner_id:    int   = -1
> var source_tags: int   = 0
> var is_crit:     bool  = false    # 影响暴击字体/特效（见 combat_mechanics_depth.md §4）
> var pierce_rate: float = 0.0      # 护甲穿透率 (0.0~1.0)，EnemyManager.apply_damage() 中使用
>
> # ── damage_context_pool.gd (Autoload: DamageContextPool) ──────────────────────
> # 本文件不声明 class_name；由 Godot Project Settings 注册为 Autoload "DamageContextPool"。
> # 采用固定大小槽位数组 + PackedInt32Array 空闲 ID 栈：O(1) 申请/归还，零动态分配，零 GC。
> const POOL_SIZE: int = 64
> var _slots:    Array[DamageContext]   # 固定槽位，索引即 ID（预分配，_ready() 填充）
> var _free_ids: PackedInt32Array       # 空闲 ID 栈（append/pop_back，O(1)，零 GC）
> var _in_use:   PackedByteArray        # 占用标记：1=已 acquire；防重复 release
>
> func _ready() -> void:
>     _slots.resize(POOL_SIZE)
>     _free_ids.resize(POOL_SIZE)
>     _in_use.resize(POOL_SIZE)
>     for i in POOL_SIZE:
>         _slots[i]    = DamageContext.new()
>         _free_ids[i] = POOL_SIZE - 1 - i  # 初始化：index 0 最先被弹出
>         _in_use[i]   = 0
>
> # ⚠️ 必须先调用 ctx.reset()，防止从池中取出的旧实例残留 source_tags 等脏数据。
> func acquire(base_dmg: float, m: float, dtype: int, owner: int,
>              crit: bool = false, pierce: float = 0.0) -> int:
>     if _free_ids.is_empty():
>         push_warning("DamageContextPool: 池已耗尽，动态扩展（POOL_SIZE=%d 建议上调）" % POOL_SIZE)
>         var new_id: int = _slots.size()
>         _slots.append(DamageContext.new()); _in_use.append(0)
>         return _fill_slot(new_id, base_dmg, m, dtype, owner, crit, pierce)
>     var id: int = _free_ids[_free_ids.size() - 1]
>     _free_ids.resize(_free_ids.size() - 1)  # pop_back，O(1)
>     return _fill_slot(id, base_dmg, m, dtype, owner, crit, pierce)
>
> func _fill_slot(id: int, base_dmg: float, m: float, dtype: int, owner: int,
>                 crit: bool, pierce: float) -> int:
>     var ctx: DamageContext = _slots[id]
>     ctx.reset()  # 清除所有残留字段后再覆写，保证每次 acquire 的上下文状态干净
>     ctx.base_damage = base_dmg; ctx.mult = m
>     ctx.damage_type = dtype;    ctx.owner_id = owner
>     ctx.is_crit = crit;         ctx.pierce_rate = pierce
>     _in_use[id] = 1
>     return id
>
> func get_context(id: int) -> DamageContext:
>     if id < 0 or id >= _slots.size() or _in_use[id] == 0: return null
>     return _slots[id]
>
> func release(id: int) -> void:
>     if id < 0 or id >= _slots.size() or _in_use[id] == 0:
>         push_warning("DamageContextPool.release: 无效或重复归还 ID=%d" % id)
>         return
>     _in_use[id] = 0
>     _free_ids.append(id)   # push_back，O(1)，不触发 GC
>
> func reset() -> void:
>     # GameCycleManager._reset_all_managers() 在波次/Run 重置时调用。
>     # 将所有 in-use 槽位强制归还（防止跨波次泄漏），清空空闲 ID 栈后重建。
>     _free_ids.clear()
>     for i in _slots.size():
>         _in_use[i] = 0
>         _free_ids.append(i)
> ```
> **使用约定**：`SpellEvaluator` 发出 `APPLY_DAMAGE` 前调用 `DamageContextPool.acquire(...)` 获取整数 ID；
> `EnemyManager` 收到事件后调用 `get_context(id)` 处理伤害，处理完毕立即调用 `release(id)` 归还，
> 不得持有 DamageContext 跨帧引用。

### 2.2 法术解释器层 (Layer 1: Spell Virtual Machine)

这是本项目的"CPU"，负责执行 `SpellNode` 指令。

#### 数据结构

**SpellDeck** — 运行时执行游标
```gdscript
class_name SpellDeck
# _nodes: Array[SpellNode]，预编译后不再修改
# _cursor: int，当前执行位置
#
# Scope 边界标记：预编译时每个 SCOPE_OPEN 节点（LOGIC_IF_*、TRIGGER 后续体）
#   在 _nodes 中紧跟虚拟节点 SpellNode{type=SCOPE_CLOSE, id="_scope_end"}。
#   skip_until_scope_end() 推进 cursor 直到遇到第一个 SCOPE_CLOSE（深度计数器处理嵌套）。
#   consume_until_scope_end() 同理，返回中间节点序列用于打包 SubPayload。
#   O(N) 线性扫描定位边界，N ≤ MAX_OPS_PER_CPU × cpu_limit。
func has_next() -> bool: return _cursor < _nodes.size()
func pop() -> SpellNode:
    # 完整实现须包含 _consumed 掩码跳过（见 architecture_design.md §3.4.C）
    if _cursor >= _nodes.size(): return null
    var node := _nodes[_cursor]
    _cursor += 1           # GDScript 不支持后置 ++ 运算符
    return node
func skip_until_scope_end() -> void: ...
func consume_until_scope_end() -> Array[SpellNode]: ...
```

**CompiledDeck** — 预编译产物，关卡期间只读
```gdscript
class_name CompiledDeck
# compile_wand(core: CoreDefinition, raw_deck: SpellDeck) -> CompiledDeck
# 由 SpellEvaluator 在背包关闭时调用
#
# nodes: Array[SpellNode]      拓扑扁平化 + SCOPE 虚节点插入后的线性序列
# label_table: Dictionary      { label_id: int -> node_index: int }（LOGIC_LABEL 专用）
# sub_payload_ids: Array[int]  本 Deck 预编译时注册到 SubPayloadRegistry 的所有 ID
# topology_type: int           0=LINEAR 1=MATRIX 2=CIRCUIT（影响 _flatten_* 选择）
# checksum: int                插槽内容哈希，用于判断是否需要重新编译
#   算法：多项式滚动哈希（对换位敏感，避免 [A,B] 与 [B,A] 产生相同 checksum）：
#     checksum = topology_type ^ slot_count ^ (grid_cols << 8) ^ hash(core.id)
#     // grid_cols 防止不同列宽的 MATRIX Core 碰撞（2×4 与 4×2 slot_count 相同）
#     // hash(core.id) 防止不同 Core ID 但拓扑相同时 checksum 碰撞导致跳过重编译
#     for i in range(nodes.size()):
#         checksum = checksum * 31 ^ hash(nodes[i].id)
#
# 运行时 SpellEvaluator 从 CompiledDeck 构造一个 SpellDeck（拷贝 nodes 并重置 cursor）
var nodes: Array[SpellNode]
var label_table: Dictionary
var sub_payload_ids: Array[int]
var topology_type: int = 0
var checksum: int = 0
```

**CastState** — 单次 execute 调用的临时状态
```gdscript
# trigger_depth: int，当前 execute_sub 嵌套深度（防止 TRIGGER 无限递归）
# registers: PackedFloat32Array，长度 4，R1-R4
# ⚠️ 重要区分：
#   CastState.registers  → 单次 execute() 内的临时工作寄存器，每次 execute() 开始时重置，不跨调用保留
#   SpellContext.registers → 跨帧持久寄存器（见 architecture_design.md §3.2）
# LOGIC_EVERY_N_SHOTS【必须】使用 SpellContext.registers（否则计数器每帧重置，永远等效为"每次都触发"）。
# _execute_logic() 收到 LOGIC_EVERY_N_SHOTS 时通过 spell_ctx 参数访问 spell_ctx.registers[0]。
```

#### 执行流程 (`SpellEvaluator.execute`)
```gdscript
# MAX_OPS_PER_CPU = 40：每点玩家属性 cpu_limit 换算为 40 步执行额度
# 运行时：_max_ops = PlayerStats.cpu_limit × MAX_OPS_PER_CPU（默认 cpu_limit=5 → MAX_OPS=200）
# 超过限制立即中断，防止图灵完备构建死循环
const MAX_OPS_PER_CPU: int = 40
const MAX_TRIGGER_DEPTH: int = 3  # execute_sub 嵌套最大深度；超过 3 层时 TRIGGER 不再触发新的 SubPayload
                                  # 分工：MAX_OPS 管单次施法内指令总量；MAX_TRIGGER_DEPTH 管跨弹体调用深度
                                  # ⚠️ 超限时不得静默失效：当 execute_sub 被 TRIGGER_DEPTH 隔断时，
                                  # EventBus 发出 SPELL_CAST_BEGIN 事件并附带 flag "depth_exceeded=true"，
                                  # UIManager 订阅该 flag，在 HUD 显示短暂黄色闪烁（"[法术链太深，部分触发已忽略]"）。
                                  # 开发期保留 push_warning；正式版将 push_warning 改为发出事件。
var _max_ops: int = 200  # 战斗开始时更新：_max_ops = PlayerStats.cpu_limit * MAX_OPS_PER_CPU

while deck.has_next() and ops_count < _max_ops:
    ops_count += 1
    var node: SpellNode = deck.pop()
    match node.type:
        SpellType.ACTION:
            _push_projectile(node, context)
        SpellType.MODIFIER:
            node.apply(context)  # 直接修改 context.stats
            # Multicast 边缘规则：若 Deck 剩余法术数 < draw_count，以"尽力而为"策略执行
            # （弹出现有法术直至 Deck 耗尽，不崩溃），法杖编辑 UI 对此显示黄色警告。
        SpellType.TRIGGER:
            # 实现方案：预编译时打包 SubPayload，运行时查表执行
            # 1. 将 TRIGGER 后续的 SpellNode 序列打包为 SubPayload，注册到全局表，得到整数 ID
            # 2. 子弹在 PackedFloat32Array 中仅携带 on_hit_payload_id (int)
            # 3. 命中时 BulletManager 查表并调用 SpellEvaluator.execute_sub(payload_id, hit_pos, owner_id)
            # 这样子弹逻辑与 PackedFloat32Array 热数据完全解耦
            var payload_id: int = SubPayloadRegistry.register(deck.consume_until_scope_end())
            context.current_payload.on_hit_payload_id = payload_id
        SpellType.LOGIC:
            # 最小指令集（详细行为见 architecture_design.md §3.4.B）：
            # LOGIC_IF_HP_BELOW     → 读 caster HP%，条件不满足则 deck.skip_until_scope_end()
            # LOGIC_IF_ENEMY_NEARBY → SpatialGrid 查询 context.range 内是否有敌方实体
            # LOGIC_EVERY_N_SHOTS   → 读写 spell_ctx.registers[0..3]（SpellContext，跨帧持久！）
            #                         ⚠️ 严禁使用 CastState.registers（每帧重置 → 计数器永远不累积）
            # LOGIC_LOOP(count, body_size)
            #   → 将紧随其后的 body_size 个节点重复执行 count 次（count ≤ 8，超限裁剪）
            #   → 每次循环消耗 body_size 个 ops；总耗费 = count × body_size，计入 ops_count
            #   → 与 MAX_OPS 交互：LOOP(5, 3) = 15 ops；若 ops_count + 15 > _max_ops 则提前截断
            #   → game_design.md §3.2.D 中「循环执行后续 3 个法术 5 次」即为 LOGIC_LOOP(5, 3)
            # LOGIC_LABEL / LOGIC_JUMP_IF → 仅限 persistent_memory Core；预编译时建立 _label_table
            # LOGIC_FORK  → CIRCUIT 拓扑分叉专用（由 _flatten_circuit 注入，玩家不可购买）
            #   node.id = "LOGIC_FORK"；node.get_meta("fork_branch_ids") = Array[int] SubPayload ID 列表
            #   _execute_logic 识别 LOGIC_FORK 时对每个 fork_branch_id 调用 execute_sub()
            #   消耗 fork_branch_ids.size() 个 ops（每个分支算 1 步），计入 ops_count
            _execute_logic(node, context, deck)
# ops_count 达到上限时：① 开发期 push_warning；② 通过 EventBus 向玩家 HUD 发出反馈
# 截断不得静默，玩家须知构建已被截断（与 MAX_TRIGGER_DEPTH "depth_exceeded" 事件相同规范）。
# UIManager 订阅 SPELL_CAST_BEGIN 中 "ops_exceeded: true" 标志，HUD 显示短暂黄色闪烁提示。
if ops_count >= _max_ops:
    push_warning("SpellEvaluator: MAX_OPS reached, build may be too complex")
    EventBus.emit(EventID.SPELL_CAST_BEGIN, {
        "caster_id": context.caster_id, "deck_id": -1, "ops_exceeded": true
    })
```

> **LOGIC 指令集扩展路径**：当前 `_execute_logic` 使用中央 `match node.id` 硬编码所有 LOGIC 指令，新增 LOGIC 类型需修改核心（OCP 限制）。
> **P0/P1**：保留 match 实现，LOGIC 指令集固定不超过 8 条，可接受。
> **P2 路线图**：若 LOGIC 指令集需扩展超过 10 条，引入 `LogicHandler` 接口：
> ```gdscript
> # logic_handler.gd
> class_name LogicHandler
> extends RefCounted
> func handle(node: SpellNode, context: SpellContext, deck: SpellDeck) -> void: pass
>
> # 在 SpellRegistry 中按 node.id 注册：
> # SpellRegistry.register_logic_handler("LOGIC_MY_NEW", MyNewHandler.new())
> # _execute_logic 改为：
> # SpellRegistry.get_logic_handler(node.id).handle(node, context, deck)
> ```
> 迁移前无需改变 P0/P1 行为，仅 P2 新增 LOGIC 法术卡采用新接口注册。

#### SubPayloadRegistry 生命周期
*   **创建时机**：玩家关闭背包（预编译）时，`SpellEvaluator.compile_wand(core, raw_deck)` 清空并重建整个 Registry。
*   **清空时机**：关卡切换、游戏结束时全量清除。滚动最终销毁所有未使用的 SubPayload 对象还入对象池。
*   **并发处理**：多弹一帧内同时命中时，`execute_sub` 可并行执行同一 `payload_id`， Registry 不发生冲突（只读）。
*   **竞争条件安全保证**：Registry 重建发生在玩家**关闭**背包时，而非打开时。
    因此飞行中的弹体在玩家进入商店编辑阶段时，其 `on_hit_payload_id` 仍指向当前 Registry 中的有效条目——
    战斗波次结束后所有弹体自然清空，Registry 重建（下次关闭背包）必定早于下波战斗开始；
    不存在"弹体持有旧 payload_id、Registry 已重建为新 ID 映射"的竞争窗口。
    > **禁止行为**：不得在波次**进行中**允许玩家修改 Deck（如暂停菜单热插拔法术），否则将违反此不变量。
    > 如未来需支持"战斗中暂停换牌"，必须先清空所有飞行中的弹体，再执行重编译，最后恢复生成。

### 2.3 战斗实体层 (Layer 2: Combat ECS-Lite)

#### A. 物理与碰撞 (Physics & Collision)

碰撞系统采用**分档策略**，不同弹幕密度区间使用不同方案；`BulletManager._collision_mode` 标志控制当前路径（详见 `architecture_design.md §4.3`）：

| 同屏弹幕数 | 碰撞方案 | 说明 |
| :--- | :--- | :--- |
| < 200 | **Area2D + CircleShape2D** | Godot 内置碰撞；Physics Layer/Mask 过滤阵营；`body_entered` 信号回调 `_on_bullet_hit()` |
| 200–2000 | **自定义 SpatialGrid（主力）** | BulletManager 每帧 dirty-list 重建网格，手动 `query_circle()`；Area2D 实例全部禁用 |
| 2000+ | **SpatialGrid + MultiMesh** | 碰撞继续走 SpatialGrid；渲染切换 MultiMeshInstance2D |

> **⚠️ S0 验证目标（风险 R-04）**：S0 期间在 500+ 弹幕时实测 Area2D 帧时间（预期 > 8ms）。验证后**永久锁定 SpatialGrid 为 200+ 弹幕的主力碰撞方案**，Area2D 路径不再作为运行时"降级回退"保留。

*   **Physics Layer & Mask 配置**（< 200 弹幕 Area2D 路径）：Layer 1 = 玩家，Layer 2 = 子弹，Layer 3 = 敌人；子弹 Layer 2 只检测 Layer 3；`body_entered` → `_on_bullet_hit(bullet_id, enemy_id)`。
*   **SpatialGrid 主路径**（200+）：两路径最终均调用相同的 `_on_bullet_hit(bullet_id, enemy_id)` 处理函数，后处理逻辑完全共用；切换入口仅在 `_collision_mode` 标志处。

#### B. 子弹系统 (`BulletManager`)
*   **混合渲染模式**:
    *   **逻辑层**: 依然使用 `PackedFloat32Array` 管理子弹的生命周期和属性（速度/伤害），SoA 布局保证缓存友好。
    *   **表现层**: 利用 Node Pool 复用 `Node2D` 节点；对于极大量同类子弹，改用 `MultiMeshInstance2D` 直接 GPU 实例化渲染，大幅降低 Draw Call。
    *   **同步优化**: 只有当子弹位置发生显著变化或处于屏幕视口内时，才设置 `Node2D.position`，利用 Godot 的脏标记机制避免无效渲染树更新。

#### C. 敌人系统 (`EnemyManager`)

**EnemyManager 热数据 SoA 布局（权威定义）**

敌人数量可达 1000+，同 BulletManager 一样需要 PackedFloat32Array SoA 结构：

```
const ENEMY_STRIDE: int = 8

stride = ENEMY_STRIDE 个 float
[ x, y, vx, vy, hp, hp_max, faction_and_type, status_bits ]
  0   1   2   3   4    5          6                 7
```
- `faction_and_type`：高 16 位 = faction（0=敌方, 1=友方/召唤物），低 16 位 = enemy_type_id
- `status_bits`：燃烧/冰冻/中毒等状态的位掩码（各类 DoT 的精确数值存冷数据）
- 复杂数据（AI 状态、DoT 计时器、combo_tracker）存入 `_enemy_contexts: Dictionary`（key = entity_id）

**SpatialGrid 每帧清空策略（P5）**

`SpatialGrid` 每 `_physics_process` 帧重建一次，采用 **Dirty-List 方案**而非全量 memset：
- `_dirty_cells: PackedInt32Array` 记录本帧有写入的 Cell 索引。
- 帧末遍历 `_dirty_cells`，仅清空这些 Cell，跳过空 Cell。
- 当 `_active_count > 1500` 时切换为全量 fill(0)（此时脏格子数量接近总数，遍历反而更慢）。

*   **AI 状态机**：AI 逻辑**不使用 AnimationTree 驱动**，而是以轻量级枚举存于 `_enemy_contexts[entity_id]["ai_state"]`（0=IDLE / 1=CHASE / 2=ATTACK / 3=RETREAT）。`EnemyManager._physics_process` 在 Manager 内部批量完成所有状态转换，不经过 Godot 场景树。
    *   **单向驱动**：帧末对**屏内**敌人（`_visible_flags[i] == 1`）将 `ai_state` 映射为 AnimationTree 参数（`anim_tree.set("parameters/conditions/is_running", ...)`），AnimationTree **仅接收结果，不反向影响逻辑**；屏外敌人完全跳过 AnimationTree 更新。
    *   **⚠️ 禁止**：不得用 AnimationTree StateMachine 驱动 AI 逻辑转换；不得在 `_physics_process` 热路径内对屏外敌人调用 `anim_tree.set()`（大量屏外时 1000× 调用/帧严重浪费）。
*   **LOD（屏外 AI 剔除）**：❌ **不使用** `VisibilityNotifier2D` per-enemy 方案（1000+ 敌人各挂一个节点 = 1000+ 额外信号监听，节点开销显著）。改为 **Manager 侧 Camera Rect AABB 批量剔除**：
    ```gdscript
    # ⚠️ _visible_flags 必须声明为 EnemyManager 的类成员（PackedByteArray），
    # 禁止在 _physics_process 内用 var 声明（否则每帧分配新数组，触发 GC 抖动）。
    # 类成员声明（EnemyManager 顶部）：
    #   var _visible_flags: PackedByteArray = PackedByteArray()
    # 每当 _enemy_count 扩容时同步 _visible_flags.resize(_enemy_count)
    #
    # EnemyManager._physics_process 每帧执行（O(N) 单次矩形测试）：
    var cam_rect: Rect2 = _get_camera_rect_expanded(128.0)  # 扩大 128px 防闪烁
    for i in range(_enemy_count):
        var pos := Vector2(_data[i * ENEMY_STRIDE + 0], _data[i * ENEMY_STRIDE + 1])
        _visible_flags[i] = int(cam_rect.has_point(pos))  # ⚠️ 必须显式 int() 转换
                                                           # has_point() 返回 bool，
                                                           # 直接赋给 PackedByteArray[i] 会静默写入错误值
    # _physics_process 遍历时跳过 _visible_flags[i] == 0 的实体 AI 计算
    ```
    *   相比 VisibilityNotifier2D，此方案无额外节点、无信号开销，N=1000 时约节省 ~1000 次信号 dispatch/帧，适合 ECS-Lite 架构。

> **屏外 Boid 分离力低频保留**：完全跳过屏外敌人 AI 会导致 Boid 分离斥力缺失——大量屏外实体相互挤叠，进入视野瞬间爆发弹射（视觉闪烁）。
> **解决方案**：`_visible_flags[i] == 0` 的屏外敌人**不跳过分离力更新**，改为以低频单独运行：
> ```gdscript
> const OFFSCREEN_SEPARATION_INTERVAL: int = 10  # 每 10 帧更新一次屏外分离力
>
> for i in range(_enemy_count):
>     if _visible_flags[i]:
>         _update_ai_full(i)            # 全量 AI：索敌 + 分离力 + 动画参数
>     elif Engine.get_physics_frames() % OFFSCREEN_SEPARATION_INTERVAL == i % OFFSCREEN_SEPARATION_INTERVAL:
>         _update_separation_only(i)    # 仅分离斥力：查 SpatialGrid 最近 8 格，O(1)
> ```
> - `_update_separation_only` 无 AI 状态机、无动画更新，每帧参与计算的屏外实体数 ≤ N/10。
> - 10 帧低频下最坏分离响应时延 ≈ 166ms（60 Hz），不可感知；可消除进视野瞬间弹射。

### 2.4 状态效果系统 (`StatusManager`)

#### 核心常量

```gdscript
# status_manager.gd (Autoload: StatusManager)
# _physics_process 热路径见 csharp/autoloads/StatusManagerCs.cs (ADR-L1)

## 每个实体允许同时存在的最大状态类型数量（STATUS_BATCH_LIMIT）
const STATUS_BATCH_LIMIT: int = 8

## 同一状态类型的最大叠加层数上限
const STATUS_MAX_STACKS: int = 16
```

**设计依据**：单实体最多 8 种状态类型。`_physics_process` 最坏情况 = 1000 敌人 × 8 状态 = 8000 次 tick 检查/帧，仍在帧预算内（ADR-L1 规定 StatusManagerCs < 1.5ms）。

#### 超限淘汰策略（Eviction）

当某实体活跃状态数 = `STATUS_BATCH_LIMIT` 且接收到新状态时，按以下顺序决策：

| 优先级 | 规则 |
| :--- | :--- |
| 1（最高）| 同类型 → 刷新 duration，按叠加规则增减 stacks，**不占新槽** |
| 2 | 同组升级（如 CHILL→FREEZE）→ 替换，保留剩余 duration，**不增加槽数** |
| 3 | LRU 淘汰 → 踢出 `last_applied_time` 最早的状态，空槽后写入新状态 |
| 4（最低）| 新状态优先级 < 所有现存状态 → 静默丢弃，`push_warning` 记录 |

```gdscript
## 状态分组（同组内高等级覆盖低等级）
const STATUS_GROUP: Dictionary = {
    StatusType.BURN:    "fire_dot",   StatusType.SCORCH:  "fire_dot",
    StatusType.POISON:  "toxic_dot",  StatusType.CORRODE: "toxic_dot",
    StatusType.CHILL:   "cold",       StatusType.FREEZE:  "cold",
    StatusType.SLOW:    "cc",         StatusType.STUN:    "cc",
}
```

#### DoT Tick 规则

```gdscript
// StatusManagerCs.cs —— _physics_process 热路径（C#）
// tick_timer 使用 while 模式，与 ZoneManager 规范一致：
// while (tickTimer >= TICK_INTERVAL) { tickTimer -= TICK_INTERVAL; ApplyDot(entityId, status); }
// 最坏情况：STATUS_BATCH_LIMIT = 8 种 × 1000 敌人 = 8000 次检查/帧
```

#### 与 ZoneManager 的交互规则

- ZoneManager 通过 `StatusManager.apply(entity_id, type, stacks, duration=0, source_id=zone_id)` 施加持续性区域 DoT。
- `duration=0` 表示"持续存在直到来源主动移除"；区域销毁时调用 `StatusManager.remove_source(zone_id)` 批量清除。
- **同一来源的相同状态不占新槽**，直接刷新 timer（防止多个同类型区域叠满 8 槽）。

### 2.5 基础服务框架 (Layer 3: System Services)
使用 Godot 4 的 **InputMap** 系统作为底层驱动，在上层封装一层 **"Action-Based"** 的抽象。
*   **抽象层**: 游戏逻辑通过 `Input.get_vector("move_left", "move_right", "move_up", "move_down")` 获取移动向量，不关心具体设备。
*   **设备支持**:
    *   **键盘/鼠标**: `WASD` 在 InputMap 中映射为 `move_*` Action，鼠标位置通过 `get_global_mouse_position()` 获取瞄准方向。
    *   **虚拟摇杆**: 监听 UI 层触摸事件，转换为 (-1, 1) 的向量，映射到同名 Action。
    *   **手柄 (Gamepad)**: 利用 Godot 内置的 `Input.get_joy_axis()` 和 `Input.is_joy_button_pressed()`，InputMap 已支持手柄轴自动绑定。
        *   **自动适配**: 识别 `Input.get_joy_name(device_id)` 来区分 Xbox / PS 的按键图标显示。
        *   **死区处理**: 在 InputMap 中直接配置 `Deadzone` 参数，或在 Manager 层统一处理防止摇杆漂移。

> **PlayerManager 移动状态追踪**：`game_design.md §5` 描述了移动敏感型法术
> （移动增益型、冲刺波、停步蓄力型），这些功能要求 `PlayerManager` 持续追踪玩家运动状态：
> ```gdscript
> # player_manager.gd（相关字段，非完整类定义）
> var _is_moving: bool = false             # 当前帧是否在移动（move_vector.length() > MOVE_THRESHOLD_NORM）
> var _stationary_time: float = 0.0       # 连续静止时长（秒）；移动时立即清零
> var _charge_triggered: bool = false     # 停步蓄力已触发标志；边沿检测，防止每帧重复发出 CHARGE_FIRED
> var _last_dash_time: float = -999.0     # 上次冲刺时刻（用于冲刺波冷却）
> # MOVE_THRESHOLD_NORM：归一化输入轴幅度（0.0~1.0），非像素/秒速度
> # 0.067 = 约 6.7% 摇杆偏移即判定为移动（死区 + 轻微触碰阈值）
> const MOVE_THRESHOLD_NORM: float = 0.067  # 对应约 20px/s @ 300px/s 最大速度
> const CHARGE_TRIGGER_TIME: float = 1.5  # 停步蓄力法术所需静止时长（秒）
>
> func _physics_process(delta: float) -> void:
>     var move_vec := Input.get_vector("move_left", "move_right", "move_up", "move_down")
>     _is_moving = move_vec.length() > MOVE_THRESHOLD_NORM
>     if _is_moving:
>         if _stationary_time > 0.0:
>             _stationary_time = 0.0
>             _charge_triggered = false   # 移动后重置标志，允许下次停步重新触发
>             EventBus.emit(EventID.CHARGE_STATE_CHANGED, {"caster_id": player_id, "progress": 0.0})
>     else:
>         _stationary_time += delta
>         if _stationary_time >= 0.3:   # 0.3 秒后开始显示蓄力进度（game_design.md §5）
>             var prog := clampf(_stationary_time / CHARGE_TRIGGER_TIME, 0.0, 1.0)
>             EventBus.emit(EventID.CHARGE_STATE_CHANGED, {"caster_id": player_id, "progress": prog})
>         # 边沿检测：仅首次越过阈值时发出一次 CHARGE_FIRED；持续静止不会重复发送
>         # SpellEvaluator 只订阅 CHARGE_FIRED 以执行停步蓄力法术（非 CHARGE_STATE_CHANGED）。
>         if _stationary_time >= CHARGE_TRIGGER_TIME and not _charge_triggered:
>             _charge_triggered = true
>             EventBus.emit(EventID.CHARGE_FIRED, {"caster_id": player_id})
>
>     # 冲刺输入检测（冲刺波 Core 专属）
>     if Input.is_action_just_pressed("dash"):
>         _last_dash_time = Time.get_ticks_msec() / 1000.0
>         # 附带 stationary_time：SpellEvaluator 用于判断蓄力时长奖励；UIManager 用于清除蓄力 UI
>         EventBus.emit(EventID.DASH_TRIGGERED, {
>             "caster_id": player_id,
>             "stationary_time": _stationary_time   # 冲刺前已积累的静止时长（秒）
>         })
>         _stationary_time = 0.0  # 冲刺后立即清零
>         _charge_triggered = false  # 冲刺打断蓄力，重置触发标志允许下次重新蓄力
>         # SpellEvaluator 订阅 DASH_TRIGGERED，触发 dash-wave Core 的附加法术释放
> ```
> **设计约束**：`CHARGE_STATE_CHANGED` 事件仅由 `UIManager` 订阅以驱动蓄力进度环动画；
> `SpellEvaluator` 订阅 `CHARGE_FIRED`（一次性边沿触发信号）以实际释放停步蓄力法术。
> 两者均通过 EventBus 解耦，`PlayerManager` 不直接持有 UI 引用或 SpellEvaluator 引用。
> ⚠️ 禁止让 `SpellEvaluator` 订阅 `CHARGE_STATE_CHANGED` 并在 `progress >= 1.0` 时触发法术——
> 该事件每帧发送（60Hz），会导致蓄力法术每帧重复释放，违反"首次越阈值只触发一次"的设计原则。

#### B. 音频系统 (`AudioManager`)
针对"割草"游戏的高并发特性进行封装。
*   **Audio Pool**: 预先实例化 32 个 `AudioStreamPlayer2D` 节点，循环使用。
*   **Throttling (节流)**: 维护一个 `last_played_time` 字典。
    *   *规则*: 如果 `explosion_sound` 在 0.1s 内已经播放过，且新的请求音量没有更大，则丢弃该请求。这避免了 50 个敌人同时炸裂时的爆音。
*   **Spatial (空间感)**: 使用 `AudioStreamPlayer2D` 的内置衰减曲线，或根据摄像机位置动态调整 `volume_db` 和 `panning_strength`。

#### C. 资源管理 (`ResourceManager`)
*   **后台加载**: 使用 `ResourceLoader.load_threaded_request(path)` 异步加载法术图标、特效场景等，避免卡顿。
*   **分组管理**: 利用 Godot 的 `ResourceGroup` 或按文件夹路径约定管理资源（如 `res://resources/spells/`、`res://scenes/enemies/`）。
*   **引用计数**: Godot 的 `Resource` 本身基于引用计数，场景卸载时未被引用的资源自动释放。对于手动预加载的资源，切换场景时显式 `queue_free()` 对应节点以触发释放。

#### D. 特效管理 (`VFXManager`)

`VFXManager` 是 Autoload 单例，所有视觉特效（命中闪光、爆炸、DoT 气泡等）必须通过此管理器播放，**禁止在逻辑层直接操作 Node**。

```gdscript
# vfx_manager.gd (Autoload)
# 职责：接收逻辑事件并以数据驱动方式触发对应特效，逻辑层与表现层完全解耦

const MAX_ACTIVE_VFX: int = 200   # 同屏最大活跃特效数量上限
var _vfx_pool: Dictionary = {}    # { "effect_id": Array[GPUParticles2D] } — 按类型分池
# VFX 场景预加载表；_ready() 中按配置填充，play() 通过此表实例化节点
# 例: _vfx_scenes["hit_spark"] = preload("res://scenes/vfx/hit_spark.tscn")
var _vfx_scenes: Dictionary = {}  # { "effect_id": String -> PackedScene }
# 维护活跃特效计数器（O(1) 计数，不在 play() 中遍历 pool 统计）
var _active_count: int = 0        # 当前正在 emitting 的特效节点总数（O(1) 计数，避免遍历 pool 统计）

# EventBus 订阅列表（在 _ready() 中注册）：
# EventID.BULLET_HIT      → play("hit_spark",   hit_position)
# EventID.ENEMY_KILLED    → play("death_burst",  enemy_position)
# EventID.STATUS_APPLIED  → play("status_" + status_name, target_position)
# EventID.SPELL_CAST_BEGIN→ play("cast_flash",   caster_position)

func play(effect_id: String, world_pos: Vector2, override_scale: float = 1.0) -> void:
    if _active_count >= MAX_ACTIVE_VFX:  # O(1) 检查，达上限时静默丢弃
        return
    var node := _pool_pop(effect_id)
    node.position = world_pos
    node.scale = Vector2.ONE * override_scale
    node.emitting = true
    _active_count += 1
    node.finished.connect(_pool_return.bind(effect_id, node), CONNECT_ONE_SHOT)

func _pool_pop(effect_id: String) -> GPUParticles2D:
    if not _vfx_pool.has(effect_id) or _vfx_pool[effect_id].is_empty():
        return _instantiate_vfx(effect_id)  # 按需实例化并加入场景树
    return _vfx_pool[effect_id].pop_back()

func _pool_return(effect_id: String, node: GPUParticles2D) -> void:
    node.emitting = false
    _active_count -= 1  # CONNECT_ONE_SHOT 保证每个节点只调用一次
    # 首次归还时 _vfx_pool 中可能尚无此 effect_id 键，需先初始化空列表再 append
    if not _vfx_pool.has(effect_id):
        _vfx_pool[effect_id] = []
    _vfx_pool[effect_id].append(node)

# _pool_pop() 中对应 effect_id 的池为空时，按需创建新 GPUParticles2D 节点。
# ⚠️ node.one_shot 必须为 true：若为 false，GPUParticles2D 持续循环发射，
#   finished 信号永不触发，_pool_return 不被调用，_active_count 只增不减，
#   触达 MAX_ACTIVE_VFX 后所有后续特效全部被静默丢弃（完全失效）。
# 父节点：VFXManager 自身（Autoload 单例），跨场景持久存活，确保池化节点复用。
func _instantiate_vfx(effect_id: String) -> GPUParticles2D:
    if not _vfx_scenes.has(effect_id):
        # 未注册的 effect_id：返回空占位节点（不崩溃），开发期通过 push_warning 提示漏配
        push_warning("VFXManager: 未知特效 ID='%s'，请检查 _ready() 中的预加载配置" % effect_id)
        var placeholder := GPUParticles2D.new()
        placeholder.one_shot = true   # 占位节点同样需要 one_shot，确保 finished 可触发
        add_child(placeholder)
        return placeholder
    var node: GPUParticles2D = _vfx_scenes[effect_id].instantiate()
    node.one_shot = true      # 必须为 true，否则 finished 永不触发，池化失效
    node.emitting = false     # 初始不发射，等待 play() 设置 position/scale 后再启动
    add_child(node)           # 挂载到 VFXManager（Autoload）节点下，跨场景持久存活
    return node
```

> **性能约束（V-N1）**：`MAX_ACTIVE_VFX = 200` 超出时静默丢弃，避免大量爆炸帧暴涨。
> 伤害数字（DamageNumber）由 `UIManager` 而非 `VFXManager` 管理，两者隔离（参见 `architecture_design.md §4.4` Throttling）。

#### E. 元数据管理 (`ProfileManager`)
*   **Save/Load**: 使用 Godot 的 `FileAccess` 读写 JSON 字符串，或使用 `ConfigFile` 存储键值对数据，存储路径为 `user://save_data.json`。
*   **Schema**: 定义 `SaveData` 字典结构，包含 `unlocked_spells: Array[String]`、`achievements: Array[int]` 等字段。
*   **版本字段**: `SaveData` 根层必须包含 `schema_version: int`（当前版本 = 1）。
*   **加载时版本检查**:
    1.  读取 `schema_version`，若字段不存在则视为 `v0`。
    2.  对每个低版本执行迁移函数（`_migrate_v0_to_v1(data)`），补全缺失字段为默认值。
    3.  若 `schema_version > 当前版本`（由更新版本写入），提示版本不匹配并回退到初始状态，避免崩溃。
*   **参考**: `docs/design/core_wand_design.md` 中的 SaveData JSON 序列化示例。

#### E.1 存档损坏 UX 规范（C-GAP-3 修复）

`load_run()` 和 `EndlessRecordsManager.load()` **不得静默降级**——返回空数据时必须通过 UI 告知玩家，禁止无声失败。

| 失败场景 | 触发条件 | UI 行为 |
| :--- | :--- | :--- |
| `load_run()` 解析失败 | JSON 格式错误 / `schema_version` 缺失 / 两槽均损坏 | `UIManager.show_data_corrupted_dialog("run")` → 对话框：「检测到存档异常，当前游戏进度无法读取。是否开始新游戏？」；确认后清除 run 文件并进入主菜单新游戏流程 |
| `EndlessRecordsManager.load()` 签名失败 | HMAC 不匹配（文件被篡改或损坏） | `UIManager.show_data_corrupted_dialog("leaderboard")` → Toast 提示：「排行榜分数验证失败，本地记录已重置」；不影响游戏进程，直接以空记录继续 |
| `load_run()` 返回 `{}` 但存档文件存在 | 两槽均损坏 | 同 run 对话框，额外追加一条 `crash_log.txt` 记录，便于复现调试 |

```gdscript
# profile_manager.gd — load_run() 调用方规范（游戏启动时）
var run_data := load_run()
if run_data.is_empty() and (
        FileAccess.file_exists(_SLOT_A) or FileAccess.file_exists(_SLOT_B)):
    # 文件存在但解析为空 → 损坏，不静默降级
    UIManager.show_data_corrupted_dialog("run")
    return  # 由对话框回调决定后续流程（新游戏 or 退出）
```

> **`UIManager.show_data_corrupted_dialog(type: String)` 接口规范**：  
> - `type = "run"`：模态对话框，两个按钮：「开始新游戏」（清除损坏 Run 文件）/ 「返回主菜单」。  
> - `type = "leaderboard"`：非模态 Toast（3 秒自动消失），不阻断游戏流程。  
> - 对话框文案须通过 `tr()` 包裹（L10n 支持）：键名 `"DIALOG_SAVE_CORRUPTED_RUN"` / `"TOAST_LEADERBOARD_RESET"`。


> `game_design.md §8.1` 要求死亡时自动截图保存构建快照。实现规范如下：
>
> **DPS 计算**：`CombatManager`（或 `ProfileManager`）维护滚动窗口：
> ```gdscript
> # 环形缓冲区：O(1) 写入/覆盖，无内存分配，零 GC 压力（替代 Array + pop_front() 的 O(N) 方案）
> # _recalc_window() 懒加载：仅在 get_dps() 查询时计算（不在每次 record_damage() 触发）
> # 理由：record_damage() 每帧可能被数百次 AoE 命中调用；UIManager 仅每 0.5 秒轮询 DPS
> const DPS_WINDOW_SEC: float = 3.0
> const _RB_SIZE: int = 256                      # 环形缓冲区槽数（上限：3秒内最多 256 次伤害事件）
> var _rb_time: PackedFloat64Array               # 各槽时间戳
> var _rb_dmg:  PackedFloat32Array               # 各槽伤害值
> var _rb_head: int = 0                          # 下一次写入位置（覆盖最旧记录）
> var _rb_count: int = 0                         # 有效记录数（最大 = _RB_SIZE）
> var _accumulated_dmg: float = 0.0             # 当前窗口内伤害累计（主动维护，O(1) 读取）
>
> func _ready() -> void:
>     _rb_time = PackedFloat64Array(); _rb_time.resize(_RB_SIZE)
>     _rb_dmg  = PackedFloat32Array(); _rb_dmg.resize(_RB_SIZE)
>
> func record_damage(amount: float) -> void:
>     var now := Time.get_ticks_msec() / 1000.0
>     _rb_time[_rb_head] = now
>     _rb_dmg[_rb_head]  = amount
>     _rb_head = (_rb_head + 1) % _RB_SIZE
>     if _rb_count < _RB_SIZE:
>         _rb_count += 1
>     _accumulated_dmg += amount   # 乐观累加；get_dps() 时统一裁剪过期值
>
> func _recalc_window(now: float) -> void:
>     var sum: float = 0.0
>     var tail := (_rb_head - _rb_count + _RB_SIZE) % _RB_SIZE
>     var valid: int = 0
>     for k in _rb_count:
>         var idx := (tail + k) % _RB_SIZE
>         if (now - _rb_time[idx]) <= DPS_WINDOW_SEC:
>             sum += _rb_dmg[idx]
>             valid += 1
>     _accumulated_dmg = sum
>     _rb_count = valid
>
> func get_dps() -> float:
>     _recalc_window(Time.get_ticks_msec() / 1000.0)  # 懒加载裁剪
>     return _accumulated_dmg / DPS_WINDOW_SEC   # 平均 DPS（过去 3 秒）
> ```
> `UIManager` 每 0.5 秒轮询 `CombatManager.get_dps()`，更新 HUD DPS 标签；靶场模式下同步更新 DPS 面板。
>
> **Run 截图**：死亡时 `GameCycleManager` 调用：
> ```gdscript
> func _save_run_screenshot() -> void:
>     var img: Image = get_viewport().get_texture().get_image()
>     var path := "user://runs/%s_run_%d.png" % [
>         Time.get_datetime_string_from_system().substr(0, 10),
>         ProfileManager.get_run_count()
>     ]
>     img.save_png(path)
> ```
> 截图在主线程调用（`get_image()` 是同步操作），建议在死亡动画第 1 帧完成后、统计屏显示前执行，
> 避免截到黑屏。

## 3. 开发阶段规划 (Development Stages)

### Phase 1: 核心验证 (The Engine)
*   [x] 定义 `SpellNode` 基类 (已完成)。
*   [ ] 实现 `SpellEvaluator` (纯逻辑，无 UI)。
*   [ ] 实现 `SpatialGrid` 碰撞检测。
*   [ ] 编写单元测试：构建一个简单的"散弹枪"逻辑，验证输出数据是否符合预期。

### Phase 2: 视觉化 (The Visuals)
*   [ ] 搭建 Godot 场景，实现玩家移动 (键盘/手柄)。
*   [ ] 接入 `BulletManager`，将逻辑坐标同步到 Sprite2D。
*   [ ] 实现简单的敌人 AI (追着玩家跑)。

### Phase 3: 构建系统 (The Builder)
*   [ ] 实现各种具体的 `SpellNode` (Actions, Modifiers)。
*   [ ] UI 开发：背包拖拽系统。
*   [ ] 存档与解析系统 (JSON <-> SpellDeck)，含 Schema 版本字段。

#### SpellDeck JSON 序列化格式 (E2 权威格式)

```json
{
  "schema_version": 1,
  "core_id": "linear_core_t2",
  "slots": [
    { "spell_id": "modifier_damage_plus", "position": 0 },
    { "spell_id": "action_spark_bolt",    "position": 1 },
    { "spell_id": "trigger_on_hit",       "position": 2 },
    { "spell_id": "action_chain_bolt",    "position": 3 }
  ]
}
```
*   `core_id`：核心 ID，决定插槽拓扑结构。
*   `slots` 按 `position` 排列，`position` 为核心插槽座标（线性核心就是序数，网格核心为 `{x, y}` 对）。
*   `spell_id` 对应 `SpellRegistry` 中的全局唯一 ID。

### Phase 4: 循环与内容 (The Game)
*   [ ] 商店逻辑。
*   [ ] 波次管理器。
*   [ ] 数值接入。
*   [ ] ZoneManager（地面效果系统）。
*   [ ] VFXManager 特效池。
*   [ ] Endless 排行榜本地存储。

---

## 4. 关键技术难点预案

### Q1: GDScript 如何避免 GC 抖动？
*   **预案**: 所有的 `ProjectilePayload`、`SpellContext` 在游戏启动时预分配并放入 `Array` 池。使用时 `pool.pop_back()` 取出，用完调用 `reset()` 后 `pool.append()` 归还，不依赖 GDScript 的自动引用计数销毁。

### Q2: 复杂的法术链如何调试？
*   **预案**: 开发一个 Godot 编辑器插件（`EditorPlugin`）作为可视化的 **"Debug Graph"** 工具。在编辑器模式下，可以单步执行 `SpellEvaluator`，看到当前的 Stack 和 Deck 状态，并在 2D 视图中高亮对应节点。

### Q3: 物理碰撞性能不够怎么办？
*   **预案**: 
    1. 确保 `CollisionShape2D` 使用圆形（最快），并合理配置 Physics Layer/Mask 减少检测对数。
    2. 将碰撞检测分帧（Time-Slicing），这一帧算一半子弹，下一帧算另一半。对于高速割草游戏，延迟一帧通常不可感知。
    3. 终极方案：完全放弃 Area2D，改用自定义 `SpatialGrid`，在 `_physics_process` 中手动执行圆形重叠测试。

### Q4: `PackedFloat32Array` 删除策略？
*   **问题**：直接调用 `PackedFloat32Array.resize()` 删除元素是 O(n)，对 2000+ 弹幕每帧有明显性能开销。
*   **预案：末位交换 (Swap-and-Pop)**：
    *   子弹 “死亡” 时，将数组最后一个元素的数据复制到当前位置，然后缩减数组长度 1 个 stride。
    *   复杂度 O(1)，但子弹顺序不再保证（对融剆这个游戏类型无影响）。
    *   **实际实现**：`BulletManager` 内部维护 `_active_count: int`，子弹数据帮存在 `[0, _active_count)` 区间内，不依赖 resize()。

### Q5: GDScript 与 C# 如何协同工作？
*   **热路径 C# 文件目录**：`scripts/core_csharp/BulletManagerCore.cs`、`SpellEvaluatorCore.cs`。
*   **调用方式**：在 Godot 4 中，GDScript 可通过 `var evaluator = preload("res://scripts/SpellEvaluatorCore.cs").new()` 直接实例化 C# 类，调用公开方法无需特殊处理。
*   **跨语言传递类型**：只传递 GDScript / C# 双方都支持的类型：`int`、`float`、`Vector2`、`Godot.Array`、`Godot.Dictionary`。禁止将 GDScript `RefCounted` 自定义类型直接传入 C#：应将复杂数据序列化为 `PackedFloat32Array` 或 `int` ID 后传递。
*   **原则**：只有当 Profiler 显示具体函数是确认瓶颈时，才将其迁移到 C#；默认先用 GDScript 实现，确保选择的正确性。