# 模块化战术土豆 (Modular Tactical Potato) - 架构设计文档
## 1. 概述 (Overview)
本项目旨在开发一款基于 **Godot 4.x** 的 Roguelite 动作射击游戏。
核心体验结合了 **Brotato (土豆兄弟)** 的快节奏割草体验与 **Noita** 的深度法术构建系统。
架构设计的首要目标是 **高性能**（支持同屏大量单位与弹幕）与 **极高的可扩展性**（特别是武器系统的模块化）。
### 1.1 设计目标
1. **超模块化武器系统 (Hyper-Modular Weapon System)**：超越 Noita 的线性构建，引入更灵活的管道流与事件钩子机制。
2. **高性能战斗引擎**：支持同屏 500+ 敌人，2000+ 弹幕，60FPS 稳定运行。
3. **数据驱动 (Data-Driven)**：所有游戏内容（法术、属性、波次）完全配表化/JSON化。
---
## 2. 系统分层架构 (Layered Architecture)
采用能够严格分离数据与表现的架构模式。虽然 Godot 是节点/组件式的，但在核心战斗层我们将采用 **Manager + Data** 的方式来规避逐节点更新带来的开销。
```mermaid
graph TD
Layer1[表现层 (Presentation Layer)] --> Layer2[逻辑层 (Domain/Logic Layer)]
Layer2 --> Layer3[数据层 (Data Layer)]
Layer2 --> Layer4[核心库 (Core Library)]
subgraph Layer1
ViewComponents[Godot Nodes (Sprite2D, AnimationPlayer)]
UIManagers[UI System (Control/CanvasLayer)]
Effects[VFXManager + GPUParticles2D Pool]
end
subgraph Layer2
CombatMgr[Combat Manager (Main Loop)]
SpellEvaluator[Spell Interpreter (The "CPU")]
EnemyAI[Boid AI System]
GameCycle[Wave & Shop Cycle]
MinionMgr[MinionManager (友军召唤)]
ZoneMgr[ZoneManager (地面效果)]
StatusMgr[StatusManager (状态效果)]
end
subgraph Layer3
ConfigMgr[JSON Config Loader]
SaveSystem[Persistent Storage]
Inventory[Player State & Inventory]
end
subgraph Layer4
Pool[Object Pool System]
SpatialHash[Spatial Hashing (Collision)]
EventSystem[Global Event Bus]
CoreFeatureTagConst[CoreFeatureTag (特性常量)]
end
```
> **⚠️ 实现现状 (2026-07-20 审计)**：数据层实际为**纯 `data/*.json`**（7 个文件：spells / cores / enemies / waves / resonance / status_effects / balance），各 Manager 自行 `FileAccess` 直读；全项目**零 `.tres` 数据资源**（仅 `assets/ui/ui_theme.tres`），无 `resources/` 目录。图中 `ConfigMgr` autoload 虽已注册（`project.godot`），但**从未被任何调用方引用，是死代码**。文中后续所有 `res://resources/**/*.tres` 路径均为设计蓝图，与实际 `data/*.json` 布局不符。详见 [`docs_dev/doc_code_audit_2026-07-20.md`](../../docs_dev/doc_code_audit_2026-07-20.md)。
---
## 3. 核心子系统：超模块化法术系统 (HMWS)
这是本项目的技术核心。我们将 Noita 的“魔杖”概念抽象为 **“法术管道 (Spell Pipeline)”**。
### 3.1 核心概念差异
| 特性 | Noita 原版 | HMWS (本项目) | 改进目的 |
| :--- | :--- | :--- | :--- |
| **执行流** | 线性 (Deck -> Hand -> Discard) | **树状/图状结构 + 事件驱动** | 支持“子母弹”、“条件触发”、“击中后分裂逻辑”的无限嵌套。 |
| **属性计算** | 累加式 (Cast Delay += 0.1) | **管线式 (Pipeline)** | 允许中间件对属性进行乘算、覆写或逻辑重定向。 |
| **载体** | 法杖 (Wand) | **构建核心 (Core)** | 核心决定了插槽拓扑结构（不仅仅是线性数组，可能是矩阵或特定触发槽）。 |
### 3.2 数据结构设计 (GDScript)
#### A. 基础单元 (SpellNode)
这是所有"部件"的基类。
> **⚠️ 本块与实现存在既有漂移（2026-07-30 部分订正）**：`pierce_add` / `bounce_add` / `homing_add` 三项已按 `scripts/domain/spell_system/cast_stats.gd` 实测订正（原写 `pierce_count` / `bounce_count` / `homing_force`）。**其余字段仍未核对**：实现里没有 `projectile_speed` / `spread_angle` / `projectile_size` / `range_mult`，实际为 `spread_count` / `speed_mult` / `radius_mult` / `lifetime` / `multicast_count`。此漂移早于本次归航改动，未一并订正以免超出改动范围 —— **以 `cast_stats.gd` 为准**。
```gdscript
# cast_stats.gd - MODIFIER 节点的修改目标；通过 SpellContext.stats 访问
class_name CastStats
extends RefCounted
var damage_add: float = 0.0 # 累加伤害加成（所有 Dmg+ 修正器的总和）
var damage_mult: float = 1.0 # 乘算伤害系数（暴击、元素弱点等乘入）
var projectile_speed: float = 600.0 # 弹道飞行速度（像素/秒）
var spread_angle: float = 0.0 # 散射角度（度，0 = 直线）
var pierce_add: int = 0 # MODIFIER 累加的穿透次数（叠加到 ACTION 自带 pierce）
var bounce_add: int = 0 # MODIFIER 累加的弹跳次数（叠加到 ACTION 自带 bounce）
var homing_add: float = 0.0 # MODIFIER 累加的归航【最大转向角速度】，单位 弧度/秒
# （叠加到 ACTION 自带 homing；语义见 §4.2 Homing 受限角速度制导）
var projectile_size: float = 1.0 # 弹道大小系数（影响碰撞半径与贴图缩放）
var range_mult: float = 1.0 # 射程乘算系数（弹道消失前飞行距离倍率）
var crit_chance: float = 0.0 # 本次施法暴击率追加量（0.0~1.0，叠加而非覆盖）
func reset() -> void:
damage_add = 0.0; damage_mult = 1.0; projectile_speed = 600.0
spread_angle = 0.0; pierce_add = 0; bounce_add = 0
homing_add = 0.0; projectile_size = 1.0; range_mult = 1.0; crit_chance = 0.0
# spell_context.gd - 使用 RefCounted 避免 GC 压力
class_name SpellContext
extends RefCounted
# ⚠️ 注意：禁止持有 Node2D 引用——逻辑层与表现层必须解耦
# 施法者位置通过 EntityManager.get_position(caster_id) 实时查询
var caster_id: int = -1 # 施法者实体 ID
var target: Vector2 # 目标点
var stats: CastStats = CastStats.new() # 必须在声明时初始化；reset() 调用 stats.reset() 清零字段，不重新 new
var payloads: Array[ProjectileDef] = [] # 待发射的弹头定义队列
var registers: PackedFloat32Array = PackedFloat32Array([0.0, 0.0, 0.0, 0.0])
# R1, R2, R3, R4 — LOGIC_P2 功能专用
# ⚠️ 必须声明时初始化为长度 4；PackedFloat32Array() 默认长度 0，
# 直接访问 registers[0] 会触发 out-of-bounds 崩溃。
# 生命周期：携带 CoreFeatureTag.PERSISTENT_MEMORY 的 Core 跨帧保留此值；
# 非持久 Core 下，帧结束后由 SpellEvaluator 调用 registers.fill(0.0) 清零。
# 与 CastState.registers 的区别：
# SpellContext.registers → 跨帧持久寄存器（属于 SpellContext 对象）
# CastState.registers → 单次 execute() 内临时工作寄存器，每次重置
# core_wand_design.md §6 将此字段称为 "memory_bank"（同一字段）
var current_payload: ProjectileDef # 当前正在构建的弹头定义
# 池化归还时必须调用 reset()，防止脏数据污染下次施法
func reset() -> void:
caster_id = -1
target = Vector2.ZERO
stats.reset() # CastStats 内部清零
payloads.clear() # 清空弹头队列（不销毁元素，由 ProjectileDef 池负责回收）
current_payload = null
# ⚠️ registers 不在此处清零：
# 持久 Core（PERSISTENT_MEMORY）由 SpellEvaluator 决定是否保留；
# 非持久 Core 由 SpellEvaluator 在帧结束后调用 registers.fill(0.0)。
# spell_node.gd - 基类，子类重写 execute()
# 所有系统通过 SpellType 枚举访问节点类型，禁止在业务代码中直接写裸整数（0/1/2/3）。
enum SpellType {
ACTION = 0, # 产生实际飞行物或即时效果（如 spark_bolt、nuke）
MODIFIER = 1, # 修改下一个 ACTION 的属性（如 damage_plus、homing）
TRIGGER = 2, # 将后续法术打包为 SubPayload，在弹体命中时执行（子母弹核心）
LOGIC = 3, # 条件跳转、循环、寄存器读写（IF_HP_LOW、LOOP 等）
SCOPE_CLOSE = 4 # 虚节点，预编译时自动插入，标记 TRIGGER/LOGIC 作用域边界
# 不出现在 SpellRegistry 中，玩家不可购买
}
class_name SpellNode
extends RefCounted
var id: String
var type: SpellType = SpellType.ACTION # 业务代码赋值时须使用 SpellType.XXX，禁止写裸整数
var element_tags: Array[String] = [] # 元素亲和性标签，供共鸣系统（§3.4.C Resonance）进行模式匹配
# 内容示例：["tag:water"]、["tag:lightning"]、[]
# resonance_recipes.json 中 "pattern" 字段的每个元素
# 对应本字段中的一个字符串；预编译时 _check_resonance()
# 遍历 deck.nodes，比对 element_tags 中是否包含目标 tag
# 数据来源：SpellRegistry 从 res://resources/spells/*.tres 加载
var shape_icon: String = "" # ADR-C1: 无障碍形状标识，与颜色配合供色盲玩家区分元素。
# 取值约定（UIAtlas 中对应图标键）：
# "triangle" → 火系 (Fire)
# "diamond" → 冰系 (Ice)
# "circle" → 水系 (Water)
# "square" → 土系 (Earth)
# "star" → 雷系 (Lightning)
# "cross" → 暗系 (Dark)
# "" → 无元素（纯伤害类）
# 渲染规则：UI 显示元素标签时必须同时绘制颜色背景 + shape_icon；
# VFXManager 在命中 VFX 上叠加 1.5× 字号的 shape_icon TextureRect。
# 禁止仅用颜色区分元素（ADR-C1 强制要求）。
# 核心执行函数：修改 Context 或产生行为，子类必须重写
func execute(ctx: SpellContext, deck: SpellDeck) -> void:
pass
# projectile_def.gd - ACTION 节点执行时填充，最终传给 BulletManager 批量生成弹体
# 通过对象池复用，不触发 GC；SpellContext.payloads 以 Array[ProjectileDef] 形式积累
class_name ProjectileDef
extends RefCounted
# 业务代码必须通过 DamageType.PHYSICAL 等常量引用，禁止直接写 0/1/2/3/4。
# 此枚举也是 BulletManager SoA 中 damage_type 字段、StatusManager DoT 分类的统一来源。
enum DamageType {
PHYSICAL = 0, # 物理伤害：受护甲（Armor）平铺减免，不受元素抗性影响
FIRE = 1, # 火焰伤害：受 attunement_fire 加成；可触发点燃/爆燃状态
ICE = 2, # 冰霜伤害：受 attunement_ice 加成；可触发冻结/减速状态
LIGHTNING = 3, # 雷电伤害：受 attunement_lightning 加成；可触发麻痹/连锁导电
POISON = 4 # 毒素伤害：受 attunement_poison 加成；施加 DoT，叠层上限受精通影响
}
# ─────────────────────────────────────────────────────────────────────────────
# ── 伤害 ──────────────────────────────────────────────────
var base_damage: float = 5.0 # 计算前基础伤害值（已含 CastStats.damage_add 累积）
var damage_mult: float = 1.0 # 乘算系数（暴击/元素弱点已合入）
var damage_type: int = DamageType.PHYSICAL # DamageType 枚举（见上方定义）
# ── 运动 ──────────────────────────────────────────────────
var speed: float = 600.0 # 初速度（像素/秒）
var direction: Vector2 = Vector2.RIGHT
var spread_angle_rad: float = 0.0 # 在 direction 基础上的随机偏转幅度
# 注：归航【不】经 ProjectileDef 传递。`projectile_def.gd` 无任何 homing 字段 ——
# SpellEvaluator._push_projectile 直接把 homing_strength / homing_range /
# homing_target_id 写进 BulletManager 的冷数据字典（详见 §4.2）。
# 原此处的 `homing_force`（「每帧转向力」）语义与实现均不存在，2026-07-30 删除。
var acceleration: float = 0.0 # 速度加速度（可为负，做减速球）
# ── 生命周期 ──────────────────────────────────────────────
var lifetime: float = 3.0 # 最大存活时间（秒）
var pierce_remaining: int = 0 # 剩余穿透次数（0 = 首次命中销毁）
var bounce_remaining: int = 0 # 剩余弹射次数
# ── 碰撞体积 ──────────────────────────────────────────────
var radius: float = 6.0 # 碰撞圆半径（像素）
var size_mult: float = 1.0 # 外观与碰撞同步缩放系数
# ── 触发器 ────────────────────────────────────────────────
var on_hit_payload_id: int = -1 # SubPayloadRegistry ID；-1 = 无 TRIGGER
var on_expire_payload_id: int = -1 # 到期/撞墙触发；-1 = 无
var on_kill_payload_id: int = -1 # 击杀触发；-1 = 无
# ── 归属 ──────────────────────────────────────────────────
var owner_id: int = -1 # 根源实体 ID（归击杀、吸血计算）
var source_tags: int = 0 # 位掩码: PRIMARY=1, TRIGGERED=2, SUMMON=4, REFLECTED=8
var spawn_position: Vector2 # 发射原点（填充时从 caster 位置获取）
# ── 触发系数 ───────────────────────────────────────────────
var proc_rate: float = 1.0 # Proc 系数（0.0~1.0）。高频攻击（加特林）应设置为 0.1~0.3，
# 防止高攻速过度触发 on_hit 特效/技能。
# 命中时实际触发概率 = SpellNode.proc_chance × proc_rate。
# 默认 1.0（不削减），Tier 1 Action 通常无需修改。
func reset() -> void:
base_damage = 5.0; damage_mult = 1.0; damage_type = DamageType.PHYSICAL
speed = 600.0; direction = Vector2.RIGHT; spread_angle_rad = 0.0
acceleration = 0.0; lifetime = 3.0
pierce_remaining = 0; bounce_remaining = 0
radius = 6.0; size_mult = 1.0
on_hit_payload_id = -1; on_expire_payload_id = -1; on_kill_payload_id = -1
owner_id = -1; source_tags = 0; proc_rate = 1.0
spawn_position = Vector2.ZERO # 必须重置，否则池化复用时携带上帧发射原点
```
#### B. 法术解析器 (The Evaluator)
为了高性能，解析器必须 **低 GC 压力 (Low-GC)**。在施法计算帧，尽量避免分配新对象。
* 使用预分配的 `SpellContext` 对象池（`Array` 作为栈管理空闲对象）。
* 使用 `Array`（作为栈）模拟递归，防止深层递归爆栈。
#### C. 高级特性：动态插槽与逻辑门
* **Logic Spells (逻辑法术)**：引入 `IfHPBelow`, `OnKillAction`, `EveryNbShot` 等逻辑块，让玩家实现“如果血量低于30%，则发射吸血导弹”的构建。
* **Variable Storage (变量存储)**：允许法术在法杖上写入/读取临时变量（例如：记录连击数）。
### 3.3 扩展性设计
所有法术行为通过 **Strategy Pattern (策略模式)** 实现。
新增一个法术只需：
1. 在 JSON（或 Godot `.tres` Resource）中定义 ID 和贴图路径。
2. 实现一个继承自 `SpellNode` 的 GDScript 类。
3. 在注册表中注册。
### 3.4 进阶构建机制 (Advanced Mechanics) - 玩法增强
为了超越“线性堆砌”的枯燥感，架构支持以下三种深度玩法机制。
> **MVP 功能边界说明**：
> - **P0（必须实现）**：4类 SpellNode（ACTION / MODIFIER / TRIGGER / LOGIC）+ LINEAR Core。
> - **P1（迭代加入）**：拓扑插槽系统（MATRIX/CIRCUIT Core）、共鸣系统。
> - **P2（可选高级内容）**：状态寄存器 + 条件跳转——此功能面向极硬核玩家，仅通过特殊 Core 解锁，**不在新手 UI 中暴露**。
#### A. 拓扑插槽系统 (Topology Slots)【P1】
核心（Core）不再仅仅是一个列表，它可以是一个 **2D 网格** 或 **电路板**。
* **adjacency_bonus (邻接加成)**：某些插槽有物理连接。例如，将 [火元素] 放在 [高压槽] 旁边，会自动获得 +20% 范围。
* **Circuit Logic (电路逻辑)**：法术流不再只是从左到右。核心板可以有分叉路口，玩家需要用 [分流器法术] 将能量流引导到不同的分支。
* 详见 [docs/design/core_wand_design.md](../design/core_wand_design.md)。
**拓扑适配层 (Topology Adapter)【A1 解决方案】**
`SpellEvaluator` 的 while 循环只能处理线性指令流。为此，在 `SpellEvaluator.compile_wand(core, raw_deck)` 预编译阶段引入 **拓扑扁平化 (Topology Flattening)**，将不同 Core 的空间拓扑提前转换为线性指令序列，运行时 while 循环无需感知拓扑：
> **⚠️ 实现现状 (2026-07-20 审计)**：真实签名与本节伪代码不同：
> - `compile_wand(core, raw_nodes: Array)` —— 第 2 参是 `Array` 而非 `SpellDeck`（`spell_evaluator.gd:36`）。
> - `execute_compiled(compiled, caster_id: int, spawn_pos: Vector2)` —— 执行期不传 `ctx`/`core`，`feature_tags` 从 `CompiledDeck` 编译期快照读取（`spell_evaluator.gd:321`）。
> 详见 [`docs_dev/doc_code_audit_2026-07-20.md`](../../docs_dev/doc_code_audit_2026-07-20.md)。
| Core 类型 | 扁平化策略 |
| :--- | :--- |
| **LINEAR** | 无需处理，直接输出原始 SpellNode 序列 |
| **MATRIX_2X4** | 扫描邻接槽对（slot[i] 与 slot[i + cols]），若满足 `adjacency_bonus` 条件，在对应 ACTION 前插入隐式 MODIFIER 节点；最终序列仍按行→列顺序线性排列 |
| **CIRCUIT** | 对有向图做 **拓扑排序**，每个分叉点展开为独立 SubPayload 并注册到 SubPayloadRegistry，分叉处插入 `LOGIC_FORK` 指令批量触发；主链保持线性 |
```gdscript
# spell_evaluator.gd（预编译入口 + 运行时配置）
# compile_wand：拓扑扁平化策略入口，仅在玩家关闭背包/装备 Core 时调用，非热路径。
var _max_ops: int = 40 # 每次施法的法术节点执行上限（= MAX_OPS_PER_CPU × cpu_limit）
func update_max_ops(cpu_limit: int) -> void:
# UpgradeSystem.apply_choice() 在被动词条变更 cpu_limit 后调用
# MAX_OPS_PER_CPU = 8（基准值，SpellEvaluator 常量）
const MAX_OPS_PER_CPU: int = 8
_max_ops = clamp(MAX_OPS_PER_CPU * cpu_limit, 8, 200)
# ⚠️ 实现现状(2026-07-20)：SpellEvaluator 从不调用本函数、从不读 cpu_limit；
# 实际硬编码 max_ops = MAX_OPS_PER_CPU * 5（代码常量为 40，本处写 8，文档内部亦不一致）。
# 结果：升级 CPU 词条对施法预算无效——本设计更优，代码待修。见审计报告 D 节。
func compile_wand(core: CoreDefinition, raw_deck: SpellDeck) -> CompiledDeck:
match core.topology:
CoreDefinition.LINEAR:
return CompiledDeck.new(raw_deck.nodes)
CoreDefinition.MATRIX_2X4:
return _flatten_matrix(raw_deck, core)
CoreDefinition.CIRCUIT:
return _flatten_circuit(raw_deck, core)
return CompiledDeck.new([]) # 未知拓扑降级为空 Deck，防止 match 无 default 返回 null
func _flatten_matrix(deck: SpellDeck, core: CoreDefinition) -> CompiledDeck:
# 仅遍历 Row A（i < grid_cols）；Row B 槽位法术不作为独立执行节点，仅用于邻接加成注入。
var out: Array[SpellNode] = []
var row_a_count: int = core.grid_cols # Row A 的槽数 = grid_cols（如 2×4 矩阵中 = 4）
for i in row_a_count:
var adj_idx: int = i + core.grid_cols # Row B 中与 slot[i] 垂直对齐的槽索引
# 空槽守卫：deck.nodes[i] 可能为 null（槽为空）
var row_a_node: SpellNode = deck.nodes[i] if i < deck.nodes.size() else null
var row_b_node: SpellNode = deck.nodes[adj_idx] if adj_idx < deck.nodes.size() else null
if row_a_node == null:
continue # 空槽：Row A 无法触发，跳过（Row B 对应槽的邻接加成也无效）
if row_b_node != null and _has_adjacency_bonus(row_a_node, row_b_node):
# 注入隐式 MODIFIER 节点，效果见 core_wand_design.md §2.2 邻接加成效果表
out.append(_make_adjacency_mod(row_a_node, row_b_node))
out.append(row_a_node) # 仅追加 Row A 节点到执行序列
# Row B 节点（row_b_node）不追加 → 不独立执行，仅作为邻接加成来源
return CompiledDeck.new(out)
# 对 CIRCUIT 拓扑的有向图做 Kahn 算法拓扑排序，主链保持线性；
# 分叉节点展开为独立 SubPayload 并注册到 SubPayloadRegistry。
# edges 读自 core.edges（顶层字段）；CoreDefinition 须声明 @export var edges: Array = []（见 core_wand_design.md §1）
# 性能说明：仅在玩家关闭背包时触发（非 _physics_process 热路径），slot_count ≤ 16，O(V+E) < 0.1ms。
func _flatten_circuit(deck: SpellDeck, core: CoreDefinition) -> CompiledDeck:
# 1. 从 core.edges 读取顶层有向边列表；若为空，降级为 LINEAR 处理（见 core_wand_design.md §2.3）
var edges: Array = core.edges
if edges.is_empty():
push_warning("_flatten_circuit: core.edges 为空，降级为 LINEAR 处理（Core=%s）" % core.id)
return CompiledDeck.new(deck.nodes)
# 2. Kahn 算法：BFS 拓扑排序（保证无环时的确定性线性化顺序）
var in_degree: Array[int] = []
var adj: Array = [] # adj[i] = Array[int] 出边目标
in_degree.resize(core.slot_count)
adj.resize(core.slot_count)
for i in core.slot_count:
in_degree[i] = 0
adj[i] = []
for e in edges:
adj[e["from"]].append(e["to"])
in_degree[e["to"]] += 1
# ⚠️ Kahn 循环结束后 in_degree 全归零；_collect_branch_path() 需要原始入度来判断汇聚点
# （orig_in_degree[nxt] > 1 表示多入边）。在 Kahn 循环前保存副本供分支收集函数使用。
var orig_in_degree: Array[int] = in_degree.duplicate() # Kahn 前原始入度快照
var queue: Array[int] = []
for i in core.slot_count:
if in_degree[i] == 0:
queue.append(i)
var topo_order: Array[int] = []
while not queue.is_empty():
var cur: int = queue.pop_front()
topo_order.append(cur)
for nxt: int in adj[cur]:
in_degree[nxt] -= 1 # 修改工作副本（orig_in_degree 保留原始值供汇聚点检测）
if in_degree[nxt] == 0:
queue.append(nxt)
if topo_order.size() != core.slot_count:
push_error("_flatten_circuit: 检测到环路，无法线性化！Core=%s" % core.id)
return CompiledDeck.new([]) # 返回空 Deck，游戏不崩溃但该法杖无法施法
# 3. 按拓扑顺序输出节点，出度 > 1 的槽注入 LOGIC_FORK 指令
var out: Array[SpellNode] = []
# in_branch_payload 记录已纳入某 SubPayload 的槽索引，防止主链循环将分支节点重复追加执行
var in_branch_payload: Dictionary = {}
for slot_idx in topo_order:
# 跳过已被分支 SubPayload 收纳的节点，防止双重执行
if in_branch_payload.has(slot_idx):
continue
var node: SpellNode = deck.nodes[slot_idx] if slot_idx < deck.nodes.size() else null
if node == null:
continue # 空槽跳过
if adj[slot_idx].size() > 1:
# 分叉检测基于出度（出边数 > 1）；"splitter" tag 保留为 UI/编辑器标注用途，不参与执行判断
# 分叉槽自身的法术节点先行追加（分叉前执行，通常为空但允许 MODIFIER/ACTION）
out.append(node)
# 为每条出边收集完整分支路径（含多节点分支，_collect_branch_path 沿单出边延伸直到叶/汇聚点）
var branch_payload_ids: Array[int] = []
for neighbor_idx in adj[slot_idx]:
var branch_path: Array[SpellNode] = _collect_branch_path(
neighbor_idx, adj, orig_in_degree, deck, in_branch_payload)
# orig_in_degree：Kahn 前快照，确保汇聚点检测正确
# in_branch_payload：共享引用，函数内登记已访问槽，主链循环可跳过
if not branch_path.is_empty():
branch_payload_ids.append(SubPayloadRegistry.register(branch_path))
if not branch_payload_ids.is_empty():
var fork_node: SpellNode = SpellNode.new()
fork_node.type = SpellType.LOGIC
fork_node.id = "LOGIC_FORK"
fork_node.set_meta("fork_branch_ids", branch_payload_ids)
out.append(fork_node)
else:
out.append(node)
return CompiledDeck.new(out)
# 从 start_idx 沿单出边路径收集节点序列，直到：
# 叶节点（出度 0）、汇聚点（orig_in_degree > 1，属于主链或另一分支）、嵌套分叉（出度 > 1，递归处理）
# orig_in_degree：必须传 Kahn 前的原始入度副本，用于汇聚点判断
# in_branch_payload：共享字典，函数内每访问一个槽即写入，消除主链双重执行
func _collect_branch_path(start_idx: int, adj: Array, orig_in_degree: Array,
deck: SpellDeck,
in_branch_payload: Dictionary) -> Array[SpellNode]:
var path: Array[SpellNode] = []
var cur: int = start_idx
var visited: Dictionary = {}
while cur >= 0 and not visited.has(cur):
visited[cur] = true
in_branch_payload[cur] = true # 登记此槽已纳入 SubPayload，主链循环将跳过
if cur < deck.nodes.size() and deck.nodes[cur] != null:
path.append(deck.nodes[cur])
if adj[cur].size() > 1:
# 嵌套分叉：为每条子出边递归收集完整路径并注册 SubPayload，
# 然后将嵌套 LOGIC_FORK 节点插入当前 path。
var nested_branch_ids: Array[int] = []
for nxt_idx: int in adj[cur]:
var nested_path: Array[SpellNode] = _collect_branch_path(
nxt_idx, adj, orig_in_degree, deck, in_branch_payload)
if not nested_path.is_empty():
nested_branch_ids.append(SubPayloadRegistry.register(nested_path))
if not nested_branch_ids.is_empty():
var nested_fork: SpellNode = SpellNode.new()
nested_fork.type = SpellType.LOGIC
nested_fork.id = "LOGIC_FORK"
nested_fork.set_meta("fork_branch_ids", nested_branch_ids)
path.append(nested_fork)
break # 嵌套分叉后路径在各子 SubPayload 中独立延伸，本路径就此结束
elif adj[cur].size() == 1:
var nxt: int = adj[cur][0]
if orig_in_degree[nxt] <= 1: # 单入边，继续延伸
cur = nxt
else:
break # 汇聚点（多入边），停止；该节点由主链处理
else:
break # 叶节点（出度 0）
return path
```
> **E3 解决方案**：MATRIX 邻接加成通过 `_flatten_matrix` 在预编译阶段注入隐式 MODIFIER 节点，SpellEvaluator 运行时不感知 Core 拓扑，邻接触发与普通 MODIFIER 执行路径完全一致。
#### B. 状态寄存器与图灵完备 (State Registers & Turing Completeness)【P2 可选】
> ⚠️ **设计注意**：本功能仅通过特殊 Core（persistent_memory / circuit_fork）解锁，新手不会接触寄存器和跳转指令。
为了支持硬核玩家实现真正的“图灵完备”构建，架构预留对**状态存储**、**条件跳转** 和 **循环**的支持。
1. **Registers (寄存器)**:
* 在 `SpellContext` 中引入 `MemoryBank`，提供 4 个 Float 寄存器 (`R1`, `R2`, `R3`, `R4`)。
* 寄存器在同一帧内所有法术间共享，甚至可以跨帧持久化（如果法杖配置了 Persistent Memory 核心）。
2. **Instruction Set (指令集法术)**:
* **OPS**: `Add R1, 1` (加法), `Set R2, HP_Percent` (赋值).
* **JUMP**: `JumpIf R1 > 10, Label_A` (条件跳转到标签A).
* **LABEL**: `Label_A` (标记跳转点).
3. **Recursion Control (递归控制)**:
* 为了防止死循环 (`While(true)`), 解释器引入 `MaxOpLimit` (最大操作数限制，例如 100 ops/frame)。超过限制强制中断并在此帧失效。
4. **实战应用**:
* **计数器**: 每射击 3 次，第 4 次发射强力火球。
* **动态模式切换**: 根据敌人距离 (`R1 = EnemyDistance`)，如果近则跳转到 [霰弹逻辑]，如果远则跳转到 [狙击逻辑]。
#### C. 共鸣系统 (Resonance System)【P1】
在**预编译阶段 (Pre-compile Phase)** 进行模式匹配。
* 如果检测到 [水] 和 [电] 法术在执行链中紧邻，架构自动插入一个隐藏的 [导电反应] 中间件。
* 这允许设计隐藏配方（Hidden Recipes），鼓励玩家探索特定组合。
* **发现机制**：法术卡片上显示元素亲和性标签（如 ⚡ 雷、💧 水），引导玩家尝试组合，而非完全盲猜。
* **缓存失效**：玩家在商店修改法术顺序时，自动触发重新预编译，确保共鸣结果与当前 Deck 始终一致。
* **共鸣配方存储 (Recipe Schema)**：配方存储于 `res://resources/resonance_recipes.json`，结构如下：
```json
[
{
"id": "plasma_storm",
"pattern": ["tag:water", "tag:lightning"],
"match": "adjacent",
"result_spell_id": "plasma_storm",
"consume_inputs": true,
"vfx": "resonance_plasma"
}
]
```
- `match` 取值：`"adjacent"`（紧邻）/ `"anywhere_in_deck"`（Deck 内任意位置）。
- `consume_inputs: true` 表示触发后移除原两张法术，节省插槽。
- 新增配方只需编辑 JSON，无需修改 SpellEvaluator 代码。
**`_check_resonance()` 精确算法**：
"相邻"的定义：在预编译后的线性执行序列 `CompiledDeck.nodes` 中，两个法术节点的 **index 差 ≤ 2**（允许中间最多夹一个 MODIFIER 节点，因为 MODIFIER 不改变元素属性流向）。
```gdscript
# spell_evaluator.gd（在 compile_wand 完成拓扑扁平化之后调用）
func _check_resonance(compiled: CompiledDeck) -> CompiledDeck:
var recipes: Array = _resonance_recipes # 启动时从 JSON 加载，按 priority 排序（高优先级先匹配）
var nodes: Array[SpellNode] = compiled.nodes.duplicate()
var consumed: PackedByteArray = PackedByteArray()
consumed.resize(nodes.size()) # 全 0 初始化
# 先处理所有 adjacent 配方
for recipe in recipes.filter(func(r): return r.get("match") == "adjacent"):
var pattern: Array = recipe.get("pattern", []) # 如 ["tag:water", "tag:lightning"]
if pattern.size() < 2: continue
for i in nodes.size():
if consumed[i] != 0: continue
if not _node_has_tag(nodes[i], pattern[0]): continue
# 向右扫描 index i+1 至 i+2（跳过 MODIFIER），寻找 pattern[1]
for j in range(i + 1, min(i + 3, nodes.size())):
if consumed[j] != 0: continue
if nodes[j].type == SpellType.MODIFIER: continue # MODIFIER 不参与匹配，但不中断扫描
if _node_has_tag(nodes[j], pattern[1]):
# 命中：在 i 位置注入共鸣结果节点（替换 nodes[i] 位置），标记双方为已消费
var result_node: SpellNode = SpellRegistry.get(recipe.get("result_spell_id", ""))
if result_node == null: break
nodes.insert(i, result_node) # 在 i 位置插入共鸣结果
consumed.insert(i, 0) # 同步扩展 consumed 数组
if recipe.get("consume_inputs", false):
consumed[i + 1] = 1 # 原 pattern[0] 节点（现 i+1）标记为消费
consumed[j + 1] = 1 # 原 pattern[1] 节点（现 j+1）标记为消费
break # 每个 i 只匹配一次，防止多配方叠加在同一节点
else:
break # 遇到非 MODIFIER 非目标节点，中断内层扫描（不跨过 ACTION/TRIGGER）
# 再处理所有 anywhere_in_deck 配方（O(N²)，P1 仅限稀有度 ≥ 3 的传说配方）
for recipe in recipes.filter(func(r): return r.get("match") == "anywhere_in_deck"):
... # 类似逻辑，但 i、j 不需要相邻约束
return CompiledDeck.new(nodes, compiled.label_table, compiled.sub_payload_ids,
compiled.topology_type, compiled.checksum, consumed)
func _node_has_tag(node: SpellNode, tag_pattern: String) -> bool:
# tag_pattern 格式为 "tag:water"，匹配 node.element_tags 中含 "tag:water" 的节点
if tag_pattern.begins_with("tag:"):
return tag_pattern in node.element_tags
return node.id == tag_pattern # 直接 ID 匹配（精确配方，如 nuke+ignite）
```
> **⚠️ `consume_inputs` 运行时实现**：`CompiledDeck.nodes` 在预编译后为**只读**线性序列，
> 不可在运行时直接删除元素（会破坏共鸣检测缓存，影响其他帧的重编译判断）。
> `consume_inputs: true` 配方的运行时"移除"通过 **消费掩码（Consumed Mask）** 实现：
> ```gdscript
> # spell_deck.gd（运行时执行游标）
> # _consumed: PackedByteArray，长度 = nodes.size()，初始全 0
> # 预编译阶段在共鸣注入时，将被消费的槽位 index 写入 _consumed_indices 列表。
> # 运行时 pop() 跳过 _consumed[cursor] != 0 的槽位：
> func pop() -> SpellNode:
> while _cursor < _nodes.size() and _consumed[_cursor] != 0:
> _cursor += 1 # 跳过已消费槽位
> if _cursor >= _nodes.size():
> return null
> var node := _nodes[_cursor]
> _cursor += 1
> return node
> ```
> **消费掩码初始化**：`SpellEvaluator.compile_wand()` 完成共鸣注入后，对每个 `consume_inputs: true` 配方，
> 将参与配方的两个原始节点的 index 写入 `_consumed`（值为 1），同时在对应位置插入共鸣结果节点。
> `_consumed` 是 `SpellDeck`（运行时对象）的字段，`CompiledDeck`（只读预编译缓存）不含此字段，
> 每次从 CompiledDeck 构造 SpellDeck 时重新初始化（避免消费状态跨轮次残留）。
> **R4-C1 规范（触发范围权威定义）**：
> - `"adjacent"`：**标准触发范围**，绝大多数配方使用此选项（如"水+雷=等离子风暴"）。
> `game_design.md §3.3.C` 所述"执行链中直接相邻"即对应此选项。
> - `"anywhere_in_deck"`：**跨距触发**，仅用于极少数传说级全局共鸣配方，
> 预编译时对整个 CompiledDeck 做 O(N²) 全局扫描，且**自动标记为稀有以上配方**。
> 新增此类配方时需在 JSON 中追加 `"rarity": 3`（传说）以防止轻易触发。
> - 两者不冲突，同一配方文件中可同时存在不同 `match` 值的条目，SpellEvaluator 在预编译阶段
> 先处理所有 `adjacent` 配方，再统一处理 `anywhere_in_deck` 配方。
---
## 4. 高性能战斗架构 (High-Performance Combat Architecture)
为了实现“同屏 2000+ 弹幕”和“复杂逻辑构建”的双重目标，本架构采用 **Data-Oriented (面向数据)** 与 **Hybrid-ECS** 相结合的策略，最大化 CPU 缓存命中率并消除 GC 压力。
### 4.1 核心原则：低 GC (Low-GC Principle)
在核心战斗循环 (Game Loop) 中，尽量避免频繁实例化新对象。
* **Context Pooling**: `SpellContext` 等高频对象在关卡加载时预分配并放入 `Array` 池，使用时复用，用完调用 `reset()` 方法归还。
* **预分配大小**：`SPELL_CONTEXT_POOL_SIZE = 32`。依据：单帧最坏情况 ≈ MAX_BULLETS(2000) × 平均 proc_rate(0.05) × 命中概率(0.3) ≈ 30 次 execute_sub 并发触发，32 个实例可覆盖此场景且无 GC 分配。若 `pool.pop_back()` 返回 null（池耗尽），额外实例化 1 个并发出 `push_warning("SpellContextPool: exhausted")`，不崩溃。**⚠️ 溢出实例归还规范**：溢出实例使用完毕后须调用 `pool.push_back(ctx)` 归还；若归还时 `pool.size() >= SPELL_CONTEXT_POOL_SIZE`，直接丢弃（GC 处理权交还 Godot），不超量囤积。禁止遗弃，避免 Endless 模式长局游离实例积累导致 GC 压力持续上升。
* **Static Temporaries**: GDScript 可在模块顶层声明静态变量 (`static var _tmp_vec2: Vector2`)，避免向量计算产生中间对象。
* **PackedFloat32Array (SoA)**: 子弹的热数据（位置、速度）存储在 `PackedFloat32Array` 中，保证内存连续性，提升缓存命中率。
### 4.2 实体管理：ECS-Lite
虽然 Godot 是基于节点/组件的，但在海量单位管理上，我们将剥离节点的逐帧逻辑。
* **Manager-Based Logic**: 子弹和敌人的 `Node2D` 节点**不运行自身的 `_process`**，逻辑全部由中央 Manager（Autoload 单例）统一驱动。
* 也就是：`Node2D` 仅仅作为渲染容器，负责同步 `position` 和播放动画。
* **Centralized Loop (中央循环)**:
* `BulletManager` 维护一个紧凑的 `PackedFloat32Array`（SoA 布局）。
每颗子弹占用 **BULLET_STRIDE = 12** 个 float，在数组中偏移量 = `bullet_id × BULLET_STRIDE`：
| 偏移 | 字段 | 说明 |
| :--- | :--- | :--- |
| +0 | `x` | 世界坐标 X（像素） |
| +1 | `y` | 世界坐标 Y（像素） |
| +2 | `vx` | 速度 X（像素/秒） |
| +3 | `vy` | 速度 Y（像素/秒） |
| +4 | `lifetime` | 剩余存活时间（秒），归零时销毁 |
| +5 | `radius` | 碰撞圆半径（像素） |
| +6 | `base_damage` | 命中基础伤害值 |
| +7 | `damage_mult` | 伤害乘算系数 |
| +8 | `damage_type` | DamageType 整数（DamageType 枚举，0=PHYSICAL…4=POISON） |
| +9 | `owner_id` | 根源实体 ID（float 存 int，精度足够 24-bit ID） |
| +10 | `source_tags` | 位掩码（PRIMARY/TRIGGERED/SUMMON/REFLECTED） |
| +11 | `acceleration` | 速度加速度（像素/秒²，0=匀速） |
> **冷数据（非热路径）** 存储于 `_bullet_contexts: Dictionary`（key=bullet_id），包含：
> `pierce_remaining`, `bounce_remaining`, `homing_strength`, `homing_range`, `homing_target_id`,
> `on_hit_payload_id`, `on_expire_payload_id`, `on_kill_payload_id`, `proc_rate`, `visited_targets`。
> 正弦弹道等额外字段（`wave_frequency`, `wave_amplitude`）也存于此 Dictionary，
> 不占用 SoA 热数组空间，仅在命中/特殊弹道帧查询。
>
> **职责分离**：`ProjectileDef` 是**生成时配置模板**，在 `SpellEvaluator.execute` 阶段由 ACTION 节点填充；
> `_bullet_contexts[bullet_id]` 是**运行时可变冷状态**，由 `BulletManager.spawn(def)` 从 `ProjectileDef` 拷贝创建。
> 两者字段名相同但生命周期不同：`ProjectileDef` 可安全复用（对象池 reset）；
> `_bullet_contexts[id]` 随子弹销毁时一同移除（`_bullet_contexts.erase(bullet_id)`）。
* 在 `_physics_process(delta)` 中，直接遍历 Array 进行物理积分，速度比遍历 Node Tree 快一个数量级。
* **Dirty Sync**: 仅当物体在屏幕视口内，且逻辑坐标发生位移时，才去同步 `Node2D.position`。
* **Homing 受限角速度制导（2026-07-30 实现，权威 spec：`docs_dev/specs/2026-07-30-bullet-homing-design.md`）**：
> **⚠️ 方案变更记录**：本节原方案为「每帧建立敌人位置快照 `_enemy_pos_snapshot`，所有 homing 子弹共用后线性扫描最近敌人」（对应已退役的 `P6-N2` / `P6-N25`）。实际实现改为**按 entity_id 锁定目标** —— 快照按槽位存位置、**不含 entity_id**，支撑不了锁定语义；且锁定后目标有效期内**零查询**，比每帧 O(M) 重扫更省。快照与 `EnemyManager.fill_pos_snapshot` 已一并删除。
目标策略为**发射后锁定**：`_push_projectile` 只写冷数据、不解析目标（`homing_target_id = -1`），首帧在 `_gd_integrate` 惰性获取；此后**仅在目标失效时**（`EnemyManager.get_pos_by_id` 返回哨兵 `(-9999,-9999)`，即目标死亡）才重选。稳态下一颗子弹一生只查 1–2 次。
```gdscript
# 冷数据字段（_bullet_contexts[bullet_idx]）：
# homing_strength : float —— 最大转向角速度，单位 弧度/秒（3.0 ≈ 350 速度下转弯半径 117px）
# homing_range : float —— 选目标搜索半径，默认 400.0
# homing_target_id: int —— 锁定的 entity_id，-1 = 未锁定/待重选
# homing_retry_at : int —— 重选失败后的退避到期时刻（ms 墙钟），成功即 erase
# bullet_manager._gd_integrate 循环体顶部，位置积分【之前】调用，使子弹当帧即沿新方向前进。
# 判别提到调用方：绝大多数冷数据子弹（纯 pierce/bounce/状态/荷载）不归航，
# 避免为它们付一次完整函数调用。
if has_cold and _bullet_contexts.has(i) and _bullet_contexts[i].has("homing_strength"):
_apply_homing(i, base, delta)
func _apply_homing(bullet_idx: int, base: int, delta: float) -> void:
var cold: Dictionary = _bullet_contexts[bullet_idx]
var strength: float = float(cold.get("homing_strength", 0.0))
if strength <= 0.0: return
var pos: Vector2 = Vector2(_data[base + 0], _data[base + 1])
var tid: int = int(cold.get("homing_target_id", -1))
var tpos := Vector2(-9999.0, -9999.0)
if tid >= 0:
tpos = EnemyManager.get_pos_by_id(tid)
if tpos == Vector2(-9999.0, -9999.0): # 目标失效或首帧：重选
if EnemyManager.get_active_count() == 0:
return # 空场守卫：挡掉清场瞬间全体子弹集体查询
var now: int = Time.get_ticks_msec()
if now < int(cold.get("homing_retry_at", 0)):
return # 退避中：本帧直行，零查询
# 复用 bounce 期引入的 _find_nearest_unvisited，天然滤除哨兵与 visited_targets
tid = _find_nearest_unvisited(pos, float(cold.get("homing_range", 400.0)),
cold.get("visited_targets", []))
cold["homing_target_id"] = tid
_bullet_contexts[bullet_idx] = cold
if tid < 0:
# 抖动「到期时刻」而非共用固定退避（见下方 ⚠️），落在 [200, 400) ms
var jitter: int = (bullet_idx * HOMING_RETRY_MS) / maxi(1, _active_count)
cold["homing_retry_at"] = now + HOMING_RETRY_MS + jitter % HOMING_RETRY_MS
return
cold.erase("homing_retry_at") # 重选成功：恢复零查询稳态
tpos = EnemyManager.get_pos_by_id(tid)
if tpos == Vector2(-9999.0, -9999.0): return
var vel := Vector2(_data[base + 2], _data[base + 3])
var diff: float = wrapf((tpos - pos).angle() - vel.angle(), -PI, PI) # 最短转向方向
var nv: Vector2 = vel.rotated(clampf(diff, -strength * delta, strength * delta))
_data[base + 2] = nv.x # rotated() 保持速率不变，只改方向
_data[base + 3] = nv.y
```
三个数值要点：`wrapf(..., -PI, PI)` 保证走最短转向（否则追一个偏 179° 的目标会绕远路）；`clampf` 到 `strength * delta` 即最大角速度，落实「中度制导」（追不上贴脸急转的目标）；`rotated()` **保持速率不变**，与 bounce 重定向用 `spd` 保速率一致。
> **⚠️ 失败退避必须带抖动**（spec §5.4，本次最值得记住的一条）：重选**失败**时若不留记录，该子弹余生每帧都会重跑 `query_circle(r=400)`（半径 400 覆盖约 196 格 + 一次 `PackedInt32Array` 分配 ≈ 一百多次碰撞查询）。但**朴素固定退避会把子弹锁进同相、而非打散** —— 同帧失败的子弹拿到同一个 `now`，一个退避周期后又整齐地一起重试，尖峰每 12 帧永久复发。故抖动到期时刻，用「`bullet_idx` 在活跃弹数中的占比」铺满恰好一个退避周期（`HOMING_RETRY_MS` 一值两用：既是基础退避时长也是抖动窗口宽度）。实测数据见 spec §5.2 / §5.5，此处不复述以免两套数字分叉。
> **与 bounce 协同**：bounce 在命中瞬间硬重定向到「最近未访问敌」，若不协调，下一帧 homing 就会覆盖它、使 bounce 失效。语义定为**bounce 负责选目标、homing 负责追上去**。bounce 重定向块内：
> ```gdscript
> if cold.has("homing_strength"): # 前置守卫：纯 bounce 弹不写 homing 键
> cold["homing_target_id"] = next_id
> cold.erase("homing_retry_at") # 新目标有效，须撤销过期退避
> ```
> `has("homing_strength")` 这个守卫不可省 —— 没有它，纯 bounce 子弹会被塞进一个永不被消费的 `homing_target_id`；而 `erase` 不可省是因为退避键若残留，子弹会对着 bounce 刚给的有效目标拒绝转向（该缺陷在实现期评审中实测复现并修复）。
* **EnemyManager 对外查询接口**：以下函数供 BulletManager、DropManager、BossManager、AudioManager 调用，均为 GDScript 侧接口（轻量读操作，非热路径）：
```gdscript
# enemy_manager.gd — 对外查询接口（热路径内不调用，仅事件驱动 / 轮询路径使用）
func get_pos_by_id(entity_id: int) -> Vector2:
# BulletManager 碰撞检测与 homing 转向查询目标位置；
# 未命中（已死亡 / 不存在）返回哨兵 Vector2(-9999, -9999)，
# 此约定即 homing「锁定目标已失效」的判据，调用方须显式比对哨兵。
var idx: int = _entity_index_map.get(entity_id, -1)
if idx < 0: return Vector2(-9999.0, -9999.0)
return Vector2(_data[idx * ENEMY_STRIDE], _data[idx * ENEMY_STRIDE + 1])
func get_last_position(entity_id: int) -> Vector2:
# DropManager 在 ENEMY_KILLED 事件中查询死亡位置（EnemyManagerCs 死亡时缓存到字典）
return _death_position_cache.get(entity_id, Vector2.ZERO)
func get_type(entity_id: int) -> String:
# DropManager / BossManager 查询敌人类型 ID（对应掉落表 key / boss_config key）
return _entity_type_map.get(entity_id, "") # { entity_id: String }，spawn 时写入
func get_hp_percent(entity_id: int) -> float:
# BossManager 多阶段 HP 切换使用；entity_id 存在则返回 [0.0, 1.0]，否则返回 0.0
var idx: int = _entity_index_map.get(entity_id, -1)
if idx < 0: return 0.0
var hp := _data[idx * ENEMY_STRIDE + 4] # slot +4: hp（权威来源 implementation_plan §2.3.C）
var hp_max := _data[idx * ENEMY_STRIDE + 5] # slot +5: hp_max
return hp / max(hp_max, 0.001)
func get_visible_count() -> int:
# AudioManager 动态音乐层轮询；返回当前在 Camera AABB 内的存活敌人数
return _visible_count # EnemyManagerCs 的 LOD 循环维护此计数，O(1) 读取
func get_nearest_pos(origin: Vector2, max_dist: float = 9999.0) -> Vector2:
# BulletManager.get_nearest_enemy_pos() 调用；直接线性扫描 SoA _data，O(M)
# 仅在发射时调用，非每帧热路径（homing 走 get_pos_by_id 锁定目标，不经此函数）
var best_pos := origin # 无敌人时返回 origin（非 Vector2.ZERO）
var best_dist := max_dist * max_dist # 比较平方距离，避免 sqrt
for i in _active_count: # _active_count，不存在 _enemy_count
var px := _data[i * ENEMY_STRIDE + 0]
var py := _data[i * ENEMY_STRIDE + 1]
var d2 := (px - origin.x) * (px - origin.x) + (py - origin.y) * (py - origin.y)
if d2 < best_dist:
best_dist = d2
best_pos = Vector2(px, py)
return best_pos # 实现全扫存活敌人，不按 _visible_flags 过滤
```
> **EnemyManager SoA 完整槽位布局**（权威来源：`implementation_plan.md §2.3.C`，P6-N45）：
> ```
> ENEMY_STRIDE = 8
> [ x, y, vx, vy, hp, hp_max, faction_and_type, status_bits ]
> 0 1 2 3 4 5 6 7
> ```
> - `+4 hp`：当前生命值；`+5 hp_max`：最大生命值（BossManager 的 `get_hp_percent` 读取此两槽）
> - `+6 faction_and_type`：高 16 位 = faction（0=敌方, 1=友方）；低 16 位 = enemy_type_id
> - `+7 status_bits`：燃烧/冰冻/中毒等位掩码（精确 DoT 计时存 `_enemy_contexts` 冷数据）
> - `_death_position_cache`、`_entity_type_map`、`_entity_index_map` 为类成员 `Dictionary`，spawn/kill 时 GDScript 维护。
* **自动瞄准目标选取算法**：法杖自动开火时，发射方向需要选取"目标敌人"。目标选取逻辑集中在 `PlayerManager.get_aim_target()` 中，优先级如下：
1. **手柄/鼠标显式瞄准**：若存在显式输入方向（`aim_vector.length() > 0.3`），直接使用该方向，不进行目标锁定。
2. **最近敌人（默认）**：委托 `EnemyManager.get_nearest_pos()` 直接线性扫描敌人 SoA `_data`，取欧氏距离最小的存活敌人位置，作为开火方向。时间复杂度 O(M)；仅在发射时调用，非每帧热路径。
3. **自定义优先级扩展（P2）**：商店购买"目标优先级"被动时（如"优先最低 HP"、"优先最近"），`PlayerManager.aim_priority` 属性切换选取算法，但当前 P0/P1 阶段固定为最近敌人。
```gdscript
# player_manager.gd
func get_aim_direction() -> Vector2:
var aim := Input.get_vector("aim_left", "aim_right", "aim_up", "aim_down")
if aim.length() > 0.3:
return aim.normalized() # 手柄/鼠标显式瞄准优先
# 自动瞄准：查最近敌人快照
var nearest_pos := BulletManager.get_nearest_enemy_pos(get_position())
if nearest_pos == Vector2.INF:
return Vector2.RIGHT # 无敌人时向右发射（避免零向量）
return (nearest_pos - get_position()).normalized()
```
### 4.3 物理与碰撞机制
* **Area2D (优先方案)**: 子弹使用 `Area2D` + `CollisionShape2D`，通过 `body_entered` 信号回调处理命中。Godot 的 Area2D 属于轻量级重叠检测，无刚体动力学开销。
* 利用 **Physics Layer & Mask** 系统过滤阵营（子弹层只与敌人层交互），避免无效检测。
* **Spatial Hashing Fallback**: 若 Area2D 在 2000+ 弹幕下仍有压力，回退到定制的 **Spatial Grid** (一维数组网格)，只计算临近 Grid 的实体碰撞，确保碰撞检测复杂度维持在 O(N)。
* **Separation Logic**: 怪物挤压不使用刚体求解，而是施加简单的轻量级斥力向量。
* **Cell Size 定义**: 默认格子边长 = `max_collider_radius × 2`（如最大子弹半径 20px → Cell = 40px）。格子过小增加哈希桶压力，格子过大降低空间剪裁效果。推荐随关卡配置可调。
* **超大弹体豁免策略**：`nuke` 等特殊弹体半径可达 300px，若将 Cell Size 设为 600px 会使整个 SpatialGrid 退化为单格全量扫描。
解决方案：SpatialGrid 的 `max_collider_radius` 仅取**标准弹体**上限（如 24px → Cell = 48px）；
`radius > LARGE_PROJECTILE_THRESHOLD`（默认 = 64px）的弹体**绕过 SpatialGrid**，改用 `EnemyManager.query_aabb(bullet_aabb)` 进行全量矩形测试——
此类超大弹体数量通常极少（≤ 5 颗/帧），全量扫描代价可接受；同时 SpatialGrid 精度不受破坏。
`BulletManager` 在 spawn 时按 radius 自动路由到正确的碰撞路径，不需要业务层感知区别。
* **运行时切换策略**: `BulletManager` 维护 `_collision_mode: int`（`0` = Area2D，`1` = SpatialGrid）。
* 上穿阈值（`_active_count > 2000 and _collision_mode == 0`）：**分帧渐进禁用** Area2D（每帧最多关闭 `BATCH_DISABLE_PER_FRAME = 100` 个节点，约需 20 帧完成 2000 节点的切换，避免单帧卡顿）；过渡期内新生成子弹直接走 SpatialGrid 路径；所有 Area2D 禁用完毕后正式激活 MultiMesh 渲染。
* 下穿回滞（`_active_count < 1500 and _collision_mode == 1`）：反向切回，避免阈值附近频繁震荡。**⚠️ 反向切换 Jitter 风险**：从 SpatialGrid 切回 Area2D 时，约 1500 颗子弹需要重新启用 Node（`process_mode = INHERIT`）。若全部在单帧完成，将产生约 1500 次节点状态更改（额外 1~2ms，可见微卡顿）。**缓解策略**：反向切换同样须分帧渐进（`BATCH_ENABLE_PER_FRAME = 100`，约 15 帧完成），过渡期内存活子弹继续走 SpatialGrid 路径，碰撞正确性不受影响。
* 两段路径（信号回调 vs 手动查询）最终均调用同一 `_on_bullet_hit(bullet_id, enemy_id)` 函数，后处理逻辑完全共用。
> **⚠️ 实现现状 (2026-07-20 审计)**：上述 Area2D 优先 + `_collision_mode` 三档运行时切换**从未实现**。现状是 **SpatialGrid-only**：`BulletManager._check_collision` 无条件走 `SpatialGrid.query_circle`，代码中不存在 Area2D / CircleShape2D / `body_entered` / `_collision_mode` / `BATCH_DISABLE_PER_FRAME`。这一简化与 `implementation_plan.md` §S0 的 **R-04 决议**（永久锁定 SpatialGrid 为 200+ 主力、不保留 Area2D 回退）一致——本节 §4.3/§4.4 属尚未同步的旧设计。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
### 4.4 渲染优化
子弹渲染策略依据同屏数量分三档，**Area2D 与 MultiMeshInstance2D 不共存**——MultiMesh 绕过节点树，意味着子弹无法挂载 Area2D。因此两者适用于不同的弹幕规模区间：
> **⚠️ 实现现状 (2026-07-20 审计)**：下表三档**未实现**。现状：`MultiMeshInstance2D` **从第 1 帧起单档常开**（无 Node2D 池、无 <200/200-2000 档），子弹与敌人均走 MultiMesh。同步是 **GDScript 逐实例 `set_instance_transform_2d` 循环**（非文档的 C# `SetBuffer` 批量上传）；子弹无按型颜色（统一 `modulate`），敌人有 per-instance color。既然碰撞已 SpatialGrid-only，Node 池档位已无意义，此简化为**代码更优**。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
| 同屏弹幕数 | 渲染方案 | 碰撞方案 | 说明 |
| :--- | :--- | :--- | :--- |
| < 200 | Node Pool (Node2D) | Area2D | 全功能，支持粒子特效、信号回调 |
| 200–2000 | Node Pool + Dirty Sync | Area2D | 仅视口内节点同步 position |
| 2000+ | MultiMeshInstance2D | 自定义 SpatialGrid | 完全绕过节点树，牺牲特效换取帧率 |
* **Node Pooling**: 严格的节点池管理（使用 Array 存储空闲节点，Node.process_mode = DISABLED 代替真实销毁）。
* **MultiMeshInstance2D**: 仅在同屏弹幕超过 2000 且切换为 SpatialGrid 碰撞时启用。启用后 BulletManager 不再为每颗子弹维护 Node 实例，改为直接更新 `MultiMesh.transform_array`。
**SoA 索引 ↔ MultiMesh transform_array 索引映射规则**：
BulletManager 的 `_data: PackedFloat32Array` 使用 **紧凑活跃列表（Compact Active List）** 布局：索引 0 到 `_active_count - 1` 始终是存活子弹，dead-and-removed 子弹用 swap-and-pop 填入空位。MultiMesh 的 `instance_count` 始终等于 `_active_count`，两者**共享同一索引**——SoA 中第 i 个子弹对应 MultiMesh 第 i 个实例变换。
```gdscript
# BulletManagerCs.cs — _PhysicsProcess 末尾（完成 SoA 积分后）
# 将所有活跃子弹的位置同步到 MultiMesh.transform_array（批量上传）
private void SyncMultiMesh()
{
// _multiMesh.InstanceCount 由 GDScript 在 _active_count 变化时更新
// 这里只做 transform_array 的批量写入，不触发单实例 set_instance_transform_2d()
var transforms = new float[_activeCount * 8]; // Transform2D = 6 float + 2 位置 = Godot 内部格式 8 float
var span = _data.AsSpan();
for (int i = 0; i < _activeCount; i++)
{
int src = i * BulletStride;
int dst = i * 8;
// Transform2D(1,0, 0,1, px, py) — 纯平移，无旋转（子弹朝向由 Sprite 贴图决定）
transforms[dst] = 1f; transforms[dst + 1] = 0f; // col0
transforms[dst + 2] = 0f; transforms[dst + 3] = 1f; // col1
transforms[dst + 4] = span[src]; // px
transforms[dst + 5] = span[src + 1]; // py
// Godot MultiMesh 格式：8 floats per instance（含 custom_data，后 2 float 可复用为 type/size）
transforms[dst + 6] = span[src + 10]; // bullet_type（用于 Shader 切换 UV atlas 区域）
transforms[dst + 7] = span[src + 9]; // size_mult（用于 Shader 缩放实例）
}
_multiMesh.SetBuffer(transforms); // 单次批量上传，1 次 Draw Call
}
```
**子弹类型与 MultiMesh Shader**：MultiMesh 使用单一材质 + Atlas Texture，`transform_array[i * 8 + 6]`（bullet_type 整数）作为 Shader 参数，在 Canvas Shader 中做 `UV = atlas_uv_for_type(bullet_type)`，支持不同外观子弹共用一次 Draw Call。
* **Throttling (分帧降频)**:
* 伤害数字：每帧最多弹出 10 个，多余的合并或延迟显示。
* AI 索敌：不需要每帧执行 FindNearest，可分散到 10~20 帧内轮询一次（利用 Engine.get_physics_frames() % 15 == entity_id % 15 错峰轮询）。
### 4.5 帧预算分配表 (Frame Budget Allocation)
> **目标**：60fps → 单帧总预算 **16.67ms**。以下为 S0 性能验收的基准分配；S0 Profiler 实测后需将"S0 实测值"列回填并提交 git，作为后续切片的性能基线快照。
> **⚠️ 实现现状 (2026-07-20 审计)**：下表"语言"列标注 C#（`BulletManagerCs`/`EnemyManagerCs`/`SpatialGridCs`/`SpellEvaluatorCs`）的热路径**均未接线**——三个 C# 内核从未实例化、从未进场景树，战斗逻辑 **100% 由 GDScript 回退路径承载**（R-08 顺延）。C# `AsSpan()` 零拷贝在代码中不存在。表中"S0 实测值"确为 GDScript 回退实测（见 :795 摘要）。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
| 系统 | 语言 | 预算上限 | S0 实测值 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `BulletManagerCs._PhysicsProcess` | C# | 2.0ms | **0.37ms** | 2000 子弹 GDScript SoA 积分（P-S0-01；C# 热路径 S1 填充后预计更低） |
| `EnemyManagerCs._PhysicsProcess` | C# | 2.0ms | **0.23ms** | 1000 敌人直线追踪 + fill_pos_snapshot（P-S0-02；Boid C# S1 填充）
⚠️ 该实测取于 S0，其中 `fill_pos_snapshot` 已于 2026-07-30 随归航实现删除，当前循环不含此项 |
| `SpatialGridCs` 重建 + `query_circle` | C# | 1.5ms | **< 0.001ms** | GDScript stub（返回空数组）；C# SpatialGridCs 实例化后 S1 回填实测 |
| `SpellEvaluatorCs.execute_compiled` | C# | 1.0ms | — | 高频施法内层 while 循环（S1 起填入）|
| `StatusManagerCs._PhysicsProcess` | C# | 1.5ms | — | 200+ DoT 逐 tick（S4 验收后填入，P-S4-02；与 implementation_plan §2.4 统一）|
| `ZoneManagerCs._PhysicsProcess` | C# | 1.0ms | — | 64 zones × SpatialGrid 查询（S5 验收后填入）|
| GDScript 游戏循环（WaveManager / EventBus dispatch）| GDScript | 1.5ms | — | 事件分发 + 波次状态机 |
| MultiMesh transform 上传 CPU→GPU | Godot 渲染器 | 1.5ms | — | 2000+ 子弹时（S6 验收后填入）|
| Godot 渲染器 Draw Call 基线 | 引擎 | 2.0ms | — | 背景 + 角色 + HUD（S1 场景建立后填入）|
| **保留余量**（突发帧：GC、资源加载）| — | **1.17ms** | — | — |
| **合计** | | **16.67ms** | **≈ 0.60ms**（S0 GDScript 基线，2000弹+1000敌；FPS 180）| |
> **S0 实测摘要（2026-06-04）**：机器 RTX 2060；Godot 4.6.2 stable mono；Windows 10。2000 子弹 + 1000 敌人同屏，GDScript fallback 运行（C# 热路径骨架未激活）。`physics_frame_time_msec`（Godot Monitor）= 0.05~0.13ms，FPS 稳定 145~180，远超 60fps 目标。R-01/R-03 风险**已消除**。SpatialGrid C# 实例化与 AsSpan() 零拷贝基准在 S1 阶段随 BulletManagerCs 真实热路径一同验收（P-S0-06/P-S0-07 S1 延续项）。
**验收规则**：
- **S0 联合基准**：`BulletManagerCs` + `EnemyManagerCs` + `SpatialGridCs` 三项合计实测 **< 6ms**（覆盖 P-S0-01/02/04）。
- **超标触发流程**：若任一系统实测超出预算上限，**该切片不得进入下一切片**；立即检查是否违反 ADR-L1 规则 1（内层循环 `Call()`）或规则 2（未使用 `AsSpan()` 零拷贝）。
- **回填规范**：每个新切片的验收标准中对该切片新增系统补充帧时间目标；S6 发布前所有"—"必须替换为实测值。
---
### 4.6 内存预算表 (Memory Budget)
> **目标**：确保在目标平台（PC 和未来 Nintendo Switch）的内存占用在可接受范围内。Switch 主内存总量 4GB，系统 + 驱动常驻约 1.5GB，游戏可用约 **2.5GB**；PC 目标 RSS < **512MB**。
| 内存类别 | PC 预算 | Switch 预算 | 说明 |
| :--- | :--- | :--- | :--- |
| 代码 + GDScript VM + C# CLR | 80MB | 200MB | Mono 运行时常驻较大 |
| 纹理资源（Atlas + VFX + UI） | 150MB | 400MB | 压缩格式：PC=DXT5，Switch=ASTC4×4 |
| 音频资源（BGM 流式 + SFX 预加载）| 30MB | 80MB | BGM 流式播放，SFX 池全量预加载 |
| BulletManager SoA（2000 子弹） | < 1MB | < 1MB | `BULLET_STRIDE=12` × 2000 × 4B ≈ 96KB |
| EnemyManager SoA（1000 敌人） | < 1MB | < 1MB | `ENEMY_STRIDE=8` × 1000 × 4B ≈ 32KB |
| SpellContext 对象池（32 实例） | < 1MB | < 1MB | 每实例约 2KB（含 payloads Array） |
| Node Pool（子弹节点 2000 个）| 20MB | 50MB | 每 Node2D 约 10KB；MultiMesh 激活后降至 ~0 |
| VFX 粒子节点池（200 个）| 5MB | 10MB | MAX_ACTIVE_VFX=200 |
| DPS 环形缓冲区 + 其他运行时 | < 1MB | < 1MB | 各 PackedFloat 数组合计 |
| 存档文件（user://） | < 1MB | < 1MB | JSON 明文 < 100KB；含 HMAC 签名 |
| **合计（估算）** | **~290MB** | **~745MB** | Switch 远低于 2.5GB 限制 |
**验收规则**：
- **S6 P0 验收 P-S6-07**：Godot Profiler → Memory 标签页实测 RSS：PC < 512MB，Switch 目标 < 2.5GB。
- **热场景峰值**：Wave 20 Boss 战（最大同屏实体数）测量内存峰值，作为 S6 发布基线。
- **纹理内存监控**：`RenderingServer.get_rendering_info(RenderingServer.RENDERING_INFO_TEXTURE_MEM_USED)` 不超过 PC 预算的 150MB。
---
## 5. 游戏循环与系统集成 (Game Loop & System Integration)
### 5.1 GameCycleManager 状态机 (FSM)
> **⚠️ 实现现状 (2026-07-20 审计)**：`GameCycleManager` Autoload **不存在**。顶层状态机现内嵌在场景子节点 `combat_manager.gd`，仅 **5 态**（INIT/BATTLE/SETTLEMENT/SHOP/GAME_OVER），缺文档的 WAVE_INTRO 开场、WAVE_RESULT 升级卡结算、GAME_CLEARED 通关、PAUSE 独立态（暂停改由 `get_tree().paused` 处理）。`GAME_STATE_CHANGED` payload 用字符串态名而非枚举。同理 §5.10 的 `UIManager` Autoload 也不存在——全部 UI 在 `combat_s2.gd` 程序化构建，无 `HUD.tscn`/`shop.tscn` 等场景，`DamageNumber` 飘字未实现。下文 GameCycleManager/UIManager 相关设计保留作目标蓝图。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
`GameCycleManager` 是游戏最顶层的协调者，持有全局状态机并驱动各 Manager 的生命周期。
```gdscript
# game_cycle_manager.gd (Autoload: GameCycleManager)
enum GameState {
MAIN_MENU = 0, # 主菜单（初始/死亡后/通关后回到此状态）
LOADING = 1, # 场景加载过渡（ResourceLoader 异步加载战斗场景）
SHOP = 2, # 商店/背包阶段（波次间）
WAVE_INTRO = 3, # 波次开场动画（约 1.5s，Boss 波有特殊演出）
WAVE = 4, # 战斗进行中
WAVE_RESULT = 5, # 本波结算（经验弹算、升级选择 UI）
GAME_OVER = 6, # 死亡结算界面
GAME_CLEARED = 7, # 通关结算（Wave 20 Boss 击杀后）
PAUSE = 8, # 暂停（可从 WAVE/SHOP 进入，恢复后返回原状态）
}
var _state: GameState = GameState.MAIN_MENU
var _prev_state: GameState = GameState.MAIN_MENU # 用于 PAUSE 恢复
var wave_num: int = 0 # 当前波次（UIManager / WaveManager 均读取）
var _rng: RandomNumberGenerator = RandomNumberGenerator.new()
# _rng 在每次 Run 开始时重置：_rng.seed = hash(Time.get_ticks_msec())
# UpgradeSystem.build_choices(wave_num, _rng) 与 ShopManager 独立使用各自 seed，互不干扰
func transition_to(next: GameState) -> void:
_on_exit(_state)
_prev_state = _state
_state = next
_on_enter(next)
func get_state() -> GameState: return _state
```
#### 状态转换表
| 当前状态 | 触发条件 | 目标状态 | 关键副作用 |
| :--- | :--- | :--- | :--- |
| `MAIN_MENU` | 玩家点击"开始游戏" | `LOADING` | 异步加载 BattleScene.tscn |
| `LOADING` | 场景加载完成信号 | `SHOP` | wave_num=1；调用 ShopManager.open_shop(wave_num) |
| `SHOP` | 玩家点击"出发" | `WAVE_INTRO` | PlayerManager.compile_all_wands()；WaveManager.prepare_wave(wave_num) |
| `WAVE_INTRO` | 开场动画播放完毕（1.5s Timer） | `WAVE` | WaveManager.start_wave()；BulletManager.reset()；EnemyManager.reset() |
| `WAVE` | `EventID.WAVE_COMPLETE` 收到 | `WAVE_RESULT` | 经验结算；存档（ADR-A2 §2 波次结束自动存档） |
| `WAVE` | `EventID.PLAYER_DIED` 收到 | `GAME_OVER` | 统计数据收集；EndlessRecordsManager 不更新 |
| `WAVE_RESULT` | wave_num < 20，玩家确认升级 | `SHOP` | wave_num++；ShopManager.restock(wave_num) |
| `WAVE_RESULT` | wave_num == 20 且 Boss 已击杀 | `GAME_CLEARED` | EndlessRecordsManager 更新；Steam成就触发 |
| `WAVE_RESULT` | wave_num > 20（Endless模式） | `SHOP` | wave_num++；ShopManager.restock(wave_num) |
| `GAME_OVER` / `GAME_CLEARED` | 玩家点击"返回菜单" | `MAIN_MENU` | 卸载 BattleScene；重置所有 Autoload Manager |
| 任意战斗状态 | Input.is_action_just_pressed("pause") | `PAUSE` | 保存 _prev_state；Engine.time_scale = 0 |
| `PAUSE` | 再次按暂停键 | `_prev_state` | Engine.time_scale = 1 |
#### Manager Reset 协议
每次从 `GAME_OVER`/`GAME_CLEARED` 返回 `MAIN_MENU` 时，GameCycleManager 负责按顺序重置所有 Autoload：
```gdscript
func _reset_all_managers() -> void:
# 顺序重要：先停止所有计算，再清理数据，最后重置 UI
BulletManager.reset() # 清空所有子弹 SoA 数据
EnemyManager.reset() # 清空所有敌人 SoA 数据
MinionManager.reset() # 清空所有召唤物
ZoneManager.reset() # 清空所有地面效果
StatusManager.reset() # 清空所有状态效果
SpellEvaluator.reset() # 清空 SubPayloadRegistry
DamageContextPool.reset() # 归还所有在途 context（防止下局 context 泄漏）
PlayerManager.reset() # 重置血量/位置/蓄力状态
WaveManager.reset() # wave_num = 0；spawn 队列清空
ShopManager.reset() # 商品列表清空
ProfileManager.clear_run() # 清除本局存档
```
---
### 5.2 WaveManager 框架设计
`WaveManager` 负责读取波次配置、按时序 spawn 敌人、检测清场条件、向 GameCycleManager 上报结果。
#### 波次配置 JSON 格式
```json
// res://resources/waves/wave_01.json
{
"wave_num": 1,
"duration_sec": 30, // 波次持续时间上限（超时也算通过）
"is_boss_wave": false, // true 时触发 BOSS_PHASE_CHANGED 事件和特殊 BGM
"spawn_groups": [
{
"enemy_id": "slime_basic",
"count": 20,
"spawn_mode": "perimeter", // "perimeter" = 屏幕外缘随机, "cluster" = 聚集点, "instant" = 全量即时
"delay_sec": 0.0, // 从波次开始到此批出现的延迟
"interval_sec": 0.5 // 同批内每只敌人的间隔（0 = 即时全量）
},
{
"enemy_id": "bat_fast",
"count": 10,
"spawn_mode": "perimeter",
"delay_sec": 8.0,
"interval_sec": 0.3
}
],
"clear_condition": "kill_all" // "kill_all" | "survive_duration" | "kill_boss"
}
```
#### WaveManager 状态与接口
```gdscript
# wave_manager.gd (Autoload: WaveManager)
var wave_num: int = 0
var _elapsed: float = 0.0
var _alive_count: int = 0 # 存活敌人数
var _total_spawned: int = 0 # 本波已 spawn 敌人总数
var _config: Dictionary = {} # 当前波次 JSON 解析结果
# 由 GameCycleManager 在 SHOP→WAVE_INTRO 时调用
func prepare_wave(num: int) -> void:
wave_num = num
_elapsed = 0.0; _alive_count = 0; _total_spawned = 0
var path := "res://resources/waves/wave_%02d.json" % num
_config = JSON.parse_string(FileAccess.open(path, FileAccess.READ).get_as_text())
# Boss 波：提前通知 AudioManager 切换 BGM 分层（淡入 Boss 主题）
if _config.get("is_boss_wave", false):
EventBus.emit(EventID.BOSS_PHASE_CHANGED, {"boss_id": _config.get("boss_id",""), "phase": 0, "bgm_layer": "boss"})
# 由 GameCycleManager 在 WAVE_INTRO 完成后调用
func start_wave() -> void:
_schedule_spawns()
func _physics_process(delta: float) -> void:
if GameCycleManager.get_state() != GameCycleManager.GameState.WAVE: return
_elapsed += delta
_process_spawn_queue(delta)
_check_clear_condition()
func _check_clear_condition() -> void:
match _config.get("clear_condition", "kill_all"):
"kill_all":
if _total_spawned >= _total_required() and _alive_count <= 0:
EventBus.emit(EventID.WAVE_COMPLETE, {"wave_num": wave_num})
"survive_duration":
if _elapsed >= _config.get("duration_sec", 30.0):
EventBus.emit(EventID.WAVE_COMPLETE, {"wave_num": wave_num})
"kill_boss":
pass # 由 BossManager 在 Boss 死亡时发出 WAVE_COMPLETE
# 订阅 ENEMY_KILLED：更新存活计数
func _on_enemy_killed(_enemy_id: int, _killer_id: int) -> void:
_alive_count = max(0, _alive_count - 1)
```
#### 敌人 spawn 与 EnemyManager 协议
WaveManager 不直接操作 EnemyManager 的 SoA 数据，而是调用高层接口：
```gdscript
# EnemyManager 对外接口（GDScript Autoload 层）
func spawn(enemy_id: String, position: Vector2) -> int: # 返回 entity_id
func reset() -> void # 清空 SoA（由 GameCycleManager 调用）
func get_alive_count() -> int
func get_pos_by_id(entity_id: int) -> Vector2 # BulletManager 碰撞/homing 用；未命中返回哨兵 (-9999,-9999)
```
---
### 5.3 ShopManager 框架设计
`ShopManager` 负责商品池管理、商店刷新、购买流程。与 `PlayerManager`（货币/库存）解耦通过 EventBus 或直接调用接口。
#### 商品池与刷新算法
```gdscript
# shop_manager.gd (Autoload: ShopManager)
# 商品类型（可出现在商店的物品分类）
enum ShopItemType { SPELL = 0, PASSIVE = 1, CONSUMABLE = 2, CORE = 3 }
# 商店槽位数：固定 6 格（3 法术 + 2 被动 + 1 消耗品）
const SLOT_COUNT: int = 6
const REROLL_BASE_COST: int = 20 # 首次刷新费用
const REROLL_COST_STEP: int = 10 # 每次刷新追加费用
var _slots: Array[Dictionary] = [] # 当前商店展示的商品
var _reroll_count_this_wave: int = 0 # 本波刷新次数（结算后重置）
var _rng: RandomNumberGenerator = RandomNumberGenerator.new()
# 由 GameCycleManager 调用
func open_shop(wave_num: int) -> void:
_reroll_count_this_wave = 0
_rng.seed = hash(wave_num) ^ ProfileManager.get_run_seed() # 确定性种子，防退出重开刷商店
_fill_slots(wave_num)
func restock(wave_num: int) -> void:
open_shop(wave_num)
func get_reroll_cost() -> int:
return REROLL_BASE_COST + _reroll_count_this_wave * REROLL_COST_STEP
func reroll(wave_num: int) -> bool:
var cost := get_reroll_cost()
if not PlayerManager.spend_gold(cost): return false
_reroll_count_this_wave += 1
_fill_slots(wave_num)
return true
func _fill_slots(wave_num: int) -> void:
_slots.clear()
# 权重池：随波次调整稀有度分布（越后期出现高稀有度概率越高）
var pool := _build_weighted_pool(wave_num)
for i in SLOT_COUNT:
_slots.append(_pick_from_pool(pool))
func _build_weighted_pool(wave_num: int) -> Array:
# ── 稀有度权重（与 UpgradeSystem._rarity_weights 保持相同曲线）────────
var common_w := max(5.0, 60.0 - wave_num * 2.5)
var uncommon_w := min(50.0, 30.0 + wave_num * 1.5)
var rare_w := min(30.0, max(5.0, wave_num * 1.2 - 5.0))
var legendary_w := min(10.0, max(0.0, wave_num * 0.5 - 8.0))
var rarity_weights := [common_w, uncommon_w, rare_w, legendary_w]
# ── 候选池：SPELL + PASSIVE（按稀有度归组）────────────────────────────
var candidates: Array[Array] = [[], [], [], []] # index = rarity-1
for item in SpellRegistry.all():
candidates[clamp(item.rarity - 1, 0, 3)].append({
"type": ShopItemType.SPELL, "id": item.spell_id,
"price": 4 + (item.rarity - 1) * 4 # 价格公式：4/8/12/16 金币
})
for item in PassiveRegistry.all():
candidates[clamp(item.rarity - 1, 0, 3)].append({
"type": ShopItemType.PASSIVE, "id": item.passive_id,
"price": 6 + (item.rarity - 1) * 5 # 被动略贵：6/11/16/21 金币
})
# ── 构建带权重的扁平池 ─────────────────────────────────────────────
var pool: Array = []
for rarity_idx in 4:
var w: float = rarity_weights[rarity_idx]
for entry in candidates[rarity_idx]:
pool.append({"entry": entry, "weight": w})
return pool
func _pick_from_pool(pool: Array) -> Dictionary:
# 使用确定性 _rng（防退出重开刷商店，与 open_shop seed 一致）
if pool.is_empty(): return {}
var total := 0.0
for item in pool: total += item["weight"]
var roll := _rng.randf() * total
for item in pool:
roll -= item["weight"]
if roll <= 0.0: return item["entry"]
return pool[-1]["entry"]
```
#### 购买流程与 PlayerManager 接口
```gdscript
# 购买接口（UIManager 点击购买时调用）
func purchase(slot_idx: int) -> bool:
if slot_idx < 0 or slot_idx >= _slots.size(): return false
var item: Dictionary = _slots[slot_idx]
if item.is_empty(): return false
var cost: int = item.get("price", 0)
if not PlayerManager.spend_gold(cost): return false
# 按类型分发给对应 Manager
match item.get("type", ShopItemType.SPELL):
ShopItemType.SPELL:
PlayerManager.add_spell_to_inventory(item.get("id", ""))
ShopItemType.PASSIVE:
PlayerManager.add_passive(item.get("id", ""))
ShopItemType.CORE:
PlayerManager.replace_core(item.get("slot", 0), item.get("id", ""))
ShopItemType.CONSUMABLE:
PlayerManager.use_consumable(item.get("id", ""))
_slots[slot_idx] = {} # 标记为已售
return true
func get_slots() -> Array[Dictionary]:
# UIManager._refresh_shop_ui() 读取当前商品展示列表（只读副本）
return _slots.duplicate()
func reset() -> void:
_slots.clear(); _reroll_count_this_wave = 0
func offer_free_spell(spell_id: String) -> void:
# DropManager 拾取法术卡掉落时调用。
# 弹出"拾取法术"交互 UI，玩家确认后才实际装备（防止强制打断操作）。
# UIManager 订阅此函数弹出的事件；若 UIManager 未处理则直接给予背包。
if not SpellRegistry.has(spell_id): return
EventBus.emit(EventID.SPELL_DROP_PICKUP, {
"spell_id": spell_id,
"auto_equip": false # false = 弹 UI 让玩家决定装到哪个 Core；true = 装 active_core
})
```
---
### 5.4 AudioManager 框架设计
`AudioManager` 管理 AudioBus 层级、动态音乐分层、音效池和空间音频。
> **权威定义说明**：本节为 AudioBus 结构的唯一权威来源。`ADR-A3`（§文档末尾）提供补充规则（空间音效衰减参数、节流规则、音量持久化细节），不重新定义 Bus 结构。两者合并阅读。
#### AudioBus 层级（权威）
```
Master
├── BGM (背景音乐总线，-6dB 预衰减)
│ ├── BGM_Base (基础旋律层，常驻播放，AudioStreamPlayer 独占)
│ └── BGM_Layer (动态叠加层：战斗强度 / Boss 阶段驱动；3 轨并行，按强度 fade-in)
├── SFX (战斗音效总线，-3dB)
│ ├── SFX_Combat (子弹/爆炸/伤害，来自 BulletManager/EnemyManager)
│ └── SFX_Spatial(2D 空间音效，挂 AudioEffect2DPan + 2D Reverb；max_distance=1200px)
├── UI (UI 音效，不受空间衰减，-3dB)
├── Ambience (循环环境音，-9dB)
└── Voice (语音 / Boss 台词，最高优先级，不受 SFX 池限制)
```
**AudioBusID 常量 Autoload**（代码中所有 Bus 名称必须通过此 Autoload 引用，禁止硬编码字符串）：
```gdscript
# scripts/autoloads/audio_bus_id.gd (Autoload: AudioBusID)
const MASTER : StringName = &"Master"
const BGM : StringName = &"BGM"
const BGM_BASE : StringName = &"BGM_Base"
const BGM_LAYER : StringName = &"BGM_Layer"
const SFX : StringName = &"SFX"
const SFX_COMBAT : StringName = &"SFX_Combat"
const SFX_SPATIAL : StringName = &"SFX_Spatial"
const UI : StringName = &"UI"
const AMBIENCE : StringName = &"Ambience"
const VOICE : StringName = &"Voice"
```
**Bus 配置文件**：`res://audio/bus_layout.tres`（Godot 内置 AudioBusLayout Resource，在 Project Settings > Audio 中指定）。
#### AudioManager 完整数据模型
```gdscript
# audio_manager.gd (Autoload: AudioManager)
# ── 常量 ───────────────────────────────────────────────────────
const MAX_CONCURRENT_SFX: int = 32 # 同时最多播放 32 个 SFX 实例（SFX_Combat + SFX_Spatial 共享上限）
const MAX_SAME_SFX_PER_FRAME: int = 3 # 同一音效每帧最多触发 3 次（防弹幕爆炸噪音堆叠）
const BGM_FADE_OUT_SEC: float = 0.8 # BGM 淡出时长（秒）
const LAYER_FADE_SPEED: float = 2.0 # 动态音乐层淡变速率（dB/秒）
const SFX_COOLDOWN_SEC: float = 0.1 # 同一音效最小间隔（防 0.1s 内重复播放）
# ── BGM 三步交叉淡变状态机 ────────────────────────────────────────
enum BgmPhase { IDLE, FADING_OUT, SWITCHING, FADING_IN }
var _bgm_phase: BgmPhase = BgmPhase.IDLE
var _current_bgm_id: String = ""
var _pending_bgm_id: String = ""
var _pending_fade_in: float = 1.5
var _fade_timer: float = 0.0
# ── BGM 播放器节点（_ready() 中创建并 add_child）───────────────────
var _bgm_base_player: AudioStreamPlayer = null # BGM_Base Bus 专属播放器
var _music_layers: Array[AudioStreamPlayer] = [] # BGM_Layer Bus 上的 3 个动态层播放器（index 0/1/2）
var _layer_target: int = 0 # 当前目标动态层级（0=基础/1=战斗/2=高强度）
# ── SFX 池 ──────────────────────────────────────────────────────
var _sfx_pool: Array[AudioStreamPlayer2D] = [] # 预分配节点池（MAX_CONCURRENT_SFX 个）
var _sfx_active_count: int = 0 # O(1) 可用池数量追踪（P6-N60 规范）
var _sfx_frame_count: Dictionary = {} # { sfx_id: int } 本帧计数（_process() 帧末清零）
var _sfx_last_play_time: Dictionary = {} # { sfx_id: float } 同 ID 节流计时
func _ready() -> void:
# 创建 BGM_Base 播放器
_bgm_base_player = AudioStreamPlayer.new()
_bgm_base_player.bus = AudioBusID.BGM_BASE
add_child(_bgm_base_player)
# 创建 3 个动态层播放器（挂 BGM_Layer Bus）
for i in 3:
var lp := AudioStreamPlayer.new()
lp.bus = AudioBusID.BGM_LAYER
lp.volume_db = -80.0 # 初始静音
add_child(lp)
_music_layers.append(lp)
# 预分配 SFX 池
for i in MAX_CONCURRENT_SFX:
var sp := AudioStreamPlayer2D.new()
sp.bus = AudioBusID.SFX_COMBAT # 默认 Combat 总线，play_sfx() 可按类型切换
sp.finished.connect(_on_sfx_finished.bind(sp))
add_child(sp)
_sfx_pool.append(sp)
EventBus.subscribe(EventID.BOSS_PHASE_CHANGED, _on_boss_phase_changed)
EventBus.subscribe(EventID.BOSS_KILLED, _on_boss_killed)
EventBus.subscribe(EventID.PLAYER_DIED, _on_player_died)
```
#### 核心接口
```gdscript
# ── SFX 接口 ─────────────────────────────────────────────────────
func play_sfx(sfx_id: String, position: Vector2, volume_db: float = 0.0,
bus: StringName = AudioBusID.SFX_COMBAT) -> void:
# 同帧频率限制
_sfx_frame_count[sfx_id] = _sfx_frame_count.get(sfx_id, 0) + 1
if _sfx_frame_count[sfx_id] > MAX_SAME_SFX_PER_FRAME: return
# 同 ID 0.1s 节流
var now := Time.get_ticks_msec() / 1000.0
if now - _sfx_last_play_time.get(sfx_id, 0.0) < SFX_COOLDOWN_SEC: return
_sfx_last_play_time[sfx_id] = now
var player := _acquire_sfx_player()
if player == null: return # 池耗尽，静默丢弃（非崩溃）
player.stream = SfxLibrary.get(sfx_id)
player.bus = bus
player.position = position
player.volume_db = volume_db
player.play()
func play_sfx_ui(sfx_id: String) -> void:
# UI 音效：不需要位置，直接挂 UI Bus
var player := _acquire_sfx_player()
if player == null: return
player.stream = SfxLibrary.get(sfx_id)
player.bus = AudioBusID.UI
player.position = Vector2.ZERO
player.volume_db = 0.0
player.play()
func _acquire_sfx_player() -> AudioStreamPlayer2D:
if _sfx_active_count >= MAX_CONCURRENT_SFX: return null
for p in _sfx_pool:
if not p.playing:
_sfx_active_count += 1
return p
return null # 全部占用
func _on_sfx_finished(player: AudioStreamPlayer2D) -> void:
_sfx_active_count = max(0, _sfx_active_count - 1)
# ── BGM 接口 ─────────────────────────────────────────────────────
func play_bgm(bgm_id: String, fade_in_sec: float = 1.5) -> void:
if _current_bgm_id == bgm_id: return
_pending_bgm_id = bgm_id
_pending_fade_in = fade_in_sec
_bgm_phase = BgmPhase.FADING_OUT
func fade_out_all(duration: float = 0.5) -> void:
# 玩家死亡时调用：所有 Bus 在 duration 秒内淡出至 -40dB
var tween := create_tween()
for bus_name in [AudioBusID.BGM, AudioBusID.SFX, AudioBusID.UI, AudioBusID.AMBIENCE]:
var idx := AudioServer.get_bus_index(bus_name)
tween.parallel().tween_method(
func(v): AudioServer.set_bus_volume_db(idx, v),
AudioServer.get_bus_volume_db(idx), -40.0, duration)
# ── BGM 三步交叉淡变（_process() 每帧驱动）────────────────────────
func _process_bgm_fade(delta: float) -> void:
match _bgm_phase:
BgmPhase.FADING_OUT:
_fade_timer += delta
_bgm_base_player.volume_db = lerp(0.0, -80.0, _fade_timer / BGM_FADE_OUT_SEC)
if _fade_timer >= BGM_FADE_OUT_SEC:
_bgm_base_player.stop()
_fade_timer = 0.0
_bgm_phase = BgmPhase.SWITCHING
BgmPhase.SWITCHING:
_bgm_base_player.stream = BgmLibrary.get(_pending_bgm_id)
_bgm_base_player.volume_db = -80.0
_bgm_base_player.play()
_current_bgm_id = _pending_bgm_id
_bgm_phase = BgmPhase.FADING_IN
BgmPhase.FADING_IN:
_fade_timer += delta
_bgm_base_player.volume_db = lerp(-80.0, 0.0, _fade_timer / _pending_fade_in)
if _fade_timer >= _pending_fade_in:
_bgm_base_player.volume_db = 0.0
_fade_timer = 0.0
_bgm_phase = BgmPhase.IDLE
# ── 动态音乐层（每 0.5s 在 _process() 中轮询，不在 _physics_process）──
func _update_music_layers(enemy_count: int, boss_active: bool) -> void:
_layer_target = 0
if boss_active or enemy_count >= 20: _layer_target = 2
elif enemy_count >= 5: _layer_target = 1
for i in _music_layers.size():
var target_db: float = 0.0 if i <= _layer_target else -80.0
_music_layers[i].volume_db = move_toward(
_music_layers[i].volume_db, target_db,
LAYER_FADE_SPEED * get_process_delta_time())
func _on_boss_phase_changed(payload: Dictionary) -> void:
var bgm_layer: String = payload.get("bgm_layer", "")
if bgm_layer.begins_with("boss"): play_bgm("boss_phase_0")
func _on_boss_killed(_payload: Dictionary) -> void:
play_bgm("wave_normal")
func _on_player_died(_payload: Dictionary) -> void:
fade_out_all(0.5)
func reset() -> void:
_bgm_base_player.stop()
for lp in _music_layers: lp.stop(); lp.volume_db = -80.0
_current_bgm_id = ""; _bgm_phase = BgmPhase.IDLE; _fade_timer = 0.0
_sfx_frame_count.clear(); _sfx_last_play_time.clear(); _sfx_active_count = 0
```
#### SfxLibrary / BgmLibrary 音频资源索引
`SfxLibrary` 和 `BgmLibrary` 是纯静态字典，在 `AudioManager._ready()` 时由预加载填充，供 `play_sfx` / `play_bgm` 通过字符串 ID 查找 `AudioStream`。
```gdscript
# sfx_library.gd（非 Autoload，挂在 AudioManager 子节点或直接合并到 audio_manager.gd）
const _SFX_MAP: Dictionary = {
# 战斗音效 ─────────────────────────────
"bullet_hit_flesh" : preload("res://audio/sfx/combat/bullet_hit_flesh.ogg"),
"bullet_hit_shield" : preload("res://audio/sfx/combat/bullet_hit_shield.ogg"),
"explosion_small" : preload("res://audio/sfx/combat/explosion_small.ogg"),
"explosion_large" : preload("res://audio/sfx/combat/explosion_large.ogg"),
"player_hurt" : preload("res://audio/sfx/combat/player_hurt.ogg"),
# 法术施放 ─────────────────────────────
"spell_cast_generic" : preload("res://audio/sfx/spell/cast_generic.ogg"),
"spell_cast_fire" : preload("res://audio/sfx/spell/cast_fire.ogg"),
"spell_cast_ice" : preload("res://audio/sfx/spell/cast_ice.ogg"),
# UI 音效 ──────────────────────────────
"ui_click" : preload("res://audio/sfx/ui/click.ogg"),
"ui_purchase" : preload("res://audio/sfx/ui/purchase.ogg"),
"ui_reroll" : preload("res://audio/sfx/ui/reroll.ogg"),
"ui_level_up" : preload("res://audio/sfx/ui/level_up.ogg"),
}
static func get(sfx_id: String) -> AudioStream:
return _SFX_MAP.get(sfx_id, null)
# bgm_library.gd（同上，流式资源使用 load() 而非 preload 避免启动时全量入内存）
const _BGM_MAP: Dictionary = {
"main_menu" : "res://audio/bgm/main_menu.ogg",
"shop" : "res://audio/bgm/shop.ogg",
"wave_normal" : "res://audio/bgm/wave_normal.ogg",
"boss_phase_0" : "res://audio/bgm/boss_phase0.ogg",
"boss_phase_1" : "res://audio/bgm/boss_phase1.ogg",
"boss_phase_2" : "res://audio/bgm/boss_phase2.ogg",
"game_over" : "res://audio/bgm/game_over.ogg",
"game_cleared" : "res://audio/bgm/game_cleared.ogg",
}
static func get(bgm_id: String) -> AudioStream:
var path: String = _BGM_MAP.get(bgm_id, "")
if path == "": return null
return load(path) as AudioStream # 流式加载，释放旧引用时 Godot 自动 GC
```
> **资源命名规范**：音效文件统一使用 `.ogg`（Vorbis，内存效率最优）；BGM 为 `.ogg` 流式（`loop: true` 在 Import 设置中启用）。所有路径以 `res://audio/` 为根，子目录 `sfx/` 和 `bgm/` 对应上方结构。
---
### 5.5 StatusManager 架构设计
`StatusManager` 集中管理所有实体的状态效果（DoT、减速、易伤等），消除各 Manager 自行处理状态的耦合。
#### 核心数据结构
```gdscript
# status_manager.gd (Autoload: StatusManager)
# 所有状态 ID 常量见 status_id.gd (Autoload: StatusID)
# 所有状态定义（效果、叠加规则）以 StatusTypeDef .tres 资源存储，由 StatusRegistry 加载
# SoA 布局（PackedFloat32Array）：每个状态实例占 STATUS_STRIDE=5 个浮点槽
# slot 0: entity_id (float 转 int 存储)
# slot 1: status_type_id (float 转 int)
# slot 2: remaining_duration
# slot 3: tick_accumulator
# slot 4: stack_count (float 转 int)
const STATUS_STRIDE: int = 5
const MAX_STATUS_INSTANCES: int = 512 # 最多同时存在 512 个状态实例（32KB）
var _data: PackedFloat32Array = PackedFloat32Array()
var _active_count: int = 0
```
#### 接口与生命周期
```gdscript
# 施加状态（由 SpellEvaluator / ZoneManager / BulletManager 调用）
# 权威签名（三处调用方统一使用此签名）：
# - SpellEvaluator: apply(target_id, status_type_id, intensity, owner_id=caster_id)
# - ZoneManager: apply(target_id, status_type_id, owner_id=zone_owner_id)（intensity=1.0 默认）
# - impl §2.4: apply(entity_id, status_type_id, stacks, duration, source_id) —
# duration/stacks 由 StatusTypeDef 驱动，不在此签名中暴露（内部细节）
func apply(entity_id: int, status_type_id: int, intensity: float = 1.0,
owner_id: int = -1) -> void:
# owner_id 用于 remove_source()（实体死亡时移除其施加的所有状态）；-1 = 无主（区域/无主状态）
var existing := _find(entity_id, status_type_id)
var typedef: StatusTypeDef = StatusRegistry.get(status_type_id)
if existing >= 0:
match typedef.stack_mode:
"refresh": _data[existing * STATUS_STRIDE + 2] = typedef.duration # 刷新时长
"stack": _data[existing * STATUS_STRIDE + 4] += 1.0 # 叠加层数
"ignore": pass # 已有则忽略
else:
_add_new(entity_id, status_type_id, typedef.duration, intensity, owner_id)
EventBus.emit(EventID.STATUS_APPLIED, {"target_id": entity_id, "status_type": status_type_id,
"stacks": int(_data[existing * STATUS_STRIDE + 4]) if existing >= 0 else 1})
func remove_source(owner_id: int) -> void:
# 移除 owner_id 施加的所有状态（召唤物/Boss 死亡时调用，防止游魂状态残留）
# 详见 implementation_plan.md §2.4 remove_source 实现
var i := 0
while i < _active_count:
if int(_data[i * STATUS_STRIDE + 5]) == owner_id: # slot +5: owner_id
# swap-and-pop
if i < _active_count - 1:
for k in STATUS_STRIDE:
_data[i * STATUS_STRIDE + k] = _data[(_active_count - 1) * STATUS_STRIDE + k]
_active_count -= 1
else:
i += 1
# 查询（EnemyManager.apply_damage() 读取易伤系数）
func get_stacks(entity_id: int, status_type_id: int) -> int:
var idx := _find(entity_id, status_type_id)
return int(_data[idx * STATUS_STRIDE + 4]) if idx >= 0 else 0
func has_status(entity_id: int, status_type_id: int) -> bool:
return _find(entity_id, status_type_id) >= 0
# _physics_process：tick DoT 并倒计时 duration，swap-and-pop 移除过期实例
func _physics_process(delta: float) -> void:
var i := 0
while i < _active_count:
var base := i * STATUS_STRIDE
_data[base + 2] -= delta # remaining_duration 倒计时
_data[base + 3] += delta # tick_accumulator 累积
var typedef: StatusTypeDef = StatusRegistry.get(int(_data[base + 1]))
while _data[base + 3] >= typedef.tick_interval:
_data[base + 3] -= typedef.tick_interval
_apply_dot_tick(i, typedef) # 触发 DoT 伤害
if _data[base + 2] <= 0.0:
_swap_and_pop(i) # O(1) 移除，顺序可乱
else:
i += 1
func reset() -> void:
_active_count = 0 # 不需要清零数据，_active_count 控制有效范围
```
#### StatusTypeDef 资源格式
```gdscript
# status_type_def.gd - Resource 子类
class_name StatusTypeDef
extends Resource
var display_name: String = "" # tr() KEY，UI 显示用
var duration: float = 3.0 # 默认持续时长（秒）
var tick_interval: float = 1.0 # DoT 跳字间隔（非 DoT 状态设 999.0 避免误触发）
var stack_mode: String = "refresh" # "refresh" | "stack" | "ignore"
var max_stacks: int = 99 # 叠层上限（stack 模式）
var dot_damage_per_tick: float = 0.0 # 每 tick 造成的基础伤害（0 = 无 DoT）
var dot_damage_type: int = DamageType.PHYSICAL
var can_catalyze: Array[int] = [] # 可参与催化的状态 ID 列表（空 = 不参与元素反应）
var is_combo_tracker: bool = false # true = 计数追踪状态（tick 逻辑由调用方控制，不走 DoT 路径）
var vfx_id: String = "" # 状态持续时的粒子特效 ID（空 = 无）
var icon_key: String = "" # UI 状态图标的 UIAtlas 键
```
---
### 5.6 PlayerManager 架构设计
`PlayerManager` 是玩家实体的单一数据权威，持有 HP / 金币 / XP / 等级 / 三个 Core / 被动列表。所有系统通过 `PlayerManager` 读写玩家状态，禁止直接操作其内部字段。
#### 玩家状态数据模型
```gdscript
# player_manager.gd (Autoload: PlayerManager)
# ── 生命值 ────────────────────────────────────────────────────
var hp: float = 100.0
var hp_max: float = 100.0
var hp_regen: float = 0.0 # 每秒自动回血（被动加成）
# ── 经济 ──────────────────────────────────────────────────────
var gold: int = 0
var xp: int = 0
var level: int = 1
# XP 升级阈值：⌊10 × 1.4^(level-1)⌋（见 numerical_design.md §1.2）
# level 20 = 最终等级（Wave 20 通关上限）；level 21+ 服务 Endless 模式
# ── 属性词条（被动叠加结果）────────────────────────────────────
var stats: PlayerStats = PlayerStats.new() # 伤害/攻速/移速等合并后的最终值
# ── 法杖 Core 系统（三 Core 机制）──────────────────────────────
const MAX_CORES: int = 3
var cores: Array[CoreDefinition] = [] # 当前装备的 Core，长度 ≤ MAX_CORES
var active_core_idx: int = 0 # 当前激活 Core 的下标
var _raw_decks: Array[SpellDeck] = [] # 每个 Core 对应的原始 SpellDeck（compile_all_wands 的输入）
var compiled_decks: Array[CompiledDeck] = [] # 每个 Core 的预编译产物（compile_all_wands 的输出）
# ── 消耗品临时持有（当回合商店购买的消耗品，在 WAVE 开始前使用）─────
var _pending_consumables: Array[String] = [] # consumable_id 列表
# ── 被动列表 ──────────────────────────────────────────────────
var passives: Array[String] = [] # 被动 ID 列表（passive_id: String，对应 .tres 文件名）
# ── 位置（View 层只读） ────────────────────────────────────────
var _position: Vector2 = Vector2.ZERO # 由 CharacterBody2D 每帧同步；其他系统通过 get_position() 读取
func get_position() -> Vector2: return _position
```
#### PlayerStats 合并数据类
```gdscript
# player_stats.gd - 所有被动合并后的最终属性快照（MODIFIER 节点的基准值来源）
class_name PlayerStats
extends RefCounted
var damage_mult: float = 1.0 # 全局伤害乘算（累乘所有 damage% 被动）
var attack_speed_mult: float = 1.0 # 攻速（影响 cast_delay 分母）
var move_speed: float = 200.0 # 像素/秒
var hp_max_bonus: float = 0.0 # HP 上限加成
var hp_regen_bonus: float = 0.0 # 回血加成
var cpu_limit: int = 5 # SpellEvaluator MAX_OPS 的基础乘数
var pickup_radius: float = 60.0 # 拾取半径（DropManager 用）
var crit_chance_bonus: float = 0.0 # 全局暴击率追加（叠加到 CastStats.crit_chance）
func recalculate(passives: Array[String]) -> void:
# 重置为默认值后依次应用每个被动的 stats_patch
_reset_defaults()
for pid in passives:
var def: PassiveDef = PassiveRegistry.get(pid)
if def: def.apply_to(self)
```
#### 核心接口
```gdscript
# ── 经济接口 ──────────────────────────────────────────────────
func spend_gold(amount: int) -> bool:
if gold < amount: return false
gold -= amount
return true
func add_gold(amount: int) -> void:
gold += amount
func add_xp(amount: int) -> void:
xp += amount
_check_level_up() # 达到阈值则 level++，触发 WAVE_RESULT 升级选择流程
func _check_level_up() -> void:
var threshold: int = int(10.0 * pow(1.4, level - 1))
while xp >= threshold and level < 21: # level 21 以上 Endless 不再升级
xp -= threshold
level += 1
threshold = int(10.0 * pow(1.4, level - 1))
# ── 生命值接口 ────────────────────────────────────────────────
func take_damage(amount: float) -> void:
hp = max(0.0, hp - amount)
EventBus.emit(EventID.PLAYER_DAMAGED, {"amount": amount, "source_id": -1})
if hp <= 0.0:
EventBus.emit(EventID.PLAYER_DIED, {})
func heal(amount: float) -> void:
hp = min(hp_max, hp + amount)
# ── Core / Deck 管理 ──────────────────────────────────────────
func add_core(core: CoreDefinition, slot: int = -1) -> void:
if slot < 0: slot = cores.size()
slot = clamp(slot, 0, MAX_CORES - 1)
if slot < cores.size():
cores[slot] = core
else:
cores.append(core)
_raw_decks.append(SpellDeck.new()) # 同步扩容，保持 cores 与 _raw_decks 等长
compiled_decks.resize(cores.size())
func replace_core(slot: int, core_id: String) -> void:
# ShopManager 购买 CORE 类商品时调用；以新 Core 替换指定槽，清空该槽的原始 Deck
if slot < 0 or slot >= MAX_CORES: return
var core: CoreDefinition = CoreRegistry.get(core_id)
if core == null: return
if slot < cores.size():
cores[slot] = core
_raw_decks[slot] = SpellDeck.new() # 换 Core 后重置对应 Deck
else:
add_core(core, slot)
compiled_decks.resize(cores.size())
func add_spell_to_inventory(spell_id: String, target_core_idx: int = -1) -> void:
var idx := target_core_idx if target_core_idx >= 0 else active_core_idx
if idx >= cores.size(): return
_raw_decks[idx].push(SpellRegistry.get(spell_id))
func add_passive(passive_id: String) -> void:
passives.append(passive_id)
stats.recalculate(passives) # 被动变更后立即重算 PlayerStats
func use_consumable(consumable_id: String) -> void:
# ShopManager 购买 CONSUMABLE 类商品时调用。
# 消耗品效果立即生效（不延迟到 WAVE）；若需要战斗中生效，加入 _pending_consumables 并在 WAVE_INTRO 处理。
var def: ConsumableDef = ConsumableRegistry.get(consumable_id)
if def == null: return
def.apply(self) # ConsumableDef.apply(player: PlayerManager) 直接修改玩家状态
# ── 法杖预编译入口（GameCycleManager 在 SHOP→WAVE_INTRO 时调用）────
func compile_all_wands() -> void:
compiled_decks.resize(cores.size())
for i in cores.size():
compiled_decks[i] = SpellEvaluator.compile_wand(cores[i], _raw_decks[i])
func get_compiled_deck(core_idx: int) -> CompiledDeck:
if core_idx < 0 or core_idx >= compiled_decks.size(): return null
return compiled_decks[core_idx]
func get_raw_deck(core_idx: int) -> SpellDeck:
if core_idx < 0 or core_idx >= _raw_decks.size(): return null
return _raw_decks[core_idx]
func reset() -> void:
hp = hp_max; gold = 0; xp = 0; level = 1
cores.clear(); _raw_decks.clear(); compiled_decks.clear(); passives.clear()
_pending_consumables.clear()
stats.recalculate([])
_position = Vector2.ZERO
```
> **compile_all_wands() 调用时机**：GameCycleManager 的 `SHOP → WAVE_INTRO` 转换回调中调用 `PlayerManager.compile_all_wands()`，而非直接调用 `SpellEvaluator`。这样 PlayerManager 保持对三个 Core 的迭代责任，SpellEvaluator 只负责单个 `compile_wand()` 逻辑。
---
### 5.7 DropManager 框架设计
`DropManager` 订阅 `EventID.ENEMY_KILLED`，负责在敌人位置生成掉落物并处理玩家拾取。
#### 掉落表配置格式
```json
// res://resources/drops/enemy_drops.json
{
"slime_basic": {
"xp": { "min": 2, "max": 4 },
"gold": { "min": 0, "max": 2, "chance": 0.3 },
"spell_drop": { "chance": 0.02, "rarity_max": 1 }
},
"bat_fast": {
"xp": { "min": 3, "max": 5 },
"gold": { "min": 1, "max": 3, "chance": 0.4 },
"spell_drop": { "chance": 0.03, "rarity_max": 2 }
},
"elite": {
"xp": { "min": 15, "max": 25 },
"gold": { "min": 8, "max": 15, "chance": 1.0 },
"spell_drop": { "chance": 0.20, "rarity_max": 3 }
},
"_default": {
"xp": { "min": 2, "max": 3 },
"gold": { "min": 0, "max": 1, "chance": 0.2 },
"spell_drop": { "chance": 0.01, "rarity_max": 1 }
}
}
```
#### DropManager 核心逻辑
```gdscript
# drop_manager.gd (Autoload: DropManager)
# 掉落物在世界空间以 Dictionary 形式存储（无 Node 开销，轻量化）
# { "type": "xp"|"gold"|"spell", "value": Variant, "position": Vector2, "lifetime": float }
var _drops: Array[Dictionary] = []
var _drop_table: Dictionary = {} # 启动时从 JSON 加载
func _ready() -> void:
var raw: String = FileAccess.open("res://resources/drops/enemy_drops.json", FileAccess.READ).get_as_text()
_drop_table = JSON.parse_string(raw)
EventBus.subscribe(EventID.ENEMY_KILLED, _on_enemy_killed)
func _on_enemy_killed(payload: Dictionary) -> void:
var enemy_id: int = payload.get("enemy_id", -1)
var pos: Vector2 = EnemyManager.get_last_position(enemy_id) # 死亡时缓存的位置
var enemy_type: String = EnemyManager.get_type(enemy_id)
var table: Dictionary = _drop_table.get(enemy_type, _drop_table.get("_default", {}))
_spawn_drops(pos, table)
func _spawn_drops(pos: Vector2, table: Dictionary) -> void:
# XP（必定掉落）
var xp_cfg: Dictionary = table.get("xp", {})
var xp_val: int = randi_range(xp_cfg.get("min", 1), xp_cfg.get("max", 2))
_drops.append({"type": "xp", "value": xp_val, "position": pos, "lifetime": 8.0})
# 金币（概率）
var gold_cfg: Dictionary = table.get("gold", {})
if randf() < gold_cfg.get("chance", 0.0):
var g: int = randi_range(gold_cfg.get("min", 1), gold_cfg.get("max", 1))
_drops.append({"type": "gold", "value": g, "position": pos, "lifetime": 10.0})
# 法术卡掉落（低概率）
var spell_cfg: Dictionary = table.get("spell_drop", {})
if randf() < spell_cfg.get("chance", 0.0):
var max_rarity: int = spell_cfg.get("rarity_max", 1)
var spell_id: String = SpellRegistry.random_by_rarity(max_rarity)
if spell_id != "":
_drops.append({"type": "spell", "value": spell_id, "position": pos, "lifetime": 15.0})
func _physics_process(delta: float) -> void:
if GameCycleManager.get_state() != GameCycleManager.GameState.WAVE: return
var player_pos := PlayerManager.get_position()
var pickup_r := PlayerManager.stats.pickup_radius
var i := 0
while i < _drops.size():
var drop := _drops[i]
drop["lifetime"] -= delta
# 拾取检测：圆形距离
if (player_pos - drop["position"]).length_squared() <= pickup_r * pickup_r:
_collect(drop)
_drops.remove_at(i)
elif drop["lifetime"] <= 0.0:
_drops.remove_at(i) # 超时消失（swap-and-pop 可改，当前掉落数量极少，remove_at 可接受）
else:
i += 1
func _collect(drop: Dictionary) -> void:
match drop["type"]:
"xp": PlayerManager.add_xp(drop["value"])
"gold": PlayerManager.add_gold(drop["value"])
"spell": ShopManager.offer_free_spell(drop["value"]) # 弹出"拾取法术"UI提示
```
---
### 5.8 UpgradeSystem 框架设计
每波结算后，玩家从随机 3 张升级词条中选择 1 张。`UpgradeSystem` 管理词条池构建、展示、应用。
#### 升级词条资源格式（UpgradeDef .tres）
```gdscript
# upgrade_def.gd - Resource 子类
class_name UpgradeDef
extends Resource
var upgrade_id: String = "" # 全局唯一，格式：category_effect（如 "offense_damage_plus"）
var display_name: String = "" # tr() KEY
var description: String = "" # tr() KEY，支持 {value} 占位符
var icon_key: String = "" # UIAtlas 图标键
var rarity: int = 1 # 1=Common, 2=Uncommon, 3=Rare, 4=Legendary
var max_stack: int = 1 # 同一词条最多叠取次数（1=不可重复，99=无限）
var value: float = 0.0 # 效果数值（供 description {value} 和 apply() 使用）
# 效果函数：直接修改 PlayerStats 或 PlayerManager 状态
func apply(player: PlayerManager) -> void:
pass # 子类重写，例：player.stats.damage_mult *= 1.1
```
#### UpgradeSystem 核心逻辑
```gdscript
# upgrade_system.gd (Autoload: UpgradeSystem)
const CHOICES_COUNT: int = 3 # 每次展示 3 张词条
var _upgrade_pool: Array[UpgradeDef] = [] # 启动时从 res://resources/upgrades/ 扫描加载
var _taken_counts: Dictionary = {} # { upgrade_id: int } 本次 Run 已取次数（reset 时清零）
func _ready() -> void:
_scan_upgrades()
func _scan_upgrades() -> void:
_upgrade_pool.clear()
var dir := DirAccess.open("res://resources/upgrades/")
if dir:
dir.list_dir_begin()
var fname := dir.get_next()
while fname != "":
if fname.ends_with(".tres"):
var def: UpgradeDef = load("res://resources/upgrades/" + fname)
if def and def.upgrade_id != "": _upgrade_pool.append(def)
fname = dir.get_next()
func build_choices(wave_num: int, rng: RandomNumberGenerator) -> Array[UpgradeDef]:
var weights := _rarity_weights(wave_num)
var available := _pool_filtered() # 过滤已达 max_stack 的词条
var result: Array[UpgradeDef] = []
var seen_ids: Array[String] = []
for _i in CHOICES_COUNT:
var pick := _weighted_pick(available, weights, rng, seen_ids)
if pick:
result.append(pick)
seen_ids.append(pick.upgrade_id)
return result
func apply_choice(upgrade: UpgradeDef) -> void:
upgrade.apply(PlayerManager)
_taken_counts[upgrade.upgrade_id] = _taken_counts.get(upgrade.upgrade_id, 0) + 1
SpellEvaluator.update_max_ops(PlayerManager.stats.cpu_limit)
func _pool_filtered() -> Array[UpgradeDef]:
# 过滤已达 max_stack 的词条（不再可选）
var result: Array[UpgradeDef] = []
for def in _upgrade_pool:
if _taken_counts.get(def.upgrade_id, 0) < def.max_stack:
result.append(def)
return result
func _weighted_pick(pool: Array[UpgradeDef], weights: Array[float],
rng: RandomNumberGenerator, exclude: Array[String]) -> UpgradeDef:
# 按稀有度权重从 pool 中加权随机选一条词条（排除 exclude 中的 ID）
var total := 0.0
for def in pool:
if def.upgrade_id in exclude: continue
total += weights[clamp(def.rarity - 1, 0, 3)]
if total <= 0.0: return null
var roll := rng.randf() * total
for def in pool:
if def.upgrade_id in exclude: continue
roll -= weights[clamp(def.rarity - 1, 0, 3)]
if roll <= 0.0: return def
return pool[-1] if not pool.is_empty() else null
func _rarity_weights(wave_num: int) -> Array[float]:
var common_w := max(5.0, 60.0 - wave_num * 2.5)
var uncommon_w := min(50.0, 30.0 + wave_num * 1.5)
var rare_w := min(30.0, max(5.0, wave_num * 1.2 - 5.0))
var legendary_w := min(10.0, max(0.0, wave_num * 0.5 - 8.0))
return [common_w, uncommon_w, rare_w, legendary_w]
func reset() -> void:
_taken_counts.clear()
```
> **GameCycleManager 集成**：`WAVE_RESULT` 状态的 `_on_enter()` 中调用 `UpgradeSystem.build_choices(wave_num, _rng)` 获取词条列表，UIManager 展示 3 张升级卡；玩家选择后调用 `UpgradeSystem.apply_choice(selected)` → 直接返回 `GameCycleManager.transition_to(SHOP)`。
---
### 5.9 BossManager 架构设计
Boss 是具有多阶段 HP 和特殊行为的特殊敌人。`BossManager` 是 `EnemyManager` 的协调层，不持有独立的 SoA 数据，而是通过 EnemyManager 的接口操作 Boss 实体并监听阶段切换。
#### BossManager 与 EnemyManager 的关系
| 职责 | 归属 | 理由 |
| :--- | :--- | :--- |
| Boss 物理位置 / Boid 运动 | `EnemyManager` SoA | Boss 也是"敌人"，共享同一物理系统 |
| Boss HP 存储 | `EnemyManager._enemy_data` | EnemyManager 统一管理存活/死亡状态 |
| 阶段切换逻辑 / 特殊能力触发 | `BossManager` | 阶段是 Boss 专有行为，不属于通用敌人 |
| Boss 碰撞体（多区域） | `BossManager` 管理多个 Area2D / 自定义 AABB | Boss 半径可达 200px，超过 SpatialGrid 标准弹体阈值，走 `EnemyManager.query_aabb(boss_aabb)` |
#### BossManager 核心设计
```gdscript
# boss_manager.gd (Autoload: BossManager)
# Boss 阶段定义（每个 Boss 的阶段配置在其对应 JSON 中定义）
# boss_design.md §6 详细描述各 Boss 行为，BossManager 仅处理通用框架
var _boss_entity_id: int = -1 # 当前 Boss 在 EnemyManager 中的 entity_id（-1 = 无 Boss）
var _current_phase: int = 0
var _phase_thresholds: Array[float] = [] # HP 百分比阈值（降序），如 [1.0, 0.6, 0.3]
var _is_active: bool = false
var _boss_size_cache: Dictionary = {} # spawn_boss 时缓存的 Boss 配置（含 collision_radius）
# WaveManager 在 is_boss_wave=true 时调用
func spawn_boss(boss_id: String, position: Vector2) -> void:
_boss_entity_id = EnemyManager.spawn(boss_id, position)
var cfg: Dictionary = _load_boss_config(boss_id)
_boss_size_cache = cfg
_phase_thresholds = cfg.get("phase_hp_thresholds", [1.0, 0.6, 0.3])
_current_phase = 0
_is_active = true
EventBus.emit(EventID.BOSS_PHASE_CHANGED, {
"boss_id": boss_id, "phase": 0, "bgm_layer": "boss"
})
func _physics_process(_delta: float) -> void:
if not _is_active or _boss_entity_id < 0: return
var hp_pct: float = EnemyManager.get_hp_percent(_boss_entity_id)
# 检测阶段切换（阈值降序，phase 0→1→2）
var next_phase := _current_phase
for i in range(_current_phase + 1, _phase_thresholds.size()):
if hp_pct <= _phase_thresholds[i]:
next_phase = i
if next_phase != _current_phase:
_current_phase = next_phase
_on_phase_changed(_current_phase)
func _on_phase_changed(phase: int) -> void:
EventBus.emit(EventID.BOSS_PHASE_CHANGED, {
"boss_id": EnemyManager.get_type(_boss_entity_id),
"phase": phase, "bgm_layer": "boss_phase_%d" % phase
})
# 触发特殊技能（如护盾、新 spawn pattern、移速变化）
# 具体行为由 boss_design.md §6 的各 Boss 脚本重写 _on_phase_enter(phase)
func _on_enemy_killed(payload: Dictionary) -> void:
if payload.get("enemy_id", -1) != _boss_entity_id: return
_is_active = false
_boss_entity_id = -1
EventBus.emit(EventID.BOSS_KILLED, {
"boss_id": EnemyManager.get_type(payload["enemy_id"]),
"wave_num": WaveManager.wave_num
})
# WaveManager 订阅 BOSS_KILLED 后发出 WAVE_COMPLETE（kill_boss clear_condition）
func reset() -> void:
_boss_entity_id = -1; _current_phase = 0; _is_active = false
_phase_thresholds.clear()
# ── 只读查询接口（BulletManager 碰撞检测 + UIManager Boss 血条）────
func is_active() -> bool: return _is_active
func get_boss_entity_id() -> int: return _boss_entity_id
func get_collision_rect() -> Rect2:
# Boss 碰撞 AABB（BulletManager 使用，用于超大碰撞体绕过 SpatialGrid）
if not _is_active: return Rect2()
var pos := EnemyManager.get_last_position(_boss_entity_id) # Boss 仍存活时 get_last_position 返回当前位置
var cfg: Dictionary = _boss_size_cache # spawn_boss 时从 _load_boss_config 读取 "collision_radius"
var r: float = cfg.get("collision_radius", 80.0)
return Rect2(pos.x - r, pos.y - r, r * 2, r * 2)
func _load_boss_config(boss_id: String) -> Dictionary:
# 从 res://resources/bosses/{boss_id}.json 加载 Boss 配置（同步加载，spawn 时调用一次）
var path := "res://resources/bosses/%s.json" % boss_id
if not FileAccess.file_exists(path):
push_warning("BossManager: boss config not found: %s" % path)
return {}
var raw: String = FileAccess.open(path, FileAccess.READ).get_as_text()
return JSON.parse_string(raw)
# 配置字段（规范）：
# { "phase_hp_thresholds": [1.0, 0.6, 0.3],
# "collision_radius": 80.0,
# "spawn_pattern": "center",
# "phase_actions": { "1": "spawn_minions", "2": "enrage" } }
```
#### Boss 碰撞策略
Boss 半径通常 > 64px（超过 `LARGE_PROJECTILE_THRESHOLD`），使用与"超大弹体豁免"对称的策略：
```gdscript
# BulletManager 子弹命中检测（_physics_process 中，SpatialGrid 路径）
# 超大碰撞体（Boss）同样绕过 SpatialGrid，改用 Boss 自定义 AABB 全量测试
if BossManager.is_active():
var boss_aabb: Rect2 = BossManager.get_collision_rect()
for i in _active_count:
var bx := _data[i * BULLET_STRIDE]; var by := _data[i * BULLET_STRIDE + 1]
if boss_aabb.has_point(Vector2(bx, by)):
_on_bullet_hit(i, BossManager.get_boss_entity_id())
```
---
### 5.10 UIManager 架构设计
`UIManager` 是 UI 系统的唯一协调者，订阅 `GameCycleManager` 的状态变化，驱动各 UI 场景的显示/隐藏。业务逻辑（金币计算、法术编译）由各业务 Manager 负责；UIManager 只负责**路由**（什么状态显示什么界面）和 **View 刷新**（将数据渲染到 Control 节点）。
#### 职责边界
| 职责 | 归属 | 理由 |
| :--- | :--- | :--- |
| 游戏状态判断（什么时候进入商店）| `GameCycleManager` | 状态机唯一持有状态 |
| UI 场景切换（show/hide CanvasLayer 子场景）| `UIManager` | UI 协调者唯一职责 |
| 数据计算（价格/稀有度/词条效果）| `ShopManager` / `UpgradeSystem` | 与 UI 无关，可独立测试 |
| Control 节点刷新（Label.text / ProgressBar.value）| UIManager 各子函数 | 表现层 |
| 玩家操作确认（点击购买/选择词条）| UIManager → 调用对应 Manager 接口 | 控制流 |
#### UIManager 数据模型
```gdscript
# ui_manager.gd (Autoload: UIManager)
# ── 各 UI 场景实例（懒加载，首次显示时实例化）────────────────────
var _shop_ui: Control = null # res://scenes/ui/ShopUI.tscn
var _inventory_ui: Control = null # res://scenes/ui/InventoryUI.tscn
var _upgrade_ui: Control = null # res://scenes/ui/UpgradeChoiceUI.tscn
var _hud: Control = null # res://scenes/ui/HUD.tscn（BattleScene 挂载时创建）
var _main_menu: Control = null # res://scenes/ui/MainMenuUI.tscn
var _game_over: Control = null # res://scenes/ui/GameOverUI.tscn
var _pause_menu: Control = null # res://scenes/ui/PauseMenuUI.tscn
# ── RNG（用于 UpgradeSystem.build_choices 的确定性种子）──────────
var _rng: RandomNumberGenerator = RandomNumberGenerator.new()
# _rng.seed 在每次进入 WAVE_RESULT 状态时重置（保持波次间确定性）
# ── 伤害数字池 ──────────────────────────────────────────────────
const MAX_DAMAGE_NUMBERS: int = 30
var _dmg_num_pool: Array[Label] = [] # 飘字 Label 池（重复利用，减少节点创建）
var _dmg_num_active: int = 0
func _ready() -> void:
EventBus.subscribe(EventID.GAME_STATE_CHANGED, _on_state_changed)
EventBus.subscribe(EventID.PLAYER_DAMAGED, _on_player_damaged)
EventBus.subscribe(EventID.ENEMY_KILLED, _on_enemy_killed)
EventBus.subscribe(EventID.SPELL_DROP_PICKUP, _on_spell_drop_pickup)
# 预分配伤害数字池
for i in MAX_DAMAGE_NUMBERS:
var lbl := Label.new()
lbl.visible = false
add_child(lbl)
_dmg_num_pool.append(lbl)
```
#### 状态→UI 路由表
`GameCycleManager` 在每次 `transition_to(next)` 末尾发送 `EventID.GAME_STATE_CHANGED`（payload: `{prev, next}`），UIManager 的 `_on_state_changed` 根据下表切换：
| GameState | 显示的 UI | 隐藏的 UI | 附加操作 |
| :--- | :--- | :--- | :--- |
| `MAIN_MENU` | MainMenuUI | 其他全部 | 停止 HUD |
| `LOADING` | 无（过渡遮罩由 GameCycleManager 驱动）| 其他 | — |
| `SHOP` | ShopUI | HUD, InventoryUI | `_refresh_shop_ui()` |
| `WAVE_INTRO` | HUD（波次预告）| ShopUI, UpgradeUI | `_show_wave_intro_banner()` |
| `WAVE` | HUD | 其他 | 激活伤害数字池 |
| `WAVE_RESULT` | UpgradeChoiceUI（3 张词条）| HUD | `_refresh_upgrade_choices()` |
| `GAME_OVER` | GameOverUI | 其他 | 显示分数/波次 |
| `GAME_CLEARED` | GameOverUI（通关变体）| 其他 | 显示 Endless 入口 |
| `PAUSE` | PauseMenuUI（叠加当前 UI）| — | `get_tree().paused = true` |
```gdscript
func _on_state_changed(payload: Dictionary) -> void:
var next: int = payload.get("next", -1)
_hide_all_ui()
match next:
GameCycleManager.GameState.MAIN_MENU: _show(_main_menu, "res://scenes/ui/MainMenuUI.tscn")
GameCycleManager.GameState.SHOP:
_show(_shop_ui, "res://scenes/ui/ShopUI.tscn")
_refresh_shop_ui()
GameCycleManager.GameState.WAVE_INTRO: _show(_hud, "res://scenes/ui/HUD.tscn"); _show_wave_intro_banner()
GameCycleManager.GameState.WAVE: _show(_hud, "res://scenes/ui/HUD.tscn")
GameCycleManager.GameState.WAVE_RESULT:
_show(_upgrade_ui, "res://scenes/ui/UpgradeChoiceUI.tscn")
_refresh_upgrade_choices()
GameCycleManager.GameState.GAME_OVER,\
GameCycleManager.GameState.GAME_CLEARED:
_show(_game_over, "res://scenes/ui/GameOverUI.tscn")
GameCycleManager.GameState.PAUSE:
_show(_pause_menu, "res://scenes/ui/PauseMenuUI.tscn")
get_tree().paused = true
func _show(ref: Control, scene_path: String) -> Control:
if ref == null:
ref = load(scene_path).instantiate()
add_child(ref) # UIManager Autoload 自身作为父节点（跨场景持久）
ref.visible = true
return ref
func _hide_all_ui() -> void:
for ui in [_shop_ui, _inventory_ui, _upgrade_ui, _hud, _main_menu, _game_over, _pause_menu]:
if ui: ui.visible = false
get_tree().paused = false # 确保 PAUSE 状态退出时解除暂停
```
#### 伤害数字池接口
```gdscript
func show_damage_number(amount: float, position: Vector2, is_crit: bool = false) -> void:
# 每帧最多弹出 10 个（帧节流由调用方 BulletManager 批处理）
var lbl := _acquire_dmg_label()
if lbl == null: return
lbl.text = str(int(amount)) + ("!" if is_crit else "")
lbl.modulate = Color.RED if is_crit else Color.WHITE
lbl.global_position = position
lbl.visible = true
# 0.6s 飘字动画后归还池（使用 Tween，避免 Timer 节点堆叠）
var tween := create_tween()
tween.tween_property(lbl, "global_position", position + Vector2(0, -40), 0.6)
tween.parallel().tween_property(lbl, "modulate:a", 0.0, 0.6)
tween.tween_callback(func(): lbl.visible = false; _dmg_num_active -= 1)
func _acquire_dmg_label() -> Label:
if _dmg_num_active >= MAX_DAMAGE_NUMBERS: return null
for lbl in _dmg_num_pool:
if not lbl.visible:
_dmg_num_active += 1
return lbl
return null
```
#### ShopUI 刷新协议
```gdscript
func _refresh_shop_ui() -> void:
# ShopManager.get_slots() 返回当前 SLOT_COUNT=6 个商品 Dictionary
var slots: Array = ShopManager.get_slots()
_shop_ui.refresh(slots, PlayerManager.gold, WaveManager.wave_num)
# ShopUI.refresh() 是 Control 层函数，仅做 Label/Icon 更新，无业务逻辑
func _refresh_upgrade_choices() -> void:
var choices: Array[UpgradeDef] = UpgradeSystem.build_choices(WaveManager.wave_num, _rng)
_upgrade_ui.show_choices(choices) # UpgradeChoiceUI 展示 3 张卡
func _on_upgrade_selected(upgrade: UpgradeDef) -> void:
# UpgradeChoiceUI 发送信号，UIManager 接收后调用业务层
UpgradeSystem.apply_choice(upgrade)
GameCycleManager.transition_to(GameCycleManager.GameState.SHOP)
func _on_spell_drop_pickup(payload: Dictionary) -> void:
# DropManager 拾取法术卡后通过 EventBus 通知，UIManager 弹出提示
var spell_id: String = payload.get("spell_id", "")
var auto_equip: bool = payload.get("auto_equip", false)
if auto_equip:
PlayerManager.add_spell_to_inventory(spell_id)
else:
# 弹出"装备到哪个Core？"选择框
_show_spell_pickup_dialog(spell_id)
```
---
### 5.11 PassiveDef + PassiveRegistry 设计
被动词条是 Roguelite 构建深度的核心扩展机制。`PassiveRegistry` 与 `SpellRegistry` 采用对称设计，启动时从资源目录扫描加载。
#### PassiveDef Resource 格式
```gdscript
# passive_def.gd - Resource 子类
class_name PassiveDef
extends Resource
var passive_id: String = "" # 全局唯一，格式：category_stat（如 "offense_damage_mult"）
var display_name: String = "" # tr() KEY，UI 显示用
var description: String = "" # tr() KEY，支持 {value} 占位符（如 "+{value}% 伤害"）
var icon_key: String = "" # UIAtlas 图标键（ADR-C1：必须有对应形状标识）
var rarity: int = 1 # 1=Common, 2=Uncommon, 3=Rare, 4=Legendary
var max_stack: int = 1 # 同一被动最多叠取次数（1=不可重复购买，99=无限）
var value: float = 0.0 # 效果数值（description {value} 占位符的填充值）
# ── 效果：修改 PlayerStats 的规则 ───────────────────────────────
# 支持三种效果模式（enum 选一）：
enum StatPatchMode { ADD, MULTIPLY, OVERRIDE }
var stat_field: String = "" # PlayerStats 中被修改的字段名（如 "damage_mult"）
var patch_mode: StatPatchMode = StatPatchMode.MULTIPLY
var patch_value: float = 1.0 # ADD: +patch_value；MULTIPLY: *patch_value；OVERRIDE: =patch_value
func apply_to(stats: PlayerStats) -> void:
if stat_field == "": return
var current: float = stats.get(stat_field)
match patch_mode:
StatPatchMode.ADD: stats.set(stat_field, current + patch_value)
StatPatchMode.MULTIPLY: stats.set(stat_field, current * patch_value)
StatPatchMode.OVERRIDE: stats.set(stat_field, patch_value)
```
> **设计约束**：`apply_to()` 只修改 `PlayerStats` 中的 float 字段，不直接修改 `PlayerManager` 的 HP/Gold/XP（防止被动产生经济副作用）。需要修改资源上限（如 `hp_max_bonus`）的被动，通过 `stats.hp_max_bonus` 间接影响，`PlayerManager` 在 `recalculate()` 后重算 `hp_max = 100.0 + stats.hp_max_bonus`。
#### PassiveRegistry Autoload
```gdscript
# passive_registry.gd (Autoload: PassiveRegistry)
var _registry: Dictionary = {} # { passive_id: PassiveDef }
var _by_rarity: Array[Array] = [[], [], [], []] # 与 SpellRegistry 对称
func _ready() -> void:
var dir := DirAccess.open("res://resources/passives/")
if dir:
dir.list_dir_begin()
var fname := dir.get_next()
while fname != "":
if fname.ends_with(".tres"):
var def: PassiveDef = load("res://resources/passives/" + fname)
if def and def.passive_id != "":
_registry[def.passive_id] = def
_by_rarity[clamp(def.rarity - 1, 0, 3)].append(def.passive_id)
fname = dir.get_next()
func get(passive_id: String) -> PassiveDef:
return _registry.get(passive_id, null)
func has(passive_id: String) -> bool:
return _registry.has(passive_id)
func all() -> Array:
return _registry.values() # Array[PassiveDef]（ShopManager 构建权重池用）
```
#### 被动词条设计示例（资源文件）
```gdscript
# res://resources/passives/offense_damage_mult_10pct.tres
passive_id = "offense_damage_mult_10pct"
display_name = "PASSIVE_DAMAGE_MULT_NAME" # tr() 键
description = "PASSIVE_DAMAGE_MULT_DESC" # tr() → "全局伤害 +{value}%"
icon_key = "icon_sword_up"
rarity = 1 # Common
max_stack = 5 # 最多叠取 5 次（最终 damage_mult = 1.1^5 ≈ 1.61）
value = 10.0 # 描述占位符：+10%
stat_field = "damage_mult"
patch_mode = StatPatchMode.MULTIPLY
patch_value = 1.1 # 每次叠取：damage_mult *= 1.1
```
---
### 5.11.A SpellRegistry 接口定义
`SpellRegistry` 是纯只读 Autoload，启动时扫描 `res://resources/spells/` 并加载所有 `SpellNode .tres` 文件，之后提供 O(1) / O(稀有度桶) 查询。
```gdscript
# spell_registry.gd (Autoload: SpellRegistry)
var _registry: Dictionary = {} # { spell_id: SpellNode }
var _by_rarity: Array[Array] = [[], [], [], []] # index = rarity-1，每组为 Array[String](spell_id列表)
func _ready() -> void:
var dir := DirAccess.open("res://resources/spells/")
if dir:
dir.list_dir_begin()
var fname := dir.get_next()
while fname != "":
if fname.ends_with(".tres"):
var node: SpellNode = load("res://resources/spells/" + fname)
if node and node.spell_id != "":
_registry[node.spell_id] = node
var ri := clamp(node.rarity - 1, 0, 3)
_by_rarity[ri].append(node.spell_id)
fname = dir.get_next()
func get(spell_id: String) -> SpellNode:
return _registry.get(spell_id, null)
func has(spell_id: String) -> bool:
return _registry.has(spell_id)
func all() -> Array:
return _registry.values() # Array[SpellNode]（用于 ShopManager 构建权重池）
func random_by_rarity(max_rarity: int, rng: RandomNumberGenerator = null) -> String:
# DropManager 使用：从稀有度 1~max_rarity 的所有法术中随机选一个 ID
# rng 为 null 时使用全局随机（掉落不需要确定性种子）
var pool: Array[String] = []
for r in range(min(max_rarity, 4)):
pool.append_array(_by_rarity[r])
if pool.is_empty(): return ""
if rng: return pool[rng.randi() % pool.size()]
return pool[randi() % pool.size()]
```
---
### 5.14 ProfileManager / SaveSystem 框架设计
`ProfileManager` 是持久化层的统一入口，负责 **Run 运行时存档** 和 **全局设置/统计** 的读写。权威实现详见 `implementation_plan.md §2.5.E` 和 `ADR-A2`，本节为接口契约。
#### 职责边界
- **负责**：JSON 文件读写（A/B 双槽写、CRC 校验）、schema 版本迁移、Run 状态持久化、全局设置持久化
- **不负责**：游戏逻辑、排行榜 HMAC（EndlessRecordsManager 负责）
```gdscript
# profile_manager.gd (Autoload: ProfileManager)
# Run 存档：user://run_a.json（A槽）+ user://run_b.json（B槽）（权威来源：ADR-A2、certification_checklist.md ST-51）
# 全局设置：user://save_data.json（音量/无障碍等，非 Run 数据）
# schema_version 必须与 ADR-A2 中的 _migrate 链同步
const SCHEMA_VERSION: int = 1 # 每次 save 结构变更时递增
# ── 全局持久化（设置/统计，非 Run）────────────────────────────────
func get_float(key: String, default_val: float = 0.0) -> float:
return _global.get(key, default_val)
func set_float(key: String, value: float) -> void:
_global[key] = value; _dirty = true
func get_int(key: String, default_val: int = 0) -> int:
return int(_global.get(key, default_val))
func set_int(key: String, value: int) -> void:
_global[key] = value; _dirty = true
# ── Run 状态存档（ADR-A2 §2 波次结束自动存档）────────────────────
func save_run(run_data: Dictionary) -> void:
# A/B 双槽交替写入（ADR-A2 防断电损坏协议）
run_data["schema_version"] = SCHEMA_VERSION
var which := get_int("run_write_slot", 0)
var path_a := "user://run_a.json"; var path_b := "user://run_b.json"
_write_json(path_a if which == 0 else path_b, run_data)
set_int("run_write_slot", 1 - which)
func load_run() -> Dictionary:
# 优先读 A 槽；A 槽损坏则降级读 B 槽；均损坏则返回 {}（GameCycleManager 展示损坏提示）
var data := _read_json("user://run_a.json")
if data.is_empty():
data = _read_json("user://run_b.json")
if not data.is_empty():
data = _migrate(data)
return data
func has_run() -> bool:
# GameCycleManager 启动时查询是否有未完成的 Run
return not load_run().is_empty()
func clear_run() -> void:
# Run 结束（通关/死亡）后调用，删除 Run 存档（保留全局设置/统计）
_write_json("user://run_a.json", {})
_write_json("user://run_b.json", {})
func get_run_seed() -> int:
# ShopManager 确定性种子（新 Run 开始时写入，存档后恢复）
return get_int("run_seed", 0)
func get_run_count() -> int:
return get_int("run_count", 0)
func flush() -> void:
# 保存全局设置（音量、无障碍等）→ user://save_data.json（与 Run 存档 run_a/b.json 分离）
# 由 SettingsManager.save_audio_setting 触发或 App 退出时调用
if _dirty: _write_json("user://save_data.json", _global); _dirty = false
func _migrate(data: Dictionary) -> Dictionary:
# ADR-A2 §3：链式迁移，v0→v1→v2...
var v: int = data.get("schema_version", 0)
if v < 1: data = _migrate_v0_to_v1(data)
return data
```
---
### 5.15 SettingsManager 框架设计
`SettingsManager` 是游戏设置的运行时接口，持久化委托给 `ProfileManager.flush()`。
```gdscript
# settings_manager.gd (Autoload: SettingsManager)
# 依赖：ProfileManager（持久化）、AudioBusID（音量），EventBus（SETTINGS_CHANGED 通知）
func _ready() -> void:
load_audio_settings() # 恢复持久化音量
_apply_accessibility_settings() # 高对比度、字体缩放、减少闪烁
# ── 音量（ADR-A3.4）────────────────────────────────────────────────
# 见 ADR-A3.4 伪代码（load_audio_settings / save_audio_setting）
# ── 无障碍功能（ADR-C1）───────────────────────────────────────────
func set_colorblind_mode(mode: String) -> void:
# mode: "normal" / "protanopia" / "deuteranopia"（见 ADR-C1.1）
ProfileManager.set_int("colorblind_mode", ["normal","protanopia","deuteranopia"].find(mode))
EventBus.emit(EventID.SETTINGS_CHANGED, { "key": "colorblind_mode" })
func set_font_scale(scale: float) -> void:
ProfileManager.set_float("font_scale", clampf(scale, 0.8, 1.5))
_apply_font_scale()
EventBus.emit(EventID.SETTINGS_CHANGED, { "key": "font_scale" })
func set_reduce_flash(enabled: bool) -> void:
ProfileManager.set_int("reduce_flash", int(enabled))
EventBus.emit(EventID.SETTINGS_CHANGED, { "key": "reduce_flash" })
func set_high_contrast(enabled: bool) -> void:
ProfileManager.set_int("high_contrast", int(enabled))
_apply_high_contrast()
EventBus.emit(EventID.SETTINGS_CHANGED, { "key": "high_contrast" })
func apply_settings() -> void:
# UIManager 在 SettingsUI 打开时调用，刷新所有设置为持久化值
load_audio_settings()
_apply_accessibility_settings()
func get_volume(save_key: String) -> float:
# UIManager 音量滑块初始化时调用
return ProfileManager.get_float(save_key, 0.0)
func _apply_accessibility_settings() -> void:
_apply_font_scale()
_apply_high_contrast()
func _apply_font_scale() -> void:
var scale: float = ProfileManager.get_float("font_scale", 1.0)
# 遍历所有 Label / RichTextLabel 节点并设置 theme_override_font_sizes
pass # 见 ADR-C1.3
func _apply_high_contrast() -> void:
pass # 切换 CanvasItem 材质 Shader uniform；见 ADR-C1.4
```
---
### 5.11.B CoreRegistry + ConsumableRegistry + ConsumableDef
`CoreRegistry` 和 `ConsumableRegistry` 与 `SpellRegistry` / `PassiveRegistry` 采用对称模式，补全 `PlayerManager.replace_core()` 和 `use_consumable()` 的依赖链。
```gdscript
# ── core_registry.gd (Autoload: CoreRegistry) ──────────────────────────────
# 扫描 res://resources/cores/ 目录，加载所有 CoreDefinition .tres 文件
var _registry: Dictionary = {} # { core_id: CoreDefinition }
func _ready() -> void:
var dir := DirAccess.open("res://resources/cores/")
if dir:
dir.list_dir_begin()
var fname := dir.get_next()
while fname != "":
if fname.ends_with(".tres"):
var def: CoreDefinition = load("res://resources/cores/" + fname)
if def and def.core_id != "": _registry[def.core_id] = def
fname = dir.get_next()
func get(core_id: String) -> CoreDefinition: return _registry.get(core_id, null)
func has(core_id: String) -> bool: return _registry.has(core_id)
func all() -> Array: return _registry.values()
# ── consumable_def.gd ───────────────────────────────────────────────────────
class_name ConsumableDef
extends Resource
var consumable_id: String = "" # 全局唯一，格式：consumable_effect（如 "hp_potion_50"）
var display_name: String = "" # tr() KEY
var description: String = "" # tr() KEY，支持 {value} 占位符
var icon_key: String = "" # UIAtlas 图标键
var price: int = 8 # 商店默认价格（金币）
var value: float = 0.0 # 效果数值
func apply(player: PlayerManager) -> void:
pass # 子类重写，或通过 effect_type + value 驱动（参考 PassiveDef.apply_to 模式）
# 示例子类：HP 药水 → player.heal(value)；速度水 → player.stats.move_speed += value（本回合）
# ── consumable_registry.gd (Autoload: ConsumableRegistry) ──────────────────
var _registry: Dictionary = {} # { consumable_id: ConsumableDef }
func _ready() -> void:
var dir := DirAccess.open("res://resources/consumables/")
if dir:
dir.list_dir_begin()
var fname := dir.get_next()
while fname != "":
if fname.ends_with(".tres"):
var def: ConsumableDef = load("res://resources/consumables/" + fname)
if def and def.consumable_id != "": _registry[def.consumable_id] = def
fname = dir.get_next()
func get(consumable_id: String) -> ConsumableDef: return _registry.get(consumable_id, null)
func all() -> Array: return _registry.values()
```
> **ShopManager 商品池补充**：`ShopItemType.CONSUMABLE` 与 `ShopItemType.CORE` 商品由特定波次固定投放（不进入随机权重池），即 Boss 波前固定刷出 Core 槽位、每波随机出现 1 消耗品。`_build_weighted_pool` 仅负责 SPELL + PASSIVE；CONSUMABLE/CORE 槽位由 `_fill_fixed_slots()` 在 `_fill_slots()` 中单独填充。
---
### 5.12 MinionManager 架构设计
`MinionManager` 管理玩家召唤物（友方单位）的生命周期，与 `EnemyManager` 共享 `SpatialGrid` 但 faction 位不同（`+6 高16位 = 1`）。召唤物数量上限较小（通常 ≤ 16），不需要 C# 热路径。
#### 职责边界
- **不处理**：战斗逻辑（委托 SpellEvaluator / StatusManager）、敌人碰撞（委托 BulletManager）
- **负责**：召唤物生命周期（spawn/expire/recall）、最大上限控制、事件通知（MINION_SPAWNED/MINION_EXPIRED）
```gdscript
# minion_manager.gd (Autoload: MinionManager)
const MAX_MINIONS: int = 16 # 全局最大召唤物数量
const DEFAULT_LIFETIME: float = 30.0 # 默认存活秒数（可被 MinionDef 覆盖）
var _minions: Array[Dictionary] = [] # 活跃召唤物列表，每项：{ id, owner_id, def, lifetime_rem, node }
var _next_id: int = 0
func spawn_minion(def: MinionDef, owner_id: int, pos: Vector2) -> int:
# 返回 minion_id；若已达 MAX_MINIONS，先 expire 最旧的（先进先出策略）
# 发出 EventID.MINION_SPAWNED
if _minions.size() >= MAX_MINIONS:
_expire(_minions[0].id)
var id := _next_id
_next_id = (_next_id + 1) % 100000
var entry := { "id": id, "owner_id": owner_id, "def": def,
"lifetime_rem": def.lifetime if def.lifetime > 0 else DEFAULT_LIFETIME,
"pos": pos }
_minions.append(entry)
EventBus.emit(EventID.MINION_SPAWNED, { "minion_id": id, "owner_id": owner_id,
"current_count": _minions.size() })
return id
func recall_all(owner_id: int) -> void:
# 立即移除 owner_id 的所有召唤物（玩家死亡 / Run 结束时调用）
var to_expire := _minions.filter(func(m): return m.owner_id == owner_id)
for m in to_expire: _expire(m.id)
func get_count(owner_id: int = -1) -> int:
# owner_id = -1 时返回所有召唤物总数
if owner_id < 0: return _minions.size()
return _minions.filter(func(m): return m.owner_id == owner_id).size()
func fill_pos_snapshot(out: PackedFloat32Array, out_ids: PackedInt32Array) -> int:
# ⚠️ 未实现（设计提案）。原注写「BulletManager homing 查询友方召唤物」，但 2026-07-30 落地的
# 归航只锁定敌人（经 _find_nearest_unvisited + SpatialGrid，不消费任何位置快照），
# 敌方/友方召唤物寻的尚未立项。此处保留仅为 MinionManager 自身的 SoA 导出提案。
# 返回写入数量；out 格式: [x0, y0, x1, y1, ...]；out_ids 同步给出 entity_id
var n := 0
for m in _minions:
out[n * 2] = m.pos.x
out[n * 2 + 1] = m.pos.y
out_ids[n] = m.id
n += 1
return n
func _physics_process(delta: float) -> void:
var i := 0
while i < _minions.size():
_minions[i].lifetime_rem -= delta
if _minions[i].lifetime_rem <= 0.0:
_expire(_minions[i].id)
else:
i += 1
func _expire(minion_id: int) -> void:
for i in _minions.size():
if _minions[i].id == minion_id:
var owner := _minions[i].owner_id
_minions.remove_at(i)
EventBus.emit(EventID.MINION_EXPIRED, { "minion_id": minion_id, "owner_id": owner,
"current_count": _minions.size() })
return
func reset() -> void:
# GameCycleManager._reset_all_managers() 调用
_minions.clear(); _next_id = 0
```
> **MinionDef Resource**：`res://resources/minions/{id}.tres`，字段：`minion_id: String`、`lifetime: float`（≤0 使用默认值）、`move_speed: float`、`damage_mult: float`、`spell_deck_id: String`（召唤物使用的法术）。
---
### 5.13 VFXManager 框架设计
`VFXManager` 管理战斗特效的播放与回收，基于对象池避免运行时节点创建。权威实现参见 `implementation_plan.md §2.5.D`，本节为 §5 级接口契约（供其他 Manager 调用）。
#### 职责边界
- **不处理**：音效（AudioManager 负责）、伤害数字（UIManager 负责）
- **负责**：粒子/精灵特效生命周期（play/stop/reset）、命中火花（spawn_hit_vfx）、区域特效（play_zone）
```gdscript
# vfx_manager.gd (Autoload: VFXManager)
# C# 热路径：无（特效数量有限，GDScript 对象池足够）
const MAX_ACTIVE_VFX: int = 64 # 同时活跃特效上限（超出时丢弃最旧）
# 订阅事件（_ready() 注册）：
# EventID.BULLET_HIT → spawn_hit_vfx("hit_spark", world_pos)
# EventID.ENEMY_KILLED → play("death_burst", enemy_pos)
# EventID.STATUS_APPLIED → play("status_" + type_name, target_pos)
# EventID.SPELL_CAST_BEGIN→ play("cast_flash", caster_pos)
# EventID.BOSS_PHASE_CHANGED → play("boss_phase_" + phase, boss_pos)
func play(effect_id: String, world_pos: Vector2, scale: float = 1.0) -> int:
# 从池中取出一个特效节点并播放；返回 vfx_handle（用于 stop）
# effect_id 对应 res://scenes/vfx/{effect_id}.tscn
pass # 具体实现见 implementation_plan.md §2.5.D
func stop(vfx_handle: int) -> void:
# 立即停止并回收特效节点（用于持续特效提前结束，如召唤物消失）
pass
func play_zone(zone_type_id: int, world_pos: Vector2, radius: float,
duration: float) -> int:
# 为 ZoneManager 显示区域特效（持续型，duration 秒后自动停止）
# zone_type_id 对应 ZoneManager 的 zone_type_id，映射到 "zone_{type}" 特效
return play("zone_%d" % zone_type_id, world_pos, radius / 64.0)
func spawn_hit_vfx(hit_type: String, world_pos: Vector2) -> void:
# BulletManager BULLET_HIT 事件处理；hit_type：spark / elemental_X / critical
play("hit_" + hit_type, world_pos, 1.0)
func reset() -> void:
# GameCycleManager._reset_all_managers() 调用，停止并归还所有活跃特效节点
pass # 具体实现见 implementation_plan.md §2.5.D（遍历 _active_pool，调用 stop/归还）
```
> **与 implementation_plan.md 的关系**：`impl §2.5.D` 为完整实现（含池管理细节），本节 §5.13 为接口契约层（供其他 Manager 查阅可调用的 API）。两者互为补充，实现时以 impl §2.5.D 为基础，函数签名以本节为准。
---
## 6. 技术栈选型总结
| 模块 | 方案 | 理由 |
| :--- | :--- | :--- |
| **引擎** | Godot 4.x | 开源免费，2D 性能强，内置物理/动画系统完善 |
| **语言** | GDScript + C#（静态职责划分，见 §6.1） | 非主备关系：GDScript 负责快迭代域（UI / 事件 / 配置 / 游戏循环 / 法术预编译），C# 负责计算密集热路径（`BulletManager` / `EnemyManager` / `SpatialGrid` / `SpellEvaluator` 内层循环）；热数据通过 `PackedFloat32Array.AsSpan()` 零拷贝共享；详见 §6.1 |
| **ECS框架** | Custom Lite (Autoload Manager-based) | 利用 Godot Autoload 实现 Manager 单例，针对本项目定制，避免引入第三方 ECS 库 |
| **物理** | Custom SpatialGrid（主力）+ Godot Area2D（低密度启动路径） | < 200 弹幕：Area2D 信号回调；200+ 弹幕：SpatialGrid dirty-list **主力碰撞**；详见 §4.3 |
| **渲染批次** | MultiMeshInstance2D | 极大量同类子弹用 MultiMesh 渲染，最小化 Draw Call |
| **UI** | Godot Control + 自定义虚拟列表 | 背包道具可能很多，需要虚拟列表优化 |
| **配置** | JSON + GDScript 类型注解（或 .tres Resource） | JSON 灵活易热更；Resource 文件可享受 Godot 编辑器集成 |
### 6.1 语言职责分工 (Language Partition)
GDScript 与 C# **不是主备（备用）关系**，而是按职责**静态划分**，从 S0 起并行建立：
| 职责域 | 语言 | 核心原因 |
| :--- | :--- | :--- |
| 表现层（UI / VFX / 音频 / 动画） | **GDScript** | 节点操作频繁；Inspector 可视化调整；帧预算宽松（< 1ms） |
| 游戏循环（WaveManager / ShopManager / CombatManager 状态机） | **GDScript** | 非高频热路径；快速迭代优先 |
| 数据定义（CoreDefinition / SpellNode / StatusTypeDef） | **GDScript `.tres`** | Godot 编辑器原生 Inspector 支持；数值调整零编译 |
| 配置与存档（ConfigMgr / SpellRegistry / ProfileManager） | **GDScript** | JSON / Resource 读取一次性，非热路径 |
| 法术预编译（`compile_wand`） | **GDScript** | 仅在换牌时触发，非 `_physics_process`；Dictionary 操作 GDScript 更高效 |
| 事件总线（EventBus / EventID） | **GDScript** | 保持单语言，避免跨语言信号绑定复杂性 |
| **`BulletManager._physics_process`** | **C#** | 2000 颗/帧 SoA 积分；`Span` 零拷贝 + struct 零 GC；GDScript ≈8ms → C# ≈0.8ms |
| **`EnemyManager._physics_process`** | **C#** | 1000 敌人 Boid 分离力；向量运算密集；GDScript ≈6ms → C# ≈0.6ms |
| **`SpatialGrid`（重建 + 查询）** | **C#** | 每帧重建 + M×N `query_circle`；纯计算密集，受益于 JIT 内联优化 |
| **`SpellEvaluator.execute_compiled`** | **C#** | 内层 while 循环（MAX_OPS_PER_CPU=40 × 高频施法）；`switch` 跳表 JIT 优化 |
| **`StatusManager._physics_process`** | **C#** | 200+ 状态实例逐 tick 计算；swap-and-pop 顺序内存访问 C# 受益更大 |
| **`ZoneManager._physics_process`** | **C#** | Zone tick + SpatialGrid 批量查询组合 |
#### 跨语言边界规则（ADR-L1）
每次 GDScript ↔ C# `Call()` / `Set()` 约有 1–5µs 开销，以下规则确保该开销不进入任何热路径：
**规则 1：禁止在 C# 内层循环体内调用 GDScript 方法**
`BulletManagerCs._PhysicsProcess` 的 `for` 循环体内不得出现 `GodotObject.Call()` / `.Set()`。
2000 次/帧 × 1–5µs = 2–10ms，直接耗尽帧预算。
**规则 2：热数据通过 `PackedFloat32Array.AsSpan()` 零拷贝共享**
GDScript Autoload 持有 `_data: PackedFloat32Array`；C# 通过 `AsSpan()` 获取 `Span` 原生指针，**无内存复制**：
```csharp
// BulletManagerCs.cs — _PhysicsProcess 热路径
public override void _PhysicsProcess(double delta)
{
float f = (float)delta;
using var span = _data.AsSpan(); // 零拷贝：指向 PackedFloat32Array 底层内存
int end = _activeCount * BulletStride; // const int BulletStride = 12
for (int i = 0; i < end; i += BulletStride)
{
span[i] += span[i + 2] * f; // px += vx * dt
span[i + 1] += span[i + 3] * f; // py += vy * dt
span[i + 4] -= f; // lifetime -= dt
}
}
```
**规则 3：帧末批量通知 GDScript，不在循环内逐条回调**
C# 内部用 `List` 收集当帧命中 ID，`_PhysicsProcess` 末尾**一次性**通知 EventBus：
```csharp
// 帧末单次跨语言调用（循环外）
// ⚠️ 禁止 _hitBulletIds.ToArray()——每帧 new int[] 产生 GC 分配。
// 改用可复用的类字段 Godot.Collections.Array _hitBuffer（_Ready() 中 new 一次）：
// private readonly Godot.Collections.Array _hitBuffer = new();
if (_hitBulletIds.Count > 0)
{
_hitBuffer.Clear();
foreach (var id in _hitBulletIds) _hitBuffer.Add(id);
_eventBus.Call("emit_batch", (int)EventId.BulletHit, _hitBuffer);
_hitBulletIds.Clear();
}
```
**规则 4：C# 组件挂为 GDScript Autoload 的子节点**
```
(Autoload) bullet_manager.gd ← GDScript：_data PackedFloat32Array + 对外接口（spawn/despawn）
└─ BulletManagerCs.cs ← C# Node：_Ready() 缓存父节点引用；_PhysicsProcess 执行热路径
```
GDScript 对外接口（`spawn_bullet` / `despawn_bullet`）保持不变，其他 GDScript 系统无感知 C# 的存在。
C# `_Ready()` 中获取父节点并缓存 `_data` 引用，之后每帧直接操作，无跨语言调用。
**BulletManager GDScript 对外接口（权威签名）**
```gdscript
# bullet_manager.gd (Autoload: BulletManager)
# 以下为 GDScript 对外 API；C# 热路径（_physics_process 积分）不在此列出。
const BULLET_STRIDE: int = 12 # SoA 完整布局（权威：arch §4.2）：
# [ x, y, vx, vy, lifetime, radius, base_damage, damage_mult, damage_type, owner_id, source_tags, acceleration ]
# 0 1 2 3 4 5 6 7 8 9 10 11
# 冷数据（pierce/bounce/homing/payload_id）→ _bullet_contexts: Dictionary（非热路径）
var _data: PackedFloat32Array = PackedFloat32Array()
var _active_count: int = 0
var _bullet_contexts: Dictionary = {} # { bullet_id: int → Dictionary（冷数据）}
func spawn_bullet(def: ProjectileDef, pos: Vector2, vel: Vector2) -> int:
# 返回 bullet_id（SoA 槽位索引）；def.lifetime 单位：秒
# SpellEvaluator、ZoneManager 调用
pass # 具体实现见 implementation_plan.md §2.2
func despawn_bullet(bullet_id: int) -> void:
# 提前回收：lifetime 置 0；C# 下帧 SoA 清理
if bullet_id < 0 or bullet_id >= _active_count: return
_data[bullet_id * BULLET_STRIDE + 4] = 0.0 # slot +4: lifetime
func get_active_count() -> int: return _active_count
func get_nearest_enemy_pos(origin: Vector2, max_dist: float = 9999.0) -> Vector2:
# PlayerManager.get_aim_direction() 调用（自动瞄准默认模式）
# 委托 EnemyManager.get_nearest_pos 直接线性扫描敌人 SoA；非每帧热路径（仅发射时调用）
return EnemyManager.get_nearest_pos(origin, max_dist)
func reset() -> void:
_active_count = 0 # 不需要清零数据，_active_count 控制有效范围
_bullet_defs.clear()
```
> **命名统一说明**：文档早期混用 `spawn()` / `spawn_bullet()`，以此处 `spawn_bullet(def, pos, vel)` 为唯一权威签名；`despawn_bullet(id)` 同理。ADR-L1 中提到的"GDScript 对外接口"均指此两个函数。
**规则 5：`compile_wand` 保留在 GDScript，不迁移**
法术预编译仅在换牌时触发（非 `_physics_process`），主要为 `Dictionary` / `Array` 构建操作，
GDScript 开发效率更高；迁移 C# 无性能收益且增加维护成本。
---
### 6.2 EventBus Autoload 接口定义
`EventBus`（`event_bus.gd`）是全局事件总线，**第 6 个 Autoload 初始化**（见 §9.2），所有 Manager 均依赖它。采用整数 ID 替代字符串，避免运行时 String 比较。
```gdscript
# event_bus.gd (Autoload: EventBus)
# 核心约定：
# - 所有事件 ID 均在 event_ids.gd (Autoload: EventID) 中声明，不接受魔术数字
# - C# 热路径通过 emit_batch 一帧内批量发送，降低跨语言调用次数
# - 订阅回调在 GDScript 侧统一处理，不在 C# 侧订阅（ADR-L1 规则 2）
var _listeners: Dictionary = {} # { event_id: int → Array[Callable] }
func subscribe(event_id: int, callback: Callable) -> void:
if not _listeners.has(event_id):
_listeners[event_id] = []
var arr: Array = _listeners[event_id]
if not arr.has(callback):
arr.append(callback)
func unsubscribe(event_id: int, callback: Callable) -> void:
if _listeners.has(event_id):
_listeners[event_id].erase(callback)
func emit(event_id: int, payload: Dictionary = {}) -> void:
if not _listeners.has(event_id): return
for cb: Callable in _listeners[event_id].duplicate(): # duplicate() 防止回调内修改订阅表
cb.call(payload)
func emit_batch(events: Array) -> void:
# C# BulletManager / EnemyManager 在 _physics_process 末尾调用（ADR-L1 规则 3）
# events 格式：[ [event_id: int, payload: Dictionary], ... ]
# 在主线程 GDScript 帧末执行，保证监听者在下一个 _process 前收到通知
for ev in events:
if ev.size() >= 2:
emit(int(ev[0]), ev[1])
elif ev.size() == 1:
emit(int(ev[0]))
func reset() -> void:
# GameCycleManager 在 Run 结束时调用，清除所有动态订阅（防跨 Run 事件泄漏）
# ⚠️ 仅清除非常驻订阅（GameCycleManager、UIManager 等 Autoload 在 _ready() 中重新订阅）
_listeners.clear()
```
> **使用约定**：
> - `subscribe` / `unsubscribe` 必须成对调用；Autoload 在 `_ready()` 中订阅，节点在 `_exit_tree()` 中取消。
> - `emit_batch` 仅供 C# Manager 使用，格式见注释；普通 GDScript Manager 直接调用 `emit`。
> - EventID 目录权威来源：`implementation_plan.md §2.1`（1–21，下一空位 22）。
---
## 7. 目录规范建议
```text
project.godot
scripts/
autoloads/ # Godot Autoload 单例 (EventBus, BulletManager, EnemyManager)
core/ # 核心架构 (ObjectPool, SpatialGrid, BaseClasses)
systems/ # 独立系统 (InputManager, AudioManager, ResourceManager)
domain/ # 游戏业务逻辑
spell_system/ # 法术解释器, SpellNode 定义, SpellDeck
combat/ # 伤害计算, 弹道管理 (BulletManager)
enemy/ # AI 行为, EnemyManager
ui/ # UI 控制脚本, 特效表现
config/ # JSON 配置加载器与类型定义
csharp/
autoloads/ # C# 热路径内核 (BulletManagerCs, EnemyManagerCs)
systems/ # C# 计算模块 (SpellEvaluatorCs, SpatialGridCs, StatusManagerCs, ZoneManagerCs)
scenes/
main/ # 主场景, 战斗场景
ui/ # UI 场景 (背包, 商店, HUD)
entities/ # 预制体场景 (子弹, 敌人, 特效)
resources/
spells/ # 法术数据 (.tres 或 .json)
enemies/ # 怪物数据
```
---
## 8. 架构决策记录 (Architecture Decision Records)
### ADR-R4-N2：属性快照方案（Snapshot vs Dynamic）
> **结论：采用 Snapshot（快照）方案。**
DoT（持续伤害）、召唤物（Minion）、持续性法术的属性在**施加/发射瞬间**锁定，
不跟随玩家后续属性变化。即：
- DoT 的每 tick 伤害 = 施加瞬间的 `attunement_bonus` × `base_damage`（固定值），后续装备变化不影响已施加的 DoT。
- Minion 的各项属性（速度/伤害/血量）= 召唤瞬间的玩家属性×配方系数，召唤后独立计算，不随玩家属性波动。
- 实现方式：`ProjectileDef` / `MinionSpawnParams` 在填充时立刻将计算完毕的数值写入，
BulletManager / MinionManager 直接使用存储值，不保存对玩家属性表的引用。
**设计原因**：Dynamic 方案（实时跟随）会导致属性换装瞬间大量已存在实体同步刷新，
产生不可控的计算尖峰，且与 SoA 热数组布局不兼容。Snapshot 方案计算开销集中在"施加时刻"，
运行时热路径无额外查询，更符合 Low-GC 原则。
详见 `docs/mechanics/combat_mechanics_extensions_v2.md §4.2`。
---
### ADR-R4-N4：召唤物/友军管理方案（MinionManager，方案 B）
> **结论：采用独立的 MinionManager（方案 B），不在 EnemyManager 中混管召唤物。**
> **⚠️ 实现现状 (2026-07-20 审计)**：MinionManager 存在，但数据结构用的是 **`Array[Dictionary]`（随 §5.12）而非本节的 SoA `stride=8`**（两处文档矛盾，代码选了 Array）；`behavior_state` 枚举未实现。召唤物**只实现了 Stationary 炮台一种**，随从/卫星/镜像（含 hp/碰撞体积/移动）均未落地。`MAX_MINIONS=20` FIFO 顶替已实现。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
`MinionManager` 为独立的 Autoload 单例，管理玩家召唤的炮台/傀儡/宠物类实体：
- **与 EnemyManager 隔离**：EnemyManager 的 SoA 中 `faction_and_type` 字段不扩展到友军，
避免碰撞 Layer 混乱和阵营判断逻辑膨胀。
- **Minion SoA stride**：`[x, y, vx, vy, hp, hp_max, owner_id, behavior_state]`（stride=8），
与 EnemyManager 的 stride=8 同构，便于复用 SpatialGrid 查询逻辑。
- **行为驱动**：Minion 的 AI 行为（巡逻/护卫/定点炮击）由 `behavior_state` 枚举驱动，
每帧在 `MinionManager._physics_process` 中批处理；不使用独立 Node `_process`。
- **生命周期**：Minion 属性在召唤瞬间 Snapshot（见 ADR-R4-N2），由 `owner_id` 关联到施法者；
施法者死亡时，对应的所有 Minion 同帧标记为"消退状态"（延迟 1 秒淡出销毁）。
- **上限保护**：单个玩家同场最多 `MAX_MINIONS = 20` 个 Minion，超出时最早召唤的自动消退。
详见 `docs/mechanics/advanced_mechanics_summons_and_environment.md §3.1`（方案 B 推荐）。
---
### ADR-R5-N1：地面效果系统架构（ZoneManager）
> **结论：采用独立的 ZoneManager（Autoload），Zone 实体基于 SpatialGrid 空间索引，不使用 Area2D。**
`ZoneManager` 管理战场中的持久化地面效果（毒液池、岩浆区、冻结地面等）：
- **数据结构**：`_zones: Array[ZoneData]`，ZoneData 字段：`[cx, cy, radius, status_type_id, duration, tick_interval, tick_accum, root_owner_id]`（stride=8；`tick_interval` 与 `tick_accum` 分开存储，支持每个 Zone 配置独立应用频率）。
- **碰撞检测**：每 `_physics_process` 帧调用 `SpatialGrid.query_circle(zone_center, zone_radius)`，对返回的敌人实体批量施加状态；不使用 Area2D，不产生 Node 开销。
- **上限保护**：`MAX_ZONES = 64`（超出时最早创建的 Zone 被顶掉）。
- **渲染**：Zone 的地面贴花由 `VFXManager.play_zone("poison_pool", center, radius)` 驱动，不在逻辑层操作节点。
- **生命周期**：Zone 创建时 duration 快照，每帧 duration -= delta；降至 ≤ 0 时用 swap-and-pop 移除，同步通知 VFXManager 淡出。
- **与 SpellSystem 的接口**：`ActionSplashPoison` 等 ACTION 节点执行时调用 `ZoneManager.spawn_zone(...)` 而非直接操作场景。
```gdscript
# zone_data.gd (inline struct, not a class_name Resource to avoid GC)
# 存储于 ZoneManager._zone_data: PackedFloat32Array，stride = 8
# [0]=cx [1]=cy [2]=radius [3]=status_type_id [4]=duration [5]=tick_interval [6]=tick_accum [7]=owner_id
# tick_interval：两次状态应用之间的最小间隔（秒，由 spawn_zone 调用方指定）
# tick_accum：当前累积时间（运行时变量），>= tick_interval 时触发一次 APPLY_DAMAGE 并减去 tick_interval
# zone_manager.gd (Autoload)
const ZONE_STRIDE: int = 8
const MAX_ZONES: int = 64
var _zone_data: PackedFloat32Array # SoA 热数据
var _active_zones: int = 0
func spawn_zone(cx: float, cy: float, radius: float,
status_id: int, duration: float,
tick_interval: float, # Zone 每隔多少秒对范围内敌人应用一次状态
owner_id: int) -> void:
if _active_zones >= MAX_ZONES:
# 顶掉最旧的 Zone（index 0），整体前移（O(N)，N≤64 可接受）
# PackedFloat32Array 无 remove_at()，用手动循环前移实现首元素删除
for j in range(ZONE_STRIDE, _active_zones * ZONE_STRIDE):
_zone_data[j - ZONE_STRIDE] = _zone_data[j]
_active_zones -= 1
var base: int = _active_zones * ZONE_STRIDE
_zone_data.resize((_active_zones + 1) * ZONE_STRIDE)
_zone_data[base + 0] = cx; _zone_data[base + 1] = cy
_zone_data[base + 2] = radius; _zone_data[base + 3] = status_id
_zone_data[base + 4] = duration; _zone_data[base + 5] = tick_interval
_zone_data[base + 6] = 0.0 # tick_accum 初始为 0
_zone_data[base + 7] = owner_id
_active_zones += 1
func _physics_process(delta: float) -> void:
var i: int = 0
while i < _active_zones:
var base: int = i * ZONE_STRIDE
_zone_data[base + 4] -= delta # duration 倒计时
_zone_data[base + 6] += delta # tick_accum 累积
# 速率限制：仅当 tick_accum >= tick_interval 时才触发状态应用，防止 64 个 Zone 每帧
# 对 1000 个敌人各触发，产生最多 64,000 APPLY_DAMAGE 事件/帧。
# 外层 if 守卫 + 内层 while + -= tick_interval：保留余量精度，且支持大帧多次跳字。
# SpatialGrid.query_circle 仅在 if 守卫内调用一次，不在 while 内重复查询。
if _zone_data[base + 6] >= _zone_data[base + 5]:
var cx: float = _zone_data[base + 0]; var cy: float = _zone_data[base + 1]
var rad: float = _zone_data[base + 2]; var sid: int = int(_zone_data[base + 3])
var targets := SpatialGrid.query_circle(Vector2(cx, cy), rad)
while _zone_data[base + 6] >= _zone_data[base + 5]:
_zone_data[base + 6] -= _zone_data[base + 5] # -= tick_interval 保留余量精度
for t_id in targets:
# ⚠️ 修正(2026-07-20)：真实签名 apply(entity_id, status_type_id, stacks:int=1, duration:float=-1.0, owner_id:int=-1)——5 参
StatusManager.apply(t_id, sid, 1, -1.0, int(_zone_data[base + 7])) # stacks=1, duration=default, owner_id=zone_owner（现实 zone_manager.gd:60 即如此调用）
if _zone_data[base + 4] <= 0.0: # duration 耗尽，移除此 Zone
var cx_exp: float = _zone_data[base + 0]; var cy_exp: float = _zone_data[base + 1]
var rad_exp: float = _zone_data[base + 2]
VFXManager.play("zone_expire", Vector2(cx_exp, cy_exp), rad_exp / 64.0)
# swap-and-pop 移除（O(1)，顺序可乱）
if i < _active_zones - 1:
for k in ZONE_STRIDE:
_zone_data[base + k] = _zone_data[(_active_zones - 1) * ZONE_STRIDE + k]
_active_zones -= 1
else:
i += 1
func reset() -> void:
# GameCycleManager._reset_all_managers() 调用，清空所有活跃区域特效
_active_zones = 0 # SoA 数据不清零，_active_zones 控制有效范围（惰性清理）
```
> **与 BulletManager 的区别**：BulletManager 管理短生命周期（秒级）的投射物；ZoneManager 管理中等生命周期（数秒～数十秒）的区域场。两者共享同一个 `SpatialGrid` 实例，但查询入口不同（BulletManager 查敌人，ZoneManager 也查敌人但传入 zone_center/radius）。
---
### ADR-R5-N2：Core Feature Tags 字符串常量规范
> **问题**：`if "persistent_memory" not in core.feature_tags` 使用裸字符串比较，拼写错误时静默失效，且重构不安全。
> **结论**：所有 Feature Tag 字符串必须通过 `CoreFeatureTag` 常量访问，禁止在业务代码中写裸字符串。
> **⚠️ 实现现状 (2026-07-20 审计)**：代码**未按本节的 `String` 常量 + `in` 判定实现**。`core_feature_tag.gd` 实为 **`int` 常量**（PERSISTENT_MEMORY=1, DUAL_STREAM=2, ALWAYS_CAST_LAST=3, SHUFFLE_DECK=4, INFINITE_SPELLS=5），`core.feature_tags` 为 `int` 位掩码。**feature_tags 实为单选枚举**（游戏设计器 `core_tab.gd` 以 OptionButton 下标 0..5 写入，下标即等于常量值）。原代码用位与 `&` 判定，因常量非 2 的幂会串扰（`3 & 1 = 1` 误判持久内存）。✅ **已修复** (`fix/audit-latent-bugs` dc05eea)：判定改为 `==`，常量保持 1..5（未改位标志以免与设计器 desync）。详见 [审计报告 D 节](../../docs_dev/doc_code_audit_2026-07-20.md)。
```gdscript
# core_feature_tag.gd (Autoload: CoreFeatureTag)
## Core 特性标签常量表 — 所有系统通过此处引用，禁止裸字符串
const PERSISTENT_MEMORY: String = "persistent_memory"
const DUAL_STREAM: String = "dual_stream"
const SHUFFLE_DECK: String = "shuffle_deck"
const INFINITE_SPELLS: String = "infinite_spells"
const ALWAYS_CAST_LAST: String = "always_cast_last"
## 使用示例（正确）：
## if CoreFeatureTag.PERSISTENT_MEMORY in core.feature_tags: ...
##
## 禁止的写法：
## if "persistent_memory" in core.feature_tags: ... # ❌ 裸字符串
```
新增 Feature Tag 流程：
1. 在 `CoreFeatureTag` 中追加常量（命名规则：全大写下划线分隔）。
2. 在 `core_wand_design.md §3` Feature Tags 表格中登记效果与稀有度。
3. 在 `SpellEvaluator` 或对应 Manager 中实现逻辑，通过 `CoreFeatureTag.XXX` 引用。
---
### ADR-A1：本地化架构（L10n Infrastructure）
> **结论：从 S1 起强制所有玩家可见字符串通过 `tr()` 包裹；本地化是开发规范而非后期工程。**
商业 Steam 发行需支持至少简体中文 / 繁体中文 / 英语 / 日语四语。延后本地化会导致数千条裸字符串的批量替换，历史代价极高。
**规范约束**：
* 所有 UI 标签、法术名称、状态名称、Boss 名称、提示文本字符串字面量**必须**用 `tr("KEY")` 包裹。
* 禁止在业务代码中写裸中文字符串（仅 `push_warning` / `push_error` 调试输出除外）。
* 使用 Godot 内置 `.po` 文件（兼容 Gettext 工具链），路径 `res://translations/zh_CN.po` / `en.po`。
**键名规范**：`<模块>_<实体>_<含义>`，全大写下划线，例：
| 键 | 对应文本 |
| :--- | :--- |
| `SPELL_SPARK_BOLT_NAME` | "电花弹" |
| `SPELL_SPARK_BOLT_DESC` | "发射一枚快速电花弹，命中造成闪电伤害" |
| `STATUS_BURN_NAME` | "燃烧" |
| `UI_SHOP_REROLL_TOOLTIP` | "花费 {gold} 金币刷新商店" |
**实施时机**：S1 随 ConfigMgr 一并建立翻译加载流程（`ProjectSettings/locale` + `TranslationServer.add_translation()`）；S1 起所有新增文本直接按规范写键，不留技术债。
---
### ADR-A2：局内存档 / 断点续玩（Run State Persistence）
> **结论：S2 实现波次边界自动存档，采用 A/B 双槽写入防崩溃损坏，支持断点续玩。**
> **⚠️ 实现现状 (2026-07-20 审计)**：A/B 双槽 + 波次自动存档 + `WM_CLOSE` 兜底 + 链式迁移已实现。差异：① 选槽逻辑现按 `saved_at` **时间戳选最新未损坏槽**（比下文伪代码"固定顺序取第一个有效"更健壮，**代码更优**）；② `SCHEMA_VERSION` 已到 **2**（新增 `wand` 键），本节仅记 v1；③ 实存字段为 `wave_num/shop_seed/player_stats/wand`，**缺** `elapsed_sec`（影响无尽续玩计时）、`active_core_idx`、`unlocked_upgrades`、多 Core 数组（待补）。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
商业 Roguelite（Hades / Slay the Spire / Balatro）均支持中途退出后恢复到当前波次起始状态。
**存档时机**：
1. 每波**战斗结束**（进入商店阶段前）：序列化 `PlayerState + ActiveCore + WaveNum`。
2. 每次**商店关闭**（进入下一波前）：追加序列化 `InventoryState + UpgradePicks`。
3. 游戏**异常退出**：通过 `_notification(NOTIFICATION_WM_CLOSE_REQUEST)` 触发最后一次存档。
**序列化字段**（`run_state_v1.json`）：
| 字段 | 内容 |
| :--- | :--- |
| `schema_version` | 当前 = 1；迁移时递增 |
| `wave_num` | 当前波次（读档后从此波重新开始） |
| `elapsed_sec` | 本次 Run 总计时（无尽模式得分依据） |
| `player_hp` | 当前血量 |
| `player_stats` | 所有属性词条快照（Dictionary） |
| `cores` | 3 个 Core 的完整 SpellDeck JSON（含 `core_id` + `slots`，格式见 §3 E2） |
| `active_core_idx` | 当前激活 Core 索引（0/1/2） |
| `unlocked_upgrades` | 已选升级 ID 数组 |
| `shop_seed` | 随机种子（保证重进后商店展示相同选项，防刷新重开骗局） |
**A/B 双槽写入（防崩溃数据损坏）**：
```gdscript
# game_cycle_manager.gd（或 ProfileManager）
const _SLOT_A := "user://run_a.json"
const _SLOT_B := "user://run_b.json"
func save_run(data: Dictionary) -> void:
var which := ProfileManager.get_int("run_write_slot", 0) # 0=A, 1=B
var path := _SLOT_A if which == 0 else _SLOT_B
var f := FileAccess.open(path, FileAccess.WRITE)
if f: f.store_string(JSON.stringify(data))
ProfileManager.set_int("run_write_slot", 1 - which) # 下次写另一槽
func load_run() -> Dictionary:
for path in [_SLOT_A, _SLOT_B]:
if not FileAccess.file_exists(path): continue
var text := FileAccess.open(path, FileAccess.READ).get_as_text()
var parsed: Variant = JSON.parse_string(text)
if parsed is Dictionary and parsed.has("schema_version"):
return parsed
return {} # 无有效存档，从头开始新 Run
```
写完 A 槽后下次写 B 槽，两槽交替覆写；任意一次写入崩溃只损坏一个槽，另一槽保留上次完整状态。
**存档版本迁移框架（Schema Migration）**：新增字段或修改存档结构时，递增 `schema_version` 并在 `_migrate_run()` 中追加对应迁移函数；禁止在业务代码中对新字段直接 `.get()` 而绕过迁移。
```gdscript
# profile_manager.gd — 存档迁移分发入口
# 调用时机：load_run() 成功解析 JSON 后、return 前调用 _migrate_run(data)
func _migrate_run(data: Dictionary) -> Dictionary:
var ver: int = data.get("schema_version", 0)
if ver < 1:
data = _migrate_v0_to_v1(data)
# if ver < 2:
# data = _migrate_v1_to_v2(data) # 未来版本在此追加，保持链式顺序迁移
return data
# v0 → v1：为无 schema_version 的旧存档补全 S2 新增字段的默认值
func _migrate_v0_to_v1(data: Dictionary) -> Dictionary:
data["schema_version"] = 1
if not data.has("elapsed_sec"): data["elapsed_sec"] = 0.0
if not data.has("shop_seed"): data["shop_seed"] = randi() # 随机补种，防刷新重开
if not data.has("unlocked_upgrades"): data["unlocked_upgrades"] = []
if not data.has("active_core_idx"): data["active_core_idx"] = 0
return data
```
**版本变更记录**（每次 `schema_version` 递增后在此登记）：
| schema_version | 变更内容 | 对应切片 |
| :--- | :--- | :--- |
| 1 | 初始版本：`wave_num` / `elapsed_sec` / `player_hp` / `player_stats` / `cores` / `active_core_idx` / `unlocked_upgrades` / `shop_seed` | S2 |
---
## ADR-R6 — Endless 排行榜数据完整性 (Leaderboard Integrity)
> **问题**：`user://endless_records.json` 是纯文本 JSON，玩家可直接用文本编辑器修改分数。
> 本 ADR 定义基于 HMAC-SHA256 的本地签名方案，对抗普通玩家随意手改，同时不影响离线可玩性。
### R6.1 威胁模型
| 攻击向量 | 对抗手段 | 是否覆盖 |
| :--- | :--- | :--- |
| 直接编辑 JSON 文件 | HMAC 签名验证失败 → 拒绝载入 | ✅ |
| 复制高分存档文件 | 签名与内容绑定，复制后验证通过（允许，属于本地副本） | 允许 |
| 逆向提取 HMAC Key 后重签 | 超出本方案防护范围；如需强防护则依赖服务器排行榜 | ❌ |
| 网络传输篡改（Steam 排行榜提交）| Steam SDK 侧验证，非本地文件问题 | ❌（Steam 负责）|
### R6.2 实现规范
```gdscript
# scripts/domain/endless_records_manager.gd
class_name EndlessRecordsManager
extends RefCounted
# HMAC Key：32 字节随机密钥，S5 开发前生成并硬编码到此处
# ⚠️ 安全注意：此 Key 仅防普通手改，不能防逆向；不含敏感用户数据，可接受。
# 生成方式：python3 -c "import secrets; print(list(secrets.token_bytes(32)))"
const _HMAC_KEY: PackedByteArray = [
0x3F, 0x7A, 0x12, 0xB8, 0x5C, 0xE4, 0x91, 0x2D,
0x6F, 0x04, 0xAA, 0x73, 0xC9, 0x18, 0x55, 0xE7,
0x8B, 0x31, 0xF6, 0x4E, 0x0D, 0x90, 0x26, 0x7C,
0xD2, 0x47, 0xBE, 0x5A, 0x83, 0x1F, 0xCA, 0x69
] # 实际集成时替换为项目专属 Key
const RECORDS_PATH: String = "user://endless_records.json"
func save(records: Array) -> void:
var data_str := JSON.stringify(records)
var sig := _sign(data_str)
var envelope := { "data": records, "sig": sig, "ver": 1 }
var f := FileAccess.open(RECORDS_PATH, FileAccess.WRITE)
if f:
f.store_string(JSON.stringify(envelope))
func load() -> Array:
if not FileAccess.file_exists(RECORDS_PATH): return []
var raw: Variant = JSON.parse_string(
FileAccess.open(RECORDS_PATH, FileAccess.READ).get_as_text())
if not raw is Dictionary: return []
var records: Variant = raw.get("data", [])
var expected := _sign(JSON.stringify(records))
if raw.get("sig", "") != expected:
push_warning("EndlessRecords: 签名验证失败，疑似被篡改，分数已重置")
return [] # 拒绝载入，不崩溃；UI 显示"分数不可用"
return records
func _sign(data: String) -> String:
var crypto := Crypto.new()
return crypto.hmac_digest(
HashingContext.HASH_SHA256,
_HMAC_KEY,
data.to_utf8_buffer()
).hex_encode()
```
### R6.3 分数提交 Steam 排行榜前的验证
```gdscript
# game_cycle_manager.gd — Endless 结算时
func _submit_endless_score(wave: int, elapsed_sec: float) -> void:
var score: int = wave * 100000 + (86400 - int(elapsed_sec)) # wave 优先，elapsed_sec 作为同波次决胜分
var records: Array = EndlessRecordsManager.new().load()
if records.is_empty() and FileAccess.file_exists(
EndlessRecordsManager.RECORDS_PATH):
# 文件存在但 load() 返回空 → 被篡改，不提交 Steam 排行榜
UIManager.show_toast("分数验证失败，本次成绩不上传排行榜")
return
# 验证通过后提交（Steam SDK 调用）
if SteamIntegration.is_available():
SteamIntegration.upload_leaderboard_score(score)
```
> **决策背景**：3A 商业标准要求游戏对色盲玩家（约占男性玩家 8%）可玩。仅用颜色区分元素
> 会导致此类玩家无法识别元素类型，影响共鸣系统核心玩法。
### C1.1 颜色盲支持（必须实现）
**规则 ADR-C1-R1**：UI 中所有元素标识必须同时提供颜色 + 形状标识，禁止仅用颜色区分。
**形状图标映射表**（对应 `SpellNode.shape_icon` 字段）：
| 元素 | 颜色（正常视觉） | `shape_icon` 键 | 图标形状描述 |
| :--- | :--- | :--- | :--- |
| 火系 Fire | 橙红 `#FF4500` | `"triangle"` | 向上三角形 |
| 冰系 Ice | 冰蓝 `#7EC8E3` | `"diamond"` | 菱形 |
| 水系 Water | 深蓝 `#1E90FF` | `"circle"` | 圆形 |
| 土系 Earth | 棕绿 `#8B7355` | `"square"` | 方形 |
| 雷系 Lightning | 黄色 `#FFD700` | `"star"` | 五角星 |
| 暗系 Dark | 紫黑 `#4B0082` | `"cross"` | X 形 |
**渲染规则**：
```gdscript
# ui_spell_card.gd — 法术卡渲染示例
func _render_element(spell_node: SpellNode) -> void:
# 1. 颜色背景（正常视觉）
$ElementBadge/Background.color = ElementColors.get(spell_node.element_tags)
# 2. 形状图标叠加（色盲支持，ADR-C1-R1）
if spell_node.shape_icon != "":
$ElementBadge/ShapeIcon.texture = UIAtlas.get_icon(spell_node.shape_icon)
$ElementBadge/ShapeIcon.visible = true
else:
$ElementBadge/ShapeIcon.visible = false
```
**VFX 叠加规则**（ADR-C1-R1 延伸）：
- 命中 VFX 粒子颜色使用对应元素颜色。
- 命中时在命中点叠加 1 帧（0.1s）的 `shape_icon` TextureRect，字号 1.5× 基准大小。
- `VFXManager` 在 `spawn_hit_vfx(pos, element_tag)` 中从 UIAtlas 读取 `shape_icon` 并生成叠加节点。
### C1.2 字体缩放（S4 实现）
```gdscript
# settings_manager.gd 新增常量 + 接口
const FONT_SCALE_KEY: String = "font_scale"
const FONT_SCALE_MIN: float = 0.5
const FONT_SCALE_MAX: float = 1.5
const FONT_SCALE_DEF: float = 1.0
static func get_font_scale() -> float:
return ProfileManager.get_float(FONT_SCALE_KEY, FONT_SCALE_DEF)
.clamp(FONT_SCALE_MIN, FONT_SCALE_MAX)
static func apply_font_scale(root: Node) -> void:
# 遍历 UILayer 下所有 Label 节点，按 scale 覆写 custom_font_size
for label in root.find_children("*", "Label", true, false):
label.add_theme_font_size_override(
"font_size", int(label.get_theme_font_size("font_size") * get_font_scale()))
```
UI 初始化时调用 `SettingsManager.apply_font_scale(ui_root)`；字体缩放变更时发送
`EventBus.emit(EventID.SETTINGS_CHANGED, { "key": "font_scale" })` 触发全局重渲染（`EventID` **19**，见 `implementation_plan.md` §2.1）。
### C1.3 减少闪光（S6 实现）
设置项 `reduce_flash`（bool，默认 `false`）：
- 开启时：VFXManager 将爆炸 / 共鸣特效的帧率限制为 12fps，白闪持续时间从 0.2s → 0.05s。
- `EventID.GAME_CLEARED`（GameCycleManager 进入 GAME_CLEARED 状态时发出）的全屏白闪在该模式下完全跳过。
### C1.4 高对比度模式（S6 实现）
设置项 `high_contrast`（bool，默认 `false`）：
- 开启时：UI 背景强制黑色 `#000000`，所有 Label 强制白色 `#FFFFFF`。
- 实现：`SettingsManager.apply_high_contrast(ui_root)` 覆写主题颜色变量，不修改资源文件。
---
## ADR-A3 — 音频架构补充细节 (Audio Architecture - Supplementary)
> **注意**：AudioBus 层级结构、AudioBusID 常量、`_bgm_base_player`/`_music_layers` 字段声明、`play_bgm()`/`play_sfx()` 接口均已在 **§5.4** 完整定义，本 ADR 仅补充 §5.4 未涉及的细节（2D 空间音效衰减参数、音量持久化、SFX 节流规则）。
### A3.1 AudioBus 结构参考
> ⚠️ 此处为索引引用，**不重新定义** Bus 结构，权威定义见 §5.4。
Bus 树：`Master > BGM (BGM_Base, BGM_Layer) > SFX (SFX_Combat, SFX_Spatial) > UI > Ambience > Voice`
AudioBusID Autoload 常量：`MASTER / BGM / BGM_BASE / BGM_LAYER / SFX / SFX_COMBAT / SFX_SPATIAL / UI / AMBIENCE / VOICE`
### A3.2 动态音乐分层触发规则（补充）
| 屏内敌人数 / 状态 | BGM_Layer 激活层级 | 说明 |
| :--- | :--- | :--- |
| 0–4 | Layer 0（基础，仅鼓点 + 低音） | 常驻，即使 0 敌人 |
| 5–19 | Layer 1（主旋律 + 和弦） | EnemyManager.get_visible_count() ≥ 5 |
| ≥ 20 或 Boss 激活 | Layer 2（弦乐/合成铅声） | 最高战斗强度 |
| SHOP / MAIN_MENU 状态 | 独立 BGM（BGM_Base 直接切换）| BGM_Layer 全部静音 |
`AudioManager._process()` 每 0.5s 轮询一次 `EnemyManager.get_visible_count()`；Boss 激活/死亡通过 EventBus 订阅（`BOSS_PHASE_CHANGED` / `BOSS_KILLED`）实时响应，无需轮询。
### A3.3 2D 空间音效衰减
- SFX_Spatial Bus 下的 `AudioStreamPlayer2D` 使用 Godot 内置 `attenuation_filter_db` 曲线。
- **衰减曲线参数**（`max_distance=1200px`，`attenuation=1.8`）：
0px → 0dB, 400px → -6dB, 800px → -18dB, 1200px → -40dB（截止）。
- 超出 `max_distance` 的音源直接 `stop()`，不参与 0.1s 节流（已无声）。
### A3.4 音量持久化
```gdscript
# settings_manager.gd — 音量持久化
# AudioBusID 是 Autoload，其常量为整数（bus index）；不支持字符串下标访问，使用显式映射表
# bus_key（保存键）→ AudioServer bus index（AudioBusID 常量）的显式映射
const _VOLUME_BUS_MAP: Dictionary = {
"vol_master": AudioBusID.MASTER,
"vol_bgm": AudioBusID.BGM,
"vol_sfx": AudioBusID.SFX,
"vol_ui": AudioBusID.UI,
}
func load_audio_settings() -> void:
# SettingsManager._ready() 调用；将持久化音量值应用到 AudioServer
for save_key in _VOLUME_BUS_MAP:
var db: float = ProfileManager.get_float(save_key, 0.0) # 0.0 dB = 100%
AudioServer.set_bus_volume_db(_VOLUME_BUS_MAP[save_key], db)
func save_audio_setting(save_key: String, db: float) -> void:
# UIManager 音量滑块 on_value_changed → SettingsManager.save_audio_setting("vol_bgm", db)
if not _VOLUME_BUS_MAP.has(save_key):
push_warning("SettingsManager: unknown audio save_key: %s" % save_key)
return
AudioServer.set_bus_volume_db(_VOLUME_BUS_MAP[save_key], db)
ProfileManager.set_float(save_key, db)
EventBus.emit(EventID.SETTINGS_CHANGED, { "key": save_key })
```
**存储位置**：`user://save_data.json`（由 `ProfileManager` 管理，非 Run 存档）。
**范围约定**：音量滑块线性映射到 `-40dB ~ 0dB`；mute 状态用 `-80dB` 替代 `set_bus_mute()`
以避免 Godot 的 mute 标志在存档恢复时的边界问题。
### A3.5 SFX 池节流规则补充
> 以下补充 `implementation_plan.md §2.5.B` 中已有的 32 池规则：
| 规则 | 说明 |
| :--- | :--- |
| 同一音效 0.1s 内只播放 1 次 | `_last_play_time[sfx_id]` 字典节流 |
| 同帧相同位置的碰撞音效合并为 1 次 | BulletManager 碰撞处理后批量调用 `AudioManager.play_sfx_batch()` |
| Boss 语音（Voice Bus）不受 SFX 池限制 | 独立 `AudioStreamPlayer` 节点，最高优先级 |
| 玩家死亡时淡出所有 Bus（0.5s 内 -40dB）| `AudioManager.fade_out_all(duration=0.5)` |
---
## ADR-A4 — 敌人 AI 寻路方案决策 (Enemy Pathfinding)
> **结论**：Wave 1–14 普通敌人维持当前 Boid 斥力向量（无寻路）；Wave 15+ Elite 及 Boss 敌人按需引入 Godot `NavigationAgent2D`，并发上限 `MAX_PATHFINDING_ENEMIES=20`，超限降级 Boid。
>
> **S5 定案（2026-06-05，P-S5-AI-01 实测）**：采用 **`NavigationAgent2D` 方案**，**不**切换 FlowField。20 个 Elite 同时寻路的 `_update_pathfinding_movement` 实测 **≈0.0496ms/帧**，远低于 0.5ms 预算（约 10× 余量）。实现于 `enemy_manager.gd`（GDScript 回退路径）：程序化单凸矩形 `NavigationRegion2D` + 每精英 `Node2D` host 挂 `NavigationAgent2D`（`avoidance_enabled=false`，与 SoA Boid 分离力共存）；无精英时主循环零额外开销。
### 背景
当前架构中，所有敌人的移动逻辑为 Boid 斥力向量（EnemyManagerCs 内 SoA 批量计算），无完整寻路。
评估发现 W15+ 精英敌人在面对角落障碍物时，因无寻路只能在角落堆叠，导致玩家可"站角落无脑输出"打过高难度波次，严重削弱 W15+ 的挑战性。
### 方案对比
| 方案 | 优点 | 缺点 | 适用范围 |
| :--- | :--- | :--- | :--- |
| Boid 斥力（当前） | 零额外 CPU，SoA 批量计算，1000 敌人帧时间已知 | 敌人无法绕过角落障碍物 | W1-14 杂鱼（堆叠可接受） |
| Godot `NavigationAgent2D` | 引擎内置，实现简单；支持动态障碍物 | 1000 个 Agent 同时 `get_next_path_position()` 帧时间未知，需 S5 基准测试 | Elite / Boss（≤ 20 个并发寻路） |
| FlowField 预烘焙 | O(1) 每敌人查询，适合大量敌人共享目标 | 实现复杂；场景动态障碍物需触发重烘焙（延迟约 1 帧） | 若 NavigationAgent2D 20 个精英时帧时间增量 > 0.5ms，则以此方案替代 |
### 实施规则
- `MAX_PATHFINDING_ENEMIES = 20`：同时具有完整寻路能力的敌人数上限。超出上限的额外 Elite 降级为 Boid 模式（按距玩家最近优先保留寻路资格）。
- W1–14 普通敌人：**永远** 使用 Boid 模式，不分配 NavigationAgent2D，避免节点数量爆炸。
- W15+ Elite / Boss：入场时在 `EnemyManagerCs` 中标记 `has_pathfinding = true`，GDScript 侧为其创建 `NavigationAgent2D` 子节点。
- **S5 性能验收（新增 P-S5-AI-01）**：`NavigationAgent2D` 20 个 Elite 同时寻路，`_physics_process` 帧时间增量 < **0.5ms**；若超标，切换 FlowField 方案并在本 ADR 更新决策结论。
### 过渡策略
S1–S4 期间：所有敌人继续使用 Boid 模式，不实现寻路（维持已知性能基线）。
S5 实现 Elite 敌人时：同步实现 `NavigationAgent2D` 方案并运行 P-S5-AI-01 基准测试，若达标则定案为 NavigationAgent2D；否则切换 FlowField。
---
## 9. Godot 项目结构 (Project Structure)
### 9.1 场景树结构 (Scene Tree)
#### 主场景（Main.tscn）
```
Main (Node) ← res://scenes/Main.tscn，程序入口
├── UILayer (CanvasLayer, layer=10) ← 主菜单 / 过渡 / 全局遮罩
│ └── MainMenuUI (Control)
├── GameRoot (Node2D) ← 战斗场景的挂载点（动态 add_child / remove_child）
└── [C# Manager 子节点] ← ADR-L1 规则 4：C# 热路径作为对应 Autoload 的子节点
├── BulletManagerCs (Node) ← 挂在 BulletManager Autoload 下
├── EnemyManagerCs (Node) ← 挂在 EnemyManager Autoload 下
├── SpatialGridCs (Node) ← 挂在 SpatialGrid Autoload 下（或独立 Autoload）
├── SpellEvaluatorCs (Node) ← 挂在 SpellEvaluator Autoload 下
├── StatusManagerCs (Node) ← 挂在 StatusManager Autoload 下
└── ZoneManagerCs (Node) ← 挂在 ZoneManager Autoload 下
```
> **注意**：C# 子节点由对应的 GDScript Autoload 在 `_ready()` 中通过 `add_child(BulletManagerCs.new())` 创建，不出现在 .tscn 文件中（避免场景文件依赖 C# 程序集，保持热重载友好）。
#### 战斗场景（BattleScene.tscn）
```
BattleScene (Node2D) ← res://scenes/BattleScene.tscn
├── World (Node2D) ← 世界坐标系（地图 TileMap 挂这里）
│ ├── TileMap (TileMap) ← 地图地形（S1 起实现）
│ ├── BulletRenderRoot (Node2D) ← 子弹 Node2D 池的挂载根（< 2000 弹幕时）
│ ├── MultiMeshRoot (Node2D) ← MultiMeshInstance2D（2000+ 弹幕时动态启用）
│ ├── EnemyRenderRoot (Node2D) ← 敌人 Sprite2D 节点池
│ ├── VFXRoot (Node2D) ← VFXManager 的粒子节点池（跨场景挂 Autoload 自身）
│ └── ZoneVFXRoot (Node2D) ← 地面效果贴图/Shader 渲染根
├── Player (CharacterBody2D) ← 玩家节点（PlayerManager 的 View 层）
│ ├── Sprite2D
│ ├── AnimationPlayer
│ └── CollisionShape2D
└── HUDLayer (CanvasLayer, layer=5) ← 战斗 HUD（血条、法术槽、波次信息）
├── HPBar (ProgressBar)
├── WaveLabel (Label)
├── SpellSlotPanel (HBoxContainer)
├── DamageNumberPool (Node) ← 伤害数字节点池（弹出后自动归还）
└── MiniMap (Control) ← S3 实现
```
#### CanvasLayer 分层规则
| Layer | 用途 | 挂载场景 |
| :--- | :--- | :--- |
| 0 | 世界空间（无 CanvasLayer） | World 节点树 |
| 5 | 战斗 HUD（跟随 Viewport） | BattleScene > HUDLayer |
| 8 | 商店 / 背包 UI（模态）| ShopManager 动态创建 |
| 10 | 全局 UI（主菜单 / 过渡动画 / 暂停菜单）| Main > UILayer |
| 15 | 调试叠加层（仅 Debug 构建） | Main > DebugLayer |
---
### 9.2 Autoload 初始化顺序（project.godot 注册顺序）
Godot 按 `project.godot [autoload]` 中的声明顺序依次调用 `_ready()`。下表定义了强制顺序及原因：
| 顺序 | Autoload 名 | 文件 | 依赖（_ready() 中调用的其他 Autoload） |
| :--- | :--- | :--- | :--- |
| 1 | `CrashReporter` | `crash_reporter.gd` | 无（最先，捕获所有后续初始化崩溃） |
| 2 | `EventID` | `event_ids.gd` | 无（纯常量，1–21）|
| 3 | `DamageType` | `damage_type.gd` | 无（纯常量） |
| 4 | `StatusID` | `status_id.gd` | 无（纯常量） |
| 5 | `CoreFeatureTag` | `core_feature_tag.gd` | 无（纯常量） |
| 6 | `AudioBusID` | `audio_bus_id.gd` | 无（纯常量，Bus index 整数）|
| 7 | `ObjectPool` | `object_pool.gd` | 无（通用对象池，S0 起全局使用，impl §2.1 Layer-0）|
| 8 | `TimeManager` | `time_manager.gd` | 无（时间缩放/GameTick，impl §2.1 Layer-0）|
| 9 | `EventBus` | `event_bus.gd` | 无（事件总线基础设施，其他 Manager 订阅事件需要它先就绪） |
| 10 | `DamageContextPool` | `damage_context_pool.gd` | 无（独立池，预分配 64 个槽） |
| 11 | `SubPayloadRegistry` | `sub_payload_registry.gd` | 无 |
| 12 | `SpatialGrid` | `spatial_grid.gd` + `SpatialGridCs.cs` | 无（C# 子节点在其 _ready() 中 add_child） |
| 13 | `SpellRegistry` | `spell_registry.gd` | 无（同步扫描加载 .tres） |
| 14 | `PassiveRegistry` | `passive_registry.gd` | 无（同步扫描加载 PassiveDef .tres） |
| 15 | `StatusRegistry` | `status_registry.gd` | 无（同步扫描加载 StatusTypeDef .tres） |
| 16 | `ProfileManager` | `profile_manager.gd` | 无（存档读写；Run存档:run_a/b.json，设置:save_data.json）|
| 17 | `SettingsManager` | `settings_manager.gd` | `ProfileManager`（读取用户音量/辅助功能设置） |
| 18 | `BulletManager` | `bullet_manager.gd` + `BulletManagerCs.cs` | `SpatialGrid`（spawn 时写入格子） |
| 19 | `EnemyManager` | `enemy_manager.gd` + `EnemyManagerCs.cs` | `SpatialGrid`（敌人位置写入格子）, `DamageContextPool` |
| 20 | `MinionManager` | `minion_manager.gd` | `SpatialGrid`, `EnemyManager`（友伤判断）, `EventBus` |
| 21 | `StatusManager` | `status_manager.gd` + `StatusManagerCs.cs` | `StatusRegistry`, `DamageContextPool`, `EventBus` |
| 22 | `ZoneManager` | `zone_manager.gd` + `ZoneManagerCs.cs` | `SpatialGrid`, `StatusManager` |
| 23 | `SpellEvaluator` | `spell_evaluator.gd` + `SpellEvaluatorCs.cs` | `SubPayloadRegistry`, `BulletManager`, `DamageContextPool`, `EventBus` |
| 24 | `PlayerManager` | `player_manager.gd` | `SpellEvaluator`, `PassiveRegistry`, `EventBus`, `ProfileManager` |
| 25 | `VFXManager` | `vfx_manager.gd` | `EventBus` |
| 26 | `AudioManager` | `audio_manager.gd` | `SettingsManager`（初始音量）, `EventBus` |
| 27 | `UIManager` | `ui_manager.gd` | `EventBus`（订阅 GAME_STATE_CHANGED 等）|
| 28 | `CoreRegistry` | `core_registry.gd` | 无（纯只读注册表，扫描 res://resources/cores/）|
| 29 | `ConsumableRegistry` | `consumable_registry.gd` | 无（纯只读注册表，扫描 res://resources/consumables/）|
| 30 | `BossManager` | `boss_manager.gd` | `EnemyManager`, `EventBus` |
| 31 | `WaveManager` | `wave_manager.gd` | `EnemyManager`, `BossManager`, `EventBus` |
| 32 | `DropManager` | `drop_manager.gd` | `EnemyManager`, `PlayerManager`, `SpellRegistry`, `EventBus` |
| 33 | `UpgradeSystem` | `upgrade_system.gd` | `PlayerManager`, `SpellEvaluator`, `EventBus` |
| 34 | `ShopManager` | `shop_manager.gd` | `PlayerManager`, `SpellRegistry`, `PassiveRegistry`, `CoreRegistry`, `ConsumableRegistry`, `EventBus` |
| 35 | `GameCycleManager` | `game_cycle_manager.gd` | **所有以上 Manager**（协调者，最后初始化） |
> **初始化安全规则**：编号 N 的 Autoload 的 `_ready()` 中只能调用编号 < N 的 Autoload。若发现需要访问编号 ≥ N 的 Autoload，必须延迟到 `_ready()` 后的第一个 `_process()` 帧，或通过 `EventBus` 信号触发。
>
> **C# 子节点时机**：C# 子节点（`BulletManagerCs` 等）在其 GDScript Autoload 的 `_ready()` 中通过 `add_child()` 挂载。C# 子节点的 `_Ready()` 在 `add_child()` 返回前同步调用（Godot 规范），因此 C# 子节点可以安全访问其 GDScript 父节点，但不得直接访问尚未初始化的其他 Autoload（通过 `GetNode("/root/XXX")` 延迟获取）。