docs: 整理文档目录并对齐代码现状
- 将开发过程/归档文档迁至 docs_dev/（development_plan、certification_checklist、 已废弃的 Cocos 架构草案 archived_cocos_architecture_draft），并修正全部跨引用 - 新增根 README.md（项目介绍，暂定名 Spellforge）与 docs_dev/README.md 索引 - 新增 docs_dev/doc_code_audit_2026-07-20.md：文档 vs 代码交叉审计报告（经 6 路对抗性复核，零证伪），含「代码更优 / 文档更优 / 中性」判定汇总 - 在 docs/ 各设计·技术·机制文档就地加「实现现状 (2026-07-20)」callout： 追认代码更优实现（纯 JSON 数据驱动、SpatialGrid-only 碰撞、MultiMesh 单档、 存档选最新槽等），订正陈旧/矛盾内容（.tres→JSON、Boss HP/阈值/波次、EventID、 StatusManager.apply 签名等），标记未实现功能（C# 热路径、Mana、元进展、 Boss 阶段/抗性、Tutorial、轨迹/连锁/催化等）与 latent bug（CoreFeatureTag 位运算、 pierce 空操作、MAX_OPS 不读 cpu_limit） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -54,8 +54,9 @@ extends Resource
|
||||
@export var base_cast_delay: float = 0.25 # 基础施法后摇（乘算基准）
|
||||
@export var base_recharge_time: float = 0.5 # 完整一轮打完后的充能时间
|
||||
|
||||
## Core 特性标签 (Array[String])，驱动特殊执行规则
|
||||
## 例如: ["persistent_memory", "dual_stream", "shuffle_deck"]
|
||||
## Core 特性标签，驱动特殊执行规则
|
||||
## ⚠️ 实现现状(2026-07-20)：代码实为 `@export var feature_tags: int = 0`（int 位掩码，非 Array[String]）；
|
||||
## CoreFeatureTag 常量为 int 1..5 并用 `&` 判定——值非 2 的幂有位冲突 bug（见审计 D 节）。
|
||||
@export var feature_tags: Array[String] = []
|
||||
|
||||
## 图标路径
|
||||
@@ -92,7 +93,7 @@ extends Resource
|
||||
| **ACTION** | **ACTION**（同 ID） | 完全相同的 ACTION 对齐 | 伤害 ×1.5（`damage_mult +0.5`） | "强化同类弹" |
|
||||
| **ACTION** | **MODIFIER** | 任意 | 该 MODIFIER 效果额外再施加一次（等效双倍加成） | "增幅器加倍" |
|
||||
| **MODIFIER** | **MODIFIER**（同 ID） | 完全相同的 MODIFIER 对齐 | 修正值 ×2（平直叠加而非乘算） | "共鸣修正" |
|
||||
| **ACTION** | **TRIGGER** | 任意 | 该 TRIGGER 的 `proc_rate ×1.5`（最大 1.0） | "增压触发" |
|
||||
| **ACTION** | **TRIGGER** | 任意 | 该 TRIGGER 的 `proc_rate ×1.5`（最大 1.0） | "增压触发" ⚠️**未实现**（代码只实现 ACTION+ACTION / ACTION+MODIFIER / MODIFIER+MODIFIER 三行）|
|
||||
| **LOGIC** | **任意** | 任意 | 无加成（LOGIC 节点不参与邻接计算） | 设计原则：逻辑层不受物理拓扑影响 |
|
||||
| **空槽** | **任意** | 行 A 为空 | 无加成 | 空槽不传递邻接效果 |
|
||||
|
||||
@@ -150,6 +151,8 @@ extends Resource
|
||||
| `infinite_spells` | 法力耗尽时不停止执行，但每发增加 1 点 HP 代价（需配合 `heavy_cost` 法术） | 传说 |
|
||||
| `always_cast_last` | 无论 Deck 如何执行，最后一个插槽的法术在一轮结束时**必定**执行一次 | 稀有 |
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：5 个特性标签中**只有 `persistent_memory` 实现**；`dual_stream` / `shuffle_deck` / `infinite_spells` / `always_cast_last` 在代码里除常量定义外**无任何逻辑引用**（`core_feature_tag.gd:6` 自注"S6 P1 实现"）。下文对这 4 个标签的详细行为规范（P5-N2/P6-N7/P6-N12 等）均为目标设计。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
|
||||
> **实现约束说明（P5-N2）**：
|
||||
> - **`shuffle_deck`**：仅随机化**独立 ACTION 节点**的执行顺序；MODIFIER 节点始终与其紧接的 ACTION 视为原子单元整体移动，防止修正器与错误的动作配对，保持构建意图的确定性。UI 上以"卡组"为单位展示被打乱的顺序，而非单张卡牌。
|
||||
> - **`dual_stream`**：两条执行流**各自独立计算 ops 消耗**，每条流的 MAX_OPS 上限 = `cpu_limit × MAX_OPS_PER_CPU / 2`（平均分配）。双流模式下单帧总指令数与单流相同，不额外增加运算力消耗；实际可用插槽从序列头尾各取一半，两条流不可互相访问对方的槽位。
|
||||
@@ -220,6 +223,7 @@ extends Resource
|
||||
|
||||
# ── 阶段 1：编译（法杖装备/换牌时调用，结果缓存于 CompiledDeck）──────────────────
|
||||
# 参数类型：raw_deck: SpellDeck（通过 deck.nodes[i] 访问节点序列，禁止传入 Array[SpellNode]）
|
||||
# ⚠️ 实现现状(2026-07-20)：真实签名 compile_wand(core, raw_nodes: Array)——第 2 参是 Array 而非 SpellDeck
|
||||
func compile_wand(core: CoreDefinition, raw_deck: SpellDeck) -> CompiledDeck:
|
||||
match core.topology:
|
||||
CoreDefinition.LINEAR:
|
||||
@@ -234,6 +238,7 @@ func compile_wand(core: CoreDefinition, raw_deck: SpellDeck) -> CompiledDeck:
|
||||
# ── 阶段 2：执行（每次施法时调用缓存的 CompiledDeck）────────────────────────────
|
||||
# 必须接受 core: CoreDefinition 参数，用于读取 core.feature_tags 判断寄存器持久策略。
|
||||
# 禁止将 feature_tags 复制到 SpellContext（SpellContext 不持有 Core 引用；ctx.core_feature_tags 不存在）。
|
||||
# ⚠️ 实现现状(2026-07-20)：真实签名 execute_compiled(compiled, caster_id: int, spawn_pos: Vector2)——不传 ctx/core，feature_tags 从 CompiledDeck 编译期快照读取
|
||||
func execute_compiled(compiled: CompiledDeck, ctx: SpellContext, core: CoreDefinition) -> void:
|
||||
_run_deck(compiled, ctx) # SpellEvaluator 不感知拓扑，仅执行线性化节点序列
|
||||
|
||||
|
||||
@@ -131,6 +131,9 @@
|
||||
为了支撑如此复杂的构建，数值系统必须严谨且具备极其宽广的边界。
|
||||
|
||||
### 4.1 核心资源：魔力 (Mana)
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：**Mana 魔力系统完全未实现**——`PlayerStats` 无 mana 变量，法术无蓝耗/回蓝逻辑。作为设计文档声称的核心平衡阀，这是最大的功能缺口之一。当前施法仅受 `MAX_OPS` 与 `Cast Delay` 限制。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
|
||||
为了防止无限“加特林核弹”，限制资源是 **魔力**。
|
||||
* 强力修正器（如伤害+100）会有巨大的 **Delay (施法后摇)** 和 **Mana Cost (蓝耗)**。
|
||||
* **平衡点**：高射速 = 低单发伤害；高爆发 = 便秘的手感（打一发回蓝3秒）。
|
||||
@@ -148,6 +151,9 @@ $$ FinalDamage = ((Base + \sum Mod_{flat}) \times \prod Mod_{mult}) \times (1 -
|
||||
* **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 阶段实现目标。后续扩充方向：
|
||||
@@ -172,6 +178,8 @@ $$ FinalDamage = ((Base + \sum Mod_{flat}) \times \prod Mod_{mult}) \times (1 -
|
||||
|
||||
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 波）
|
||||
* **功能**: 展示某一核心机制的利用方式。
|
||||
* **典型设计示例**:
|
||||
@@ -265,7 +273,7 @@ Boss 阶段数据完全由 JSON 驱动（`res://resources/bosses/boss_XX.json`
|
||||
3. **购物 (The Shop)**:
|
||||
* 战斗结束，进入商店。
|
||||
* **货架 A**: 出售新的法术卡片（随机池）。
|
||||
* **货架 B**: 出售新的”核心”（更牛的主板）。
|
||||
* **货架 B**: 出售新的”核心”（更牛的主板）。 ⚠️**未实现**（现状商店仅货架 A 法术抽取；货架 C 属性、出售退款 G5 亦未实现）
|
||||
* **货架 C**: 基础属性提升（生命值、暴击率）。
|
||||
* **出售与转型规则 (G5)**：
|
||||
* 玩家可在商店界面将背包中的法术卡**出售**，回收该卡购入价格的 **50%**（下限 10G）。
|
||||
@@ -302,6 +310,8 @@ Roguelite 的"第一把"体验至关重要。系统复杂度必须渐进式解
|
||||
|
||||
## 7. 元进展设计 (Meta-Progression)
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：**本章整体未实现**——以太碎片局外货币、局外解锁树、图鉴 Codex、成就系统在代码中均无实现（仅 1 个孤立未接线的 `ACHIEVEMENT_UNLOCKED` 事件常量）。属 Roguelite 长期粘性核心，为后续切片的功能待办。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
|
||||
元进展是 Roguelite 的长期粘性来源。玩家每次游玩都在为"总体库"做出贡献，即使失败也有收获感。
|
||||
|
||||
### 7.1 局外货币：以太碎片 (Aether Fragments)
|
||||
@@ -345,6 +355,8 @@ Roguelite 的"第一把"体验至关重要。系统复杂度必须渐进式解
|
||||
|
||||
### 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 以太碎片（固定）。
|
||||
@@ -369,6 +381,8 @@ Roguelite 的"第一把"体验至关重要。系统复杂度必须渐进式解
|
||||
|
||||
### 8.3 里程碑与 Checkpoint (G3)
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：本节里程碑体系（W5/W10/W15 奖励与练习模式解锁）**未实现**；练习模式、Boss Rush 均无代码。里程碑碎片依赖的元进展系统（以太碎片/解锁树/图鉴）也未落地。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
|
||||
到达 **W5 / W10 / W15** 触发里程碑事件：
|
||||
|
||||
| 里程碑 | 即时奖励 | 解锁内容 |
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
| `cast_delay_mod` | 施法延迟修正 | 1.0 (100%) | 0.1 | 0.01 | 越低越快，乘算系数 |
|
||||
| `recharge_speed_mod` | 充能速度修正 | 1.0 (100%) | 5.0 | - | 越低越快 |
|
||||
| `luck` | 幸运 | 0 | 100 | - | 影响高阶法术掉率、暴击率 |
|
||||
| `cpu_limit` | 运算力上限 | 5 | 20 | 50 | `SpellEvaluator` 实际 MAX_OPS = `cpu_limit × 40`（默认 5 → 200 步；软上限 20 → 800 步；硬上限 50 → 2000 步）。升级此属性可执行更复杂的法术链，与 `implementation_plan.md §2.2` 的 `MAX_OPS_PER_CPU = 40` 常量对应。 |
|
||||
| `cpu_limit` | 运算力上限 | 5 | 20 | 50 | `SpellEvaluator` 实际 MAX_OPS = `cpu_limit × 40`（默认 5 → 200 步；软上限 20 → 800 步；硬上限 50 → 2000 步）。升级此属性可执行更复杂的法术链，与 `implementation_plan.md §2.2` 的 `MAX_OPS_PER_CPU = 40` 常量对应。 ⚠️**实现现状(2026-07-20)**：代码硬编码 `MAX_OPS = 40×5 = 200`，**从不读 cpu_limit**——升级此属性对施法预算无效（待修，本设计更优）。 |
|
||||
| `attunement_fire` | 火焰精通 | 0 | 50 | 100 | 每点：火焰伤害 +3%（乘算），火焰状态（点燃/爆燃）触发概率 +2%。影响 `damage_type=FIRE` 的所有投射物。 |
|
||||
| `attunement_ice` | 冰霜精通 | 0 | 50 | 100 | 每点：冰霜伤害 +3%，冰冻/减速触发概率 +2%。 |
|
||||
| `attunement_lightning` | 雷电精通 | 0 | 50 | 100 | 每点：雷电伤害 +3%，麻痹/连锁导电触发概率 +2%。 |
|
||||
@@ -135,7 +135,7 @@ Damage = ((Base + Add) × Mult) × (1 - Res) - Armor
|
||||
| Wave 1 | 杂鱼土豆 | 15 | 100 | 5 | - |
|
||||
| Wave 5 | 冲锋甲虫 | 80 | 250 | 12 | 击退抗性 50% |
|
||||
| Wave 10| 坦克巨兽 | 2000 | 50 | 30 | 护甲 5 (免疫机枪) |
|
||||
| Wave 20| 虚空领主 | 50000| 150 | 100 | 弹幕反射盾 |
|
||||
| Wave 20| 虚空领主 | 50000 ⚠️| 150 | 100 | 弹幕反射盾 |
|
||||
|
||||
### 3.3 波次强度控制 (Pacing)
|
||||
|
||||
@@ -191,6 +191,8 @@ Damage = ((Base + Add) × Mult) × (1 - Res) - Armor
|
||||
### D. W20 Boss Phase 1 DPS 门槛（P6-N17）
|
||||
* **问题**: Phase 1 的 `regen_on_physical_hit = 0.005`（每次物理命中恢复 Boss 最大 HP 的 0.5%）。
|
||||
Boss 最大 HP = 50,000，即每次物理命中回血 **250 HP**。
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：代码 Boss 实际 HP = 450(mini)/1800(final)（`balance.json`，疑为占位），**非 50000**；`regen_on_physical_hit` 虚空再生、反射盾、元素抗性**均未实现**。本节 DPS 门槛测算基于 50000 已失真，需统一血量口径后重算。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
若玩家攻速 10 发/秒（纯物理构建），Boss 每秒净回血 2,500 HP。
|
||||
* **DPS 突破阈值（最低要求）**：物理构建需满足以下条件才能有效磨血：
|
||||
$$DPS_{physical} > \frac{250 \times hit\_rate}{1} \Rightarrow DPS > 2500 \text{（10发/秒时）}$$
|
||||
|
||||
@@ -7,6 +7,8 @@
|
||||
|
||||
---
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：本文档描述的整套 FTUE 架构——`TutorialManager` Autoload、9 步状态机、气泡提示 `tutorial_hint_bubble.tscn`、`hint_*.tres`、情境提示、渐进解锁（局 1-5）、靶场慢放——**均未实现**。现状"新手引导" = 仅**首次启动的难度三选一弹窗**（`main_menu.gd` 的 FTUE 面板 + `SettingsManager.ftue_done`）。下文保留作目标设计。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
|
||||
## 一、设计目标
|
||||
|
||||
| 目标 | 度量标准 |
|
||||
@@ -218,6 +220,8 @@ T=Wave 4+ 触发共鸣时 → 最终提示显示
|
||||
| 18 | `TUTORIAL_STEP_COMPLETED` | `step: int` | TutorialManager | UIManager（显示解锁提示）|
|
||||
| 19 | `SHOP_OPENED` | — | ShopManager | TutorialManager |
|
||||
| 20 | `RESONANCE_TRIGGERED` | `recipe_id: String` | SpellEvaluator | TutorialManager, VFXManager |
|
||||
|
||||
> **⚠️ 实现现状 (2026-07-20 审计)**：上表 EventID 与实际 `event_ids.gd` **不符**——`TUTORIAL_STEP_COMPLETED` 与 `RESONANCE_TRIGGERED` 常量**根本不存在**；ID 18/19/20/21 实为 `ACHIEVEMENT_UNLOCKED`/`BOSS_SPAWNED`/`GAME_STATE_CHANGED`/`SPELL_DROP_PICKUP`，`SHOP_OPENED` 实为 17。详见 [审计报告](../../docs_dev/doc_code_audit_2026-07-20.md)。
|
||||
| 21 | `ACHIEVEMENT_UNLOCKED` | `achievement_id: String` | AchievementManager | Steam 插件层 |
|
||||
|
||||
> **注意**：ID 0 为 `CRASH_DETECTED`（CrashReporter 专用，已定义）。
|
||||
|
||||
Reference in New Issue
Block a user