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:
2026-07-20 14:35:55 +08:00
co-authored by Claude Opus 4.8
parent 7bcc0026e0
commit ad2f4c0bc6
20 changed files with 446 additions and 67 deletions
+15 -1
View File
@@ -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** 触发里程碑事件:
| 里程碑 | 即时奖励 | 解锁内容 |