joywayerandClaude Opus 4.8
ad2f4c0bc6
- 将开发过程/归档文档迁至 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>
136 lines
7.3 KiB
Markdown
136 lines
7.3 KiB
Markdown
# Spellforge（万法熔炉）
|
||
|
||
> **"Noita 遇上 Brotato"** —— 快节奏割草 × 深度法术编程的 Roguelite 弹幕射击游戏
|
||
>
|
||
> Godot 4.6 (Mono) · GDScript 热路径 + C# · SoA / ECS-Lite 架构
|
||
|
||
被困异次元的"土豆工匠"，捡到的不是武器，而是**逻辑碎片与弹头**。你要像程序员一样**"编写"你的子弹**——用核心（法杖）、修正器、触发器和逻辑门，组装出毁天灭地的魔法武器，抵御无穷波次的怪物潮。
|
||
|
||
> 📛 **命名说明**：`Spellforge / 万法熔炉` 为当前候选名（`project.godot` 中工程名仍暂为 `Rogue`）。定稿后同步更新此处与 `application/config/name`。
|
||
|
||
---
|
||
|
||
## ✨ 核心玩法：法术管道 (The Spell Pipeline)
|
||
|
||
武器由一个 **核心 (Core)** 和若干 **法术节点 (Spell Node)** 组成，四类节点自由排列组合，实现近乎图灵完备的武器逻辑：
|
||
|
||
| 类型 | 作用 | 示例 |
|
||
|:---|:---|:---|
|
||
| **ACTION** 动作 | 实际产生的飞行物 | 魔法弹、黑洞、治疗雾、召唤炮台 |
|
||
| **MODIFIER** 修正 | 改变下一个动作 | 伤害+、弹道折射、多重施法、正弦轨迹 |
|
||
| **TRIGGER** 触发 | 逻辑传递（子母弹） | 击中触发、定时触发 |
|
||
| **LOGIC** 逻辑门 | 自动化灵魂 | `IF_HP_LOW`、`IF_ENEMY_CLOSE`、`LOOP` |
|
||
|
||
深度构建维度：
|
||
- **拓扑构建** —— Core 不只是列表，还有 `LINEAR` / `MATRIX`（邻接加成）/ `CIRCUIT`（电路分叉）三种插槽拓扑
|
||
- **逻辑寄存器** —— 史诗核心提供跨帧持久寄存器，可搭出"蓄力计数器""击杀连击"
|
||
- **炼金共鸣** —— 特定元素法术相邻时自动质变合成（如 `水属性波` + `闪电链` → `等离子风暴`）
|
||
|
||
**性能怪兽**：得益于 SoA + Spatial Grid，支持同屏 **1000+ 敌人**、**2000+ 独立弹幕**，实测 500 敌人 + 1500 子弹下模拟+渲染仅 ~0.6ms（16.67ms 预算的 3.6%）。
|
||
|
||
---
|
||
|
||
## 🚀 快速上手
|
||
|
||
**前置**：[Godot 4.6 **.NET/Mono 版**](https://godotengine.org/)（工程使用 C#，需 .NET SDK）。
|
||
|
||
```bash
|
||
# 1. 用 Godot 4.6 Mono 打开工程
|
||
# 直接打开项目根目录的 project.godot
|
||
|
||
# 2. 首次打开会自动构建 C# 程序集（Rogue.sln）
|
||
|
||
# 3. 运行工程（F5）
|
||
# 主场景：res://scenes/ui/splash.tscn
|
||
# 流程：Splash → 主菜单 → 战斗 → 商店 → 结算 → 排行榜
|
||
```
|
||
|
||
> 详细步骤见 [`docs/handbook/01_quickstart.md`](docs/handbook/01_quickstart.md)。
|
||
|
||
---
|
||
|
||
## 🧰 技术栈与架构
|
||
|
||
- **引擎**：Godot 4.6 (Mono)，渲染 D3D12，物理 Jolt
|
||
- **架构**：**ECS-Lite** —— ~35 个 Autoload 单例分层协作，EventBus + 整数 `EventID` 常量解耦
|
||
- **数据布局**：SoA（Structure of Arrays），`BulletManager` STRIDE=12、`EnemyManager` STRIDE=8，配合对象池零 GC
|
||
- **渲染**：`MultiMeshInstance2D` 单批次绘制全部子弹/敌人，程序化着色器发光（`shaders/`）
|
||
- **法术虚拟机**：两阶段架构 —— `compile_wand()`（装备/换牌时编译为 `CompiledDeck`）+ `execute_compiled()`（每次施法执行线性化节点）
|
||
- **热路径**：当前跑 GDScript；`csharp/` 下 C# 管理器（`BulletManagerCs` / `EnemyManagerCs` / `SpatialGridCs`）为骨架，供后续迁移
|
||
|
||
---
|
||
|
||
## 📂 项目结构
|
||
|
||
```
|
||
daihaoRogue/
|
||
├── project.godot 工程配置（Autoload 注册、编辑器插件）
|
||
├── scenes/
|
||
│ ├── ui/ splash / main_menu（启动与菜单）
|
||
│ └── main/ combat_s2（主战斗场景，唯一可玩入口）
|
||
├── scripts/
|
||
│ ├── autoloads/ 全局单例（EventID/EnemyManager/WaveManager…）
|
||
│ ├── core/ 基础数据结构
|
||
│ └── domain/
|
||
│ ├── spell_system/ 法术虚拟机（spell_evaluator.gd 等）
|
||
│ └── combat/ 游戏循环状态机
|
||
├── csharp/ C# 热路径管理器（骨架，含 .cs）
|
||
├── data/ ⭐ 纯数据驱动内容（JSON）
|
||
│ ├── spells.json cores.json enemies.json waves.json
|
||
│ └── balance.json resonance.json status_effects.json
|
||
├── shaders/ 子弹/敌人/地面网格程序化着色器
|
||
├── translations/ zh_CN / zh_TW / en / ja（.po）
|
||
├── assets/ 精灵 / UI 主题（目前几何占位）
|
||
├── addons/ 编辑器插件（见下）
|
||
├── docs/ 产品文档：设计 / 技术 / 机制 / 手册
|
||
└── docs_dev/ 开发过程 / 归档文档：开发计划 · 认证清单 · 早期草案
|
||
```
|
||
|
||
---
|
||
|
||
## 🎮 编辑器工具（零代码配置内容）
|
||
|
||
工程为策划/美术提供了 **@tool 编辑器插件**，所有游戏内容纯数据驱动（`data/*.json`），改内容无需碰代码：
|
||
|
||
| 插件 | 位置 | 功能 |
|
||
|:---|:---|:---|
|
||
| **🎮 游戏设计器** | `addons/game_designer/` · 底部面板 | 一站式：法术 / 敌人 / 波次 / Core / 平衡 / 共鸣 / 状态 共 7 个表单页 |
|
||
| **法术编辑器** | `addons/spell_editor/` | 单独的法术 meta 字段编辑（已并入设计器） |
|
||
| **Godot MCP** | `addons/godot_mcp/` | AI 辅助开发（截图 / 输入 / 场景检查服务） |
|
||
|
||
> 修改后需 **F5 重启**生效（内容在 `_ready()` 时加载）。用法见 [`docs/handbook/07_game_designer.md`](docs/handbook/07_game_designer.md)。
|
||
|
||
---
|
||
|
||
## 📖 文档导航
|
||
|
||
完整文档索引见 [`docs/README.md`](docs/README.md)；开发/策划手册见 [`docs/handbook/`](docs/handbook/README.md)。
|
||
|
||
| 分类 | 关键文档 |
|
||
|:---|:---|
|
||
| **游戏设计** | [`game_design.md`](docs/design/game_design.md) · [`numerical_design.md`](docs/design/numerical_design.md) · [`core_wand_design.md`](docs/design/core_wand_design.md) |
|
||
| **技术架构** | [`architecture_design.md`](docs/technical/architecture_design.md) · [`implementation_plan.md`](docs/technical/implementation_plan.md) |
|
||
| **机制细节** | [`docs/mechanics/`](docs/mechanics/) —— 溯源 / 连锁 / 状态 / 召唤 / 环境场 |
|
||
| **开发计划** | [`development_plan.md`](docs_dev/development_plan.md)（S0–S6 垂直切片） · [`certification_checklist.md`](docs_dev/certification_checklist.md) —— 位于 [`docs_dev/`](docs_dev/)（开发过程/归档文档） |
|
||
|
||
> `docs/README.md` 末尾附有 **关键规范速查表（P6-N* / ADR-*）**，是跨切片实现约束的权威来源。
|
||
|
||
---
|
||
|
||
## 🏗️ 开发状态
|
||
|
||
采用"骨架垂直切片" S0–S6 推进。当前主体流程已可完整游玩：
|
||
|
||
- ✅ **完整游戏外壳**：Splash → 菜单 → 战斗 → 商店 → 结算 → Endless 排行榜，含存档（A/B 局内槽）、暂停、首启难度选择（FTUE）
|
||
- ✅ **核心战斗**：法术虚拟机（LINEAR/MATRIX/CIRCUIT 三拓扑 + LOGIC + 共鸣 + 召唤/地面场）、20 波内容 + W8/W20 多阶段 Boss、精英寻路
|
||
- ✅ **系统**：难度/音量/语言设置、4 语言本地化、程序化音效、MultiMesh 渲染 + 发光着色器、纯数据驱动 + 可视化编辑器
|
||
- 🚧 **待完善**：C# 热路径迁移（当前 GDScript）、正式美术/音频资源（现为几何占位 + 蜂鸣）、法术/Core/状态名的多语言化、Steam/Switch 平台认证项
|
||
|
||
> 详细进度与计划/代码差异见 `docs_dev/development_plan.md`。
|
||
|
||
---
|
||
|
||
## 📄 许可
|
||
|
||
尚未指定许可证（暂为私有工程）。如需开源发布，请在根目录添加 `LICENSE` 并在此说明。
|