# 01 快速上手 (Quickstart)

## 1. 环境要求

| 工具 | 版本 | 下载 |
|:---|:---|:---|
| Godot Engine | **4.6 Mono**（带 .NET 支持） | godotengine.org |
| .NET SDK | 8.0+ | dotnet.microsoft.com |
| Git | 任意 | git-scm.com |

> **重要**：必须下载 **Mono/C# 版本** 的 Godot（文件名含 `mono`），否则 C# 文件无法编译。

---

## 2. 首次运行

```bash
# 1. 克隆项目
git clone <repo-url>

# 2. 用 Godot 4.6 Mono 打开 project.godot
# 菜单: Project → Open / Import

# 3. 等待导入完成（首次约 10-30 秒）

# 4. 直接按 F5 运行，或菜单: Debug → Run Project
```

运行后你会看到：战斗场景直接开始，玩家（青色方块）自动发弹，敌人（红色方块）向玩家靠近。

---

## 3. 主场景说明

唯一可玩主场景：`scenes/main/combat_s2.tscn`

```
project.godot
└── run/main_scene = "res://scenes/main/combat_s2.tscn"
```

### 游戏循环

```
战斗 (BATTLE)
  ↓ 全部敌人/Boss 死亡
波次结算 → 商店 (SHOP)
  ↓ 关闭商店
战斗 (下一波)
  ↓ 玩家死亡
结算屏 (GAME_OVER) → 再来一局
```

### 商店内操作

| 按钮 | 功能 |
|:---|:---|
| 法术卡 | 购买并装入当前法杖 |
| 法杖 ⟳ | 切换 Core（法杖类型） |
| 🎒 背包 | 打开插槽编辑器，自由排布法术 |
| 刷新 | 重新随机商店（花费金币） |
| ⚙ 设置 | 难度 / 语言 / 音量 / 清除数据 |
| 出发下一波 | 进入下一波战斗 |

---

## 4. 调试工具

### 编辑器内测试

在任何场景运行时，可以通过 MCP 脚本执行器（godot-mcp 插件）向游戏注入 GDScript：

```gdscript
# 示例：快速生成一个 Boss 进行测试
EnemyManager.reset()
WaveManager.start_wave(20)   # 直接启动 W20 Boss 战
```

### HUD 调试信息

运行时左上角 HUD 显示：
- 当前波次 / HP / 金币 / XP / 击杀数
- DPS / 蓄力百分比
- `[Core名] [法术id列表]`（当前装备）
- 状态实例数 / VFX 数

### 快速切波次

```gdscript
# 在游戏内执行（须在商店状态下）
# 方法：打开商店后跳到指定波次再出发
WaveManager.current_wave = 14            # 设置当前波次基准
# 然后在商店中点「出发下一波」，即进入 W15 精英战
# 或直接重置重开：get_tree().current_scene._cm.start_game()
```

---

## 5. 项目配置文件

| 文件 | 说明 |
|:---|:---|
| `project.godot` | 引擎配置、Autoload 列表、主场景 |
| `user://save_data.json` | 设置（难度/语言/音量），运行时生成 |
| `user://run_a.json` `run_b.json` | 局内 A/B 双槽存档 |
| `user://endless_records.json` | 本地排行榜（HMAC 签名） |

> `user://` 路径在 Windows 上位于 `%APPDATA%\Godot\app_userdata\Rogue\`

---

## 6. 常见问题

**Q: F5 运行后没有画面（黑屏）**  
A: 确认下载的是 **Mono 版**；等待 .NET 首次编译完成（约 30s）。

**Q: 敌人/子弹消失了但没有波次结算**  
A: 可能生命时间到期。重启当前波次：`WaveManager.start_wave(WaveManager.current_wave)`

**Q: 更改了 `wand_preset.gd` 的法术数值，但游戏里没有变化**  
A: `SpellRegistry` 在 `_ready()` 时缓存法术对象；需要重启游戏（F5 重新运行）使改动生效。