# 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` 并在此说明。