# 游戏设计说明书：魔法工匠 (Arcane Artificer)

## 1. 游戏概述 (Game Overview)

**《魔法工匠》** (暂定名) 是一款融合了 **Roguelite 割草动作** 与 **深度法术编程** 的快节奏射击游戏。

玩家扮演一名被困在异次元的“土豆工匠”，必须利用手中的核心（法杖）和收集到的法术芯片，组装出毁天灭地的魔法武器，抵御无穷无尽的怪物潮。

本游戏的核心差异点在于：**你捡到的不是武器，而是逻辑与弹头的碎片。你必须像程序员一样“编写”你的子弹。**

---

## 2. 核心体验与特色 (Core Experience)

### 2.1 "Noita" 遇上 "Brotato"
*   **快节奏战斗**：继承 Brotato 的短短波次（每波 60-90 秒），自动射击，高密度怪物，让玩家肾上腺素飙升。
*   **深深度构建**：继承 Noita 的法杖编辑深度。战斗之余的商店阶段，是冷静思考、调整“代码”的时间。

### 2.2 真正的模块化 (True Modularity)
不像传统游戏那样只是“加一个火属性配件”，本作允许玩家构建复杂的逻辑链。
*   *例如*：“当子弹击中墙壁时，生成一个炮台，炮台每秒发射三枚追踪冰弹。”

### 2.3 性能怪兽
得益于底层的 **ECS-Lite (Autoload Manager-based)** 和 **Spatial Grid** 技术，游戏支持同屏 **1000+** 敌人和 **2000+** 独立运算的弹幕，每一次爆炸都不仅是贴图，而是真实的物理/逻辑判定。

---

## 3. 武器系统详解：法术管道 (The Spell Pipeline)

这是游戏最核心的玩法。武器由 **“核心 (Core)”** 和 **“法术节点 (Spell Node)”** 组成。

### 3.1 核心 (The Core)
核心相当于“枪身”或“主板”。它决定了基础属性：
*   **插槽数 (Capacity)**: 能插多少个法术芯片。
*   **回蓝速度 (Mana Charge)**: 每秒恢复多少法力。
*   **最大魔力 (Mana Max)**: 蓝条上限。
*   **施法频率 (Cast Rate)**: 每秒执行多少次主循环。
    > **术语说明**：技术文档（`core_wand_design.md`、`numerical_design.md`）统一使用
    > **Cast Delay（施法后摇）** 表示同一概念的倒数形式（`cast_delay = 1 / cast_rate`）。
    > 设计文档（GDD）用 Cast Rate（"快慢"直觉更好）；实现层用 Cast Delay（"乘算系数"更方便计算）。
    > 两者映射关系：`base_cast_delay = 0.25s` → `cast_rate = 4 次/秒`（默认）。
*   **拓扑结构**: 所有的核心都有一个 Main 入口，但高级核心可能有额外的 "OnKill"（击杀时）或 "OnHit"（受击时）入口插槽。

### 3.1.A 多 Core 持有与激活规则 (Multi-Core Rules)

> 这是最基础的游戏规则，所有构建策略以此为前提。

*   **同时激活数量上限**: 玩家在战斗中**同时激活 1 个 Core**（激活的 Core 持续执行其主循环自动射击）。
*   **背包携带上限**: 背包最多同时持有 **3 个 Core**（含当前激活的 1 个）。超出时商店购买会提示选择丢弃或出售。
*   **切换时机**: 仅可在 **商店阶段（非战斗期间）** 切换激活的 Core；战斗中不可切换。
*   **插槽独立**: 每个 Core 的法术插槽互相独立，切换 Core 时旧 Core 插槽内容保留，不适配的卡移入等待区（规则见 §5.G5）。
*   **特殊机制 `dual_stream` Core**（史诗级 Feature Tag）: 此类 Core 自身内部拥有两条并行执行流（从头尾各执行一次），**并非同时激活两个 Core**，不突破"同时激活 1 个"的规则。
*   *设计意图*：限制同时激活数量避免 Brotato 式"堆满武器"的感官疲劳，同时背包存 3 个让玩家有转型预备的空间。

### 3.2 法术芯片 (Spell Chips)
法术分为四大类，通过排列组合产生无限可能。

#### A. 动作类 (Actions) - 实际产生的飞行物
*   **魔法弹 (Spark Bolt)**: 基础伤害，低蓝耗。
*   **黑洞 (Black Hole)**: 吸附敌人，无伤害。
*   **治疗雾 (Healing Mist)**: 范围回血。

#### B. 修正类 (Modifiers) - 改变下一个动作的属性
*   **伤害增强 (Damage+)**: 蓝耗+10，伤害+20。
*   **弹道折射 (Bounce)**: 子弹遇墙反弹。
*   **多重施法 (Multicast)**: 同时发射后面 2 个动作。
*   **甚至有“数学修正”**: 比如 `Sin(Time)` 让子弹走正弦波轨迹。

#### C. 触发器类 (Triggers) - 逻辑的传递
这是构建“子母弹”的关键。
*   **击中触发 (Trigger On Hit)**: 这个子弹本身伤害很低，但它击中敌人时，会以敌人为原点，**施放**这个芯片后面的法术。
*   **定时触发 (Timer)**: 子弹飞行 0.5秒 后，施放后面的法术。

#### D. 逻辑门类 (Logic Gates) - 自动化的灵魂
这是超越 Noita 的设计，让武器变智能。
*   **IF_HP_LOW**: 如果玩家血量 < 30%，执行后续法术，否则跳过。
*   **IF_ENEMY_CLOSE**: 如果 2米内 有敌人，执行后续法术。
*   **LOOP**: 循环执行后续 3 个法术 5 次（适合做激光加特林）。

### 3.3 扩展玩法设计 (Extended Gameplay Mechanics)

为了让构建过程不仅是“堆数值”，我们引入了三个深度维度：

#### A. 拓扑与空间构建 (Topology & Spatial Building)
核心（Core）不只是一个列表，而是一个**2D 电路板**。
*   **物理邻接 (Adjacency)**：每个插槽可能有特殊的加成方向。
    *   *示例*：一个“增压核心”中间有一个红色插槽，标明“右侧插槽获得双倍效果”。
*   **电路分流 (Circuit Splitting)**：电路板上可能有分支。
    *   *玩法*：使用 [分流器] 法术，将“电爆”效果只输送给上面的路线，将“冰冻”效果只输送给下面的路线。

#### B. 逻辑与自动化 (Logic & Automation)
引入变量寄存器，让法杖拥有简单的“图灵完备性”。
*   **Global Registers (全局寄存器)**：允许在这个核心内读写变量 `A`, `B`。
*   **构建示例 - "蓄力逻辑"**:
    *   `[Set A = A + 1]` -> `[IF A < 100 THEN END]` -> `[Set A = 0]` -> `[终极核弹]`
    *   *效果*：这个法杖平时只会空转（每帧 A+1），直到第 100 帧时，才会发射一枚核弹。相当于自动蓄力 1.6秒。
*   **玩家呈现策略（P5-C1）**：寄存器 `A/B` 的读写操作**不直接作为可购买法术卡暴露给普通玩家**。游戏将寄存器操作封装为具体功能的法术卡：
    *   「蓄力计数器」卡：内置完整的计数→阈值判断→重置→执行逻辑，卡面属性为"蓄力阶数 N"，玩家感知为"蓄力 N 次后释放一次"。
    *   「击杀连击」卡：内置 ON_KILL 计数→阈值→爆发→重置，玩家感知为"积累 5 击杀触发爆发"。
    *   「裸寄存器模式」仅通过 **Tier 3+ 的「DEBUG 核心」**解锁，作为面向硬核玩家的高阶自定义工具，不作为默认游戏体验推送。

#### C. 炼金共鸣 (Alchemical Resonance)
这是隐藏的合成系统。当某些特定属性的法术在执行链中直接相邻时，会发生**质变**。
*   `[水属性波]` + `[闪电链]` -> **自动合成** -> `[等离子风暴 (Plasma Storm)]`
    *   *效果*：原本是两个独立的法术，现在融合成了一个全新的强力法术，无需消耗额外的插槽。
*   这鼓励玩家去尝试各种元素的排列组合，寻找隐藏配方。
*   **触发范围权威规则**：绝大多数共鸣配方要求两张法术卡 **直接相邻**（`match: "adjacent"`）。
    少数传说级配方允许跨 Deck 任意位置触发（`match: "anywhere_in_deck"`），但此类配方
    在 `resonance_recipes.json` 中标注 `"rarity": 3`，且性能开销较高（O(N²) 全局扫描），
    数量会严格控制。详见 `architecture_design.md §3.4.C`。
*   **配方发现机制（P5-C2）**：共鸣配方默认隐藏。玩家**首次实际触发某配方**后，图鉴自动解锁并展示该配方的完整描述（触发效果、参与元素、法术 ID）。触发前，图鉴仅展示"某两种元素似乎能产生反应…"的模糊提示（仅显示参与元素的属性标签，不透露具体法术 ID），引导探索而非强制查询外部攻略。

### 3.4 构建示例 (Build Examples)

1.  **“霰弹枪”构建**:
    *   `[三双重施法]` -> `[扩散修正]` -> `[子弹]` -> `[子弹]` -> `[子弹]`
    *   *效果*：一次射出三发散开的子弹。

2.  **“运载核弹”构建**:
    *   `[定时触发(1s)]` -> `[速度为0修正]` -> `[伤害增强]` -> `[伤害增强]` -> `[巨型爆炸]`
    *   *效果*：射出一个普通子弹，1秒后在空中停滞，然后引发核爆。

3.  **“吸血炮台”构建**:
    *   `[击中触发]` -> `[召唤静止炮台]` -> `[炮台指令: 击中触发]` -> `[连锁闪电]` -> `[吸血修正]`
    *   *效果*：你射中地板，地板上长出一个炮台，炮台射出的闪电会连环电击敌人并把血吸给你。

---

## 4. 数值策划 (Numeric Planning)

为了支撑如此复杂的构建，数值系统必须严谨且具备极其宽广的边界。

### 4.1 核心资源：魔力 (Mana)

> **⚠️ 实现现状 (2026-07-20 审计 → MVP 已实现)**：Mana 精实 MVP 已落地——`PlayerStats` 蓝池（`mana`/`mana_max`/`mana_regen`）、`CoreDefinition.base_mana_max/regen`（cores.json）、每法术 `mana_cost`（numerical §2）、`SpellEvaluator` 逐节点扣蓝 + 蓝空停施、HUD 蓝条。**已补全**：递增蓝耗、`infinite_spells` 扣血、魔力虹吸（多来源）、HUD 打磨。**仍暂缺**：全局+法杖取 Min、cast_delay。详见 `docs_dev/specs/2026-07-20-mana-system-mvp-design.md`。

为了防止无限“加特林核弹”，限制资源是 **魔力**。
*   强力修正器（如伤害+100）会有巨大的 **Delay (施法后摇)** 和 **Mana Cost (蓝耗)**。
*   **平衡点**：高射速 = 低单发伤害；高爆发 = 便秘的手感（打一发回蓝3秒）。

### 4.2 伤害公式 (The Formula)

> 完整权威公式定义该文件 `docs/design/numerical_design.md §3.1`。

$$ FinalDamage = ((Base + \sum Mod_{flat}) \times \prod Mod_{mult}) \times (1 - Res) - Armor $$

*   **Base**: 法术动作的基础伤害 (e.g., 火球 10点)。
*   **Mod_flat**: 修正器的数值加成 (e.g., +5伤害)。
*   **Mod_mult**: 玩家天赋/暴击带来的百分比乘区 (e.g., 火焰伤害 +50%)。
*   **Res**: 敌人元素抗性 (0.0~1.0)。
*   **Armor**: 敌人护甲平铺扣除值（固定数值，不受百分比影响）。最终伤害最小为 1。

### 4.3 属性词条池 (Stats Pool) — *MVP 层*

> **⚠️ 实现现状 (2026-07-20 审计)**：下表 5 条 MVP 属性中**仅 CPU（`cpu_limit`）实现**——且因 `MAX_OPS` 硬编码不读 cpu_limit，连它也对施法预算无效（见架构文档 §3.4 现状注）。Cast Speed / Mana Leech / Accuracy / Attunement 均未实现。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。

玩家在升级或商店中购买的属性，直接影响构建的上限。

> ⚠️ **MVP 说明**：以下 5 条属性为 MVP 阶段实现目标。后续扩充方向：
> 第二批（防御类）：护甲穿透、元素抗性降低、格挡概率。
> 第三批（资源类）：击杀回血（吸血）、金币掉落增益、法力吸取。
> 第四批（移动类）：冲刺距离、鬼影残影、落身位置标记。

| 属性名 | 影响 | 备注 |
| :--- | :--- | :--- |
| **施法速度 (Cast Speed)** | 减少每个法术块的执行时间 | 堆高了可以把“狙击枪”变成“冲锋枪” |
| **魔力虹吸 (Mana Leech)** | 击杀回复魔力 | 续航流派的核心 |
| **散射控制 (Accuracy)** | 减少弹道随机偏转角 | 修正“多重施法”带来的精准度惩罚 |
| **运算力 (CPU)** | 增加核心的插槽上限 | 决定了你能组多复杂的法术 |
| **元素精通 (Attunement)** | 增加特定元素（火/冰/电/毒）的触发概率和伤害 | 每点 Attunement 使对应元素伤害 +3% 且元素状态触发概率 +2%；详见 `numerical_design.md §1.1` |

### 4.4 怪物成长曲线
*   **波次 1-5**: 纯数值验证（血量低，无抗性）。
*   **波次 6-10**: 机制验证（出现 **反弹护盾怪**、**高护甲怪**）。这迫使玩家必须构建“穿透”或“元素伤害”来应对。
*   **波次 11-20**: 弹幕地狱。怪物的数量呈指数上升，考验玩家构建的 **AOE 覆盖率** 和 **FPS 优化**。

### 4.5 Boss 设计框架 (Boss Design)

Boss 出现于特定里程碑波次，强制验证玩家构建的适应性。

> **⚠️ 实现现状 (2026-07-20 审计)**：本节多为设计蓝图，代码差异较大。① **波次**：精英/Mini Boss 实际在 **W8**（非本节标题的 W10），最终 Boss 在 W20（`waves.json`）。② **阶段阈值**：代码统一用 **66%/33%**，非下方 JSON schema 的 50%/10%。③ **血量**：代码取 `balance.json` 的 450(mini)/1800(final)，与 `numerical_design §3.2` 的 50000 冲突（DPS 门槛测算已失真）。④ **未实现**：元素抗性 `(1-Res)`、镜像法师反射、重甲降甲、`regen_on_physical_hit` 虚空再生、NG+ Phase4——Boss 现状只是会在血线召唤 FAST 援军的厚血怪。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。

#### W10 精英 Boss （第 10 波）
*   **功能**: 展示某一核心机制的利用方式。
*   **典型设计示例**:
    *   **镜像法师**: 反射所有正面 PHYSICAL 投射物，逼迫玩家必须配备至少一个元素伤害 ACTION 或使用 MODIFIER: pierce。
    *   **重甲领主**: 自身有层层叠加的护甲，每次受到指定元素伤害时降低一层，验证玩家 **Stacking** 构建的强度。

#### W20 最终 Boss（第 20 波）
*   **功能**: 综合检验所有核心玩法的适应性。
*   **阶段设计**:
    1.  **Phase 1** (全血): 高层抗性，对【共鸣效果】或特定元素伤害几乎无抵抗（正常受击）。纯物理构建并非硬性免疫，但每次物理命中触发 Boss 的"虚空再生"（每次物理命中恢复 `regen_on_physical_hit = 0.5%` 最大血量），形成动态 DPS 门槛——高 DPS 物理构建仍可磨血，但效率远不如元素/共鸣流，引导玩家主动考虑构建多样性。
    2.  **Phase 2** (50% 血量): 开始弹幕攻势，玩家必须在走位的同时输出足够 DPS。
    3.  **Phase 3** (杀死前): 爆发全屏投射物，考验玩家现有弹道规避构建的极限。
*   **设计原则**: Boss 无法被"无脑通关"（一种构建就能轻松将其秒杀）；每个阶段应着重考察一个核心机制。

#### Boss 行为数据格式 (Boss Behavior Schema — P5-E1)

Boss 阶段数据完全由 JSON 驱动（`res://resources/bosses/boss_XX.json`），关卡设计师无需改代码即可调整 Boss 行为：

```json
{
  "boss_id": "void_lord_w20",
  "display_name": "虚空领主",
  "wave": 20,
  "phases": [
    {
      "phase": 1,
      "hp_threshold_enter": 1.0,
      "hp_threshold_exit": 0.5,
      "resistances": { "PHYSICAL": 0.8, "FIRE": 0.1, "ICE": 0.1, "LIGHTNING": 0.1 },
      "regen_on_physical_hit": 0.005,
      "behavior_tags": ["stationary", "spread_projectiles"],
      "projectile_pattern": "spread_8"
    },
    {
      "phase": 2,
      "hp_threshold_enter": 0.5,
      "hp_threshold_exit": 0.1,
      "resistances": { "PHYSICAL": 0.3, "FIRE": 0.1, "ICE": 0.1, "LIGHTNING": 0.1 },
      "regen_on_physical_hit": 0.0,
      "behavior_tags": ["chase_player", "barrage_mode"],
      "barrage_interval": 3.0
    },
    {
      "phase": 3,
      "hp_threshold_enter": 0.1,
      "hp_threshold_exit": 0.0,
      "resistances": {},
      "behavior_tags": ["enrage", "fullscreen_burst"],
      "burst_interval": 5.0
    }
  ],
  "ng_plus_phase": {
    "phase": 4,
    "unlock_condition": "ng_plus",
    "hp_threshold_enter": 0.0,
    "hp_threshold_exit": -0.3,
    "note": "NG+ 专属第四阶段：Boss 在 0% HP 时触发'最后意志'，暂时无敌 5 秒，HP 回复至 30%，进入超狂暴状态",
    "resistances": { "PHYSICAL": 0.5 },
    "regen_on_physical_hit": 0.0,
    "behavior_tags": ["last_will", "hyper_enrage", "clone_summon"],
    "clone_count": 2,
    "invincible_duration": 5.0,
    "hp_restore_ratio": 0.3,
    "burst_interval": 2.0
  }
}
```

> **字段说明**：`resistances` 为各元素抗性（0.0 = 无抵抗，1.0 = 完全免疫）；`regen_on_physical_hit` 为每次物理命中触发的生命恢复比例（Phase 1 动态门槛的数据实现）；`behavior_tags` 驱动 `BossAI` 状态机的行为策略选择。`ng_plus_phase` 字段仅在 NG+ 模式下由 `BossAI` 读取——普通模式下此字段存在但不生效（`unlock_condition` 检查决定是否激活）。Phase 4 的 `hp_threshold_exit: -0.3` 表示 Boss 在"回复后血量"归零后才真正死亡，防止普通模式下意外触发。

---

## 5. 游戏循环 (Gameplay Loop)

1.  **准备 (The Lab)**:
    *   界面左侧是背包（存放法术卡），右侧是核心（插槽）。
    *   玩家将卡牌拖入插槽，点击”测试按钮”，在一个安全的靶场内测试射击效果，还有 DPS 统计面板。
    *   **防呆机制**：点击”进入战斗”时，系统先对 Deck 进行验证：若全部插槽均为空或仅含 MODIFIER/TRIGGER 而无任何 ACTION 类型法术，展示警告弹窗”法术塔无法开火！需要至少一个行动类法术。”并阻止进入。
    *   **深度玩法**：调整卡牌顺序，比如把 [伤害增强] 放在 [多重施法] 之前还是之后，效果截然不同。

2.  **战斗 (The Arena)**:
    *   倒计时 60 秒。
    *   玩家自动使用构建好的武器射击。
    *   主要操作：走位躲避弹幕，拾取掉落的”法力核心”（钱）。
    *   **走位-构建互动 (G4)**：部分法术对玩家的移动状态有响应，让走位不只是”跑步”：
        *   **移动增益型法术**（如”电冲弹”）：玩家处于运动状态时该法术伤害 ×1.5，静止时恢复基准值。
        *   **冲刺波（Dash Wave）型核心**：特定 Core 属性，玩家触发冲刺动作时自动在冲刺轨迹上释放一次附加法术（消耗独立冷却，不走主 Deck 队列）。
        *   **停步蓄力型法术**（如”引力奇点”）：玩家静止超过 1.5 秒时触发蓄力，停止移动后立即释放一次超载版本（DMG ×3）；一旦移动则蓄力清零。
            *   **UI 反馈**：静止后 0.3 秒开始显示蓄力进度环（天空蓝，展示 1.5 秒倒计时）；蓄力满时进度环闪烁并播放充能音效；移动就进度环消失。进度环由 `UIManager` 经 EventBus `CHARGE_STATE_CHANGED` 事件驱动，不得在 `SpellEvaluator` 中直接操作 UI 节点。
        *   *设计意图*：玩家可以通过选择法术类型来主动决定”走位风险收益比”，使操作与构建选择相互影响。
3.  **购物 (The Shop)**:
    *   战斗结束，进入商店。
    *   **货架 A**: 出售新的法术卡片（随机池）。
    *   **货架 B**: 出售新的”核心”（更牛的主板）。 ⚠️**未实现**（现状商店仅货架 A 法术抽取；货架 C 属性、出售退款 G5 亦未实现）
    *   **货架 C**: 基础属性提升（生命值、暴击率）。
    *   **出售与转型规则 (G5)**：
        *   玩家可在商店界面将背包中的法术卡**出售**，回收该卡购入价格的 **50%**（下限 10G）。
        *   更换 Core 时，原 Core 不适配的法术卡（插槽类型不匹配）将自动移入**等待区**（上限 5 张）；超出 5 张的部分，玩家必须手动选择出售或丢弃。
        *   等待区中的卡可在下次商店阶段重新插入新 Core，或继续出售。
        *   *设计意图*：转型有真实代价——金币折损 + 等待区占位；鼓励玩家谨慎决策而非随意重构。
    *   *经济策略*：是买一个强力的”黑洞”法术？还是把钱用来升级”回蓝速度”以支撑现有的构建？

## 6. 新手引导设计 (Onboarding)

Roguelite 的"第一把"体验至关重要。系统复杂度必须渐进式解锁，避免一次性呈现所有概念。

### 6.1 渐进式解锁顺序

| 第几局 | 开放内容 | 目的 |
| :--- | :--- | :--- |
| 局 1 | 预设法杖（只有 3 个 Spark Bolt），只教走位 | 零门槛上手，感受割草爽感 |
| 局 2 | 解锁"法杖编辑"，仅开放 Tier 1 法术 | 体验最简单的换弹 |
| 局 3 | 引入第一张 Modifier（伤害增强）+ Tooltip 教学 | 理解 Modifier 放在 Action 之前生效 |
| 局 4 | 引入第一张 Trigger（击中触发）+ 靶场演示 | 看到"子母弹"视觉效果 |
| 局 5+ | Tier 2 法术、Logic 类法术逐步开放 | 自由探索 |

### 6.2 情境提示 (Contextual Tips)
*   当玩家第一次持有 Trigger 但没有配套 Action 时，显示提示："触发器需要在其后面放置动作才能生效 →"。
*   当玩家 `cpu_limit` 占用超过 80% 时，运算力进度条变红并显示："运算力不足，法杖将无法完整执行"。
*   商店中首次出现特殊 Core（如 `matrix_board`）时，显示简短动画演示邻接加成效果。

### 6.3 靶场 (Training Range)
在**每次**进入商店阶段时，靶场始终可用：
*   右侧显示实时 DPS 数字。
*   点击"慢放"按钮，以 0.1x 速度演示法术链的执行顺序（调试教学用）。

---

## 7. 元进展设计 (Meta-Progression)

> **⚠️ 实现现状 (2026-07-21 → MVP 部分实现)**：**碎片 + 法术解锁树已落地**——`MetaProgress` autoload（`user://meta.json` 碎片+已解锁）、死亡按波次发碎片（`balance.json.aether_thresholds` 阈值表，平衡页签可调）、主菜单「🔓解锁」面板花碎片解锁进阶法术、商店池按 `spells.json` 的 `meta.unlock_cost` 门控。**暂缺**：核心解锁（依赖货架B）、挑战模式解锁、图鉴 Codex、成就/炼金日志、通关首胜奖励。详见 `docs_dev/specs/2026-07-21-meta-progression-mvp-design.md`。

元进展是 Roguelite 的长期粘性来源。玩家每次游玩都在为"总体库"做出贡献，即使失败也有收获感。

### 7.1 局外货币：以太碎片 (Aether Fragments)
*   **来源**: 每次游玩结束时，按波次数量奖励（W1=0, W5=3, W10=8, W20=20）。
*   **永久保留**，不随死亡重置。

### 7.2 局外解锁树 (Unlock Tree)
用以太碎片解锁**永久加入掉落池**的内容，不直接增强玩家数值：

| 花费 | 解锁内容 | 说明 |
| :--- | :--- | :--- |
| 5 碎片 | 法术：连锁闪电 | 加入商店掉落池 |
| 10 碎片 | 核心：构造板 (matrix_board) | 加入商店掉落池 |
| 15 碎片 | 法术：战术核弹 | 加入商店掉落池 |
| 30 碎片 | 核心：记忆法杖 (persistent_memory) | 加入商店掉落池 |
| 50 碎片 | 挑战模式：诅咒波次 | 解锁额外难度模式 |

### 7.3 图鉴系统 (Codex)
*   玩家每次拾取/购买新法术，自动解锁该法术的图鉴词条（含详细数值和设计意图）。
*   图鉴中显示**元素亲和性标签**，暗示可能的共鸣组合（如"此法术具有 💧 水属性亲和"）。
*   成就：首次触发每种元素反应，解锁对应的"炼金日志"风味文本。

### 7.4 设计原则
*   解锁内容**只扩展可能性**（让玩家看到更多法术），而非直接增强初始属性（避免 P2W 感）。
*   通过 20 局可解锁全部核心内容，给硬核玩家明确的完成感。

---

## 8. 失败、通关与里程碑 (Failure, Victory & Checkpoints)

### 8.1 死亡与失败机制 (G1)

*   **触发条件**：玩家 HP 降至 0 时死亡，当局立即结束。
*   **死亡流程**：
    1. 播放死亡动画与音效。
    2. 统计数据冻结（本局最高波次、总输出伤害、最高单次伤害、击杀总数）。
    3. 显示 **本局总结屏 (Run Summary)**，含构建快照（自动截图保存至 `user://runs/YYYY-MM-DD_run_N.png`）。
    4. 给予以太碎片奖励（按波次阶梯），不因死亡扣减。
*   **唯一例外**：天赋"最后意志 (Last Will)"——允许一次以 1 HP 存活，每局限触发一次，触发后天赋失效。
*   **死亡不回退**：已解锁法术图鉴词条、成就、Meta 解锁树进度，均在死亡后保留。

### 8.2 通关条件与通关后内容 (G2)

> **⚠️ 实现现状 (2026-07-20 审计)**：**通关流程整体未实现**。击败 W20 Boss 后照常结算进商店并继续 W21，无通关演出、无 `GAME_CLEARED` 事件、无 NG+ 解锁；游戏目前只能靠死亡结束。Endless 已实现但为**逐波 ×1.12 膨胀**（非"每 5 波 +10%"），且无 Boss Rush、无全局词条。EndlessRecords 本地排行榜（评分 + HMAC）已实现。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。

*   **通关条件**：击败 W20 终波 Boss（三阶段精英怪），触发通关演出。
*   **首通奖励**：
    *   给予 30 以太碎片（固定）。
    *   解锁 **New Game+ (NG+)** 模式：全局敌人属性 ×1.5、弹幕速度 +30%、Boss 新增第四阶段。
*   **NG+ 递增**：每次 NG+ 通关再给予 20 碎片（递减 20%，下限 5）。
*   **无限模式 (Endless)**：W20 通关后可选择继续，每 5 波难度系数 +10%（无上限），用于挑战竞速排行榜，不计入 Meta 进度。
    *   **排行榜技术实现（P6-N19）**：以**到达波次 (Wave Reached)** 为主排名维度，同波次按**总经过时间 (Elapsed Seconds)** 升序排。
        - **本地存储**：`user://endless_records.json`，Schema：`{ "records": [{ "wave": int, "elapsed_sec": float, "build_snapshot": String, "timestamp": int }] }`，保留最近 20 条。
        - **在线排行榜（P2 可选）**：上传分数 = `wave * 100000 + (86400 - elapsed_sec)`，单整数实现双维度排序（波次高优先，同波次用剩余秒数打分）。
        - **防作弊**：本地记录含 `build_snapshot`（Deck checksum），便于审核异常成绩。
    *   **新机制注入 (G7)**：Endless 模式不只是纯数值膨胀，每 10 波（W30/W40/W50...）随机激活一条**全局词条**（每次 1 条，不与前轮叠加，仅保留最新一条）：

        | 词条 | 效果 |
        | :--- | :--- |
        | 镜子世界 | 所有弹道被首次命中后反弹回发射者方向 |
        | 怪物分裂 | 敌人死亡时以 50% HP 分裂为 2 个小型版本（仅分裂 1 次）|
        | 地图缩小 | 可活动区域半径减少 20%（最小 50% 原始大小）|
        | 魔力反转 | 法术 Delay 变为正向加成，原 Delay 越长攻速越快 |
        | 精英泛滥 | 所有普通敌人升级为精英，HP ×2、奖励 ×2 |

    *   每 20 波（W40/W60/W80...）触发 **Boss Rush 片段**：连续出现 3 个 Boss（随机抽取已出现过的 Boss 变体），全部击败后获得大量碎片与特殊法术卡（每次 Boss Rush 保证至少 1 张 Tier 3 卡）。

### 8.3 里程碑与 Checkpoint (G3)

> **⚠️ 实现现状 (2026-07-20 审计)**：本节里程碑体系（W5/W10/W15 奖励与练习模式解锁）**未实现**；练习模式、Boss Rush 均无代码。里程碑碎片依赖的元进展系统（以太碎片/解锁树/图鉴）也未落地。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。

到达 **W5 / W10 / W15** 触发里程碑事件：

| 里程碑 | 即时奖励 | 解锁内容 |
| :--- | :--- | :--- |
| W5 | 以太碎片 ×2 | 解锁 W5 练习模式起点 |
| W8 | — | **Mini Boss 首现警告波**（非里程碑；仅首次到达时弹出提示，Boss 数据进入图鉴）|
| W10 | 以太碎片 ×3 | 解锁 W10 练习模式起点；W10 精英 Boss 激活 |
| W15 | 以太碎片 ×4 | 解锁 W15 练习模式起点 |

*   **里程碑碎片加成**缓解高波次死亡的挫败感（玩家不会"一无所获"）。
*   **练习模式 (Practice Mode)**：从任意已到达的里程碑波次开始，无限时间商店，不计入 Meta 进度也不消耗里程碑次数；用于测试新构建。

---

## 9. 总结
《魔法工匠》不只是一款“幸存者”游戏，它是一个**带有动作外壳的逻辑解谜游戏**。每一个通过第 20 波的玩家，都是一名合格的“魔法软件工程师”。