初次提交

2026-07-20 10:56:52 +08:00
commit 7bcc0026e0
462 changed files with 50191 additions and 0 deletions
@@ -0,0 +1,121 @@
+# 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 重新运行）使改动生效。