SnyderConsulting/DelveRL

来源：https://github.com/SnyderConsulting/DelveRL

DelveRL

一款人类可玩的回合制Roguelike游戏，作为本地游戏代理的开源基准测试平台。

DelveRL在重置后具有确定性，采用程序化生成、部分可观测，且渲染器无关。每一层地图要求玩家获取一把钥匙并返回标记的出口。长期挑战在于平衡探索、战术风险、生命值、金币、装备和时间压力，同时无法获取隐藏的地图信息。

DelveRL 地牢

该代码库包含：

• 完整的 Godot 4.7 游戏和人类接口；
• 结构化的单环境API和批处理16动作训练API；
• 仅观测符号基线和特权天花板控制器；
• 支持CUDA的递归PPO训练器；
• 发布的混合检查点和原始基准审计；
• 针对生成、规则、观测、战术、装备和UI状态的确定性测试。

已发布基线

包含的代理结合了基于合法观测的战术规划器和通过CNN/GRU训练的决策策略，用于进行中转站经济决策。它从不读取生成种子、完整拓扑结构或隐藏目标坐标。

三次扩展运行在5000回合上限时仍然存活，因此这些深度属于右删失数据而非死亡层数。训练在最终战术规划器优化前达到了第26层的前沿水平。原始结果、方法和报告注意事项请参见基准测试。

发布模型为 models/floor_agent.pt（SHA-256 E0BF4095864542583D8AE0C4B25851B199A881AB111A88641E46F27604903883）。这是一个起点，而非环境已被解决的声明。

游戏玩法

环境要求

• Godot 4.7 或更高版本 (https://godotengine.org/download/)
• Windows、Linux 或 macOS

无需外部游戏资产或Godot插件。

运行方法

克隆仓库：

git clone https://github.com/SnyderConsulting/DelveRL.git
cd DelveRL

在Windows系统下，双击 play_windows.cmd 或运行：

godot --path .

在Linux或macOS系统下：

./play_unix.sh
# 或：godot --path .

也可将 project.godot 导入Godot项目管理器，按F6/F5运行。若需制作独立版本，请安装Godot导出模板并通过项目 → 导出操作；项目使用跨平台GL兼容渲染器。

操作说明

• WASD / 方向键或高亮相邻地块：移动、攻击、开门、激活封印或使用破拆撬锁工具
• 空格键或点击玩家：等待一回合
• Shift + 移动键或高亮两格外的地块：使用装备的迅捷之靴
• Q：使用药水
• Enter / Escape：离开中转站
• R：失败后开始新一轮游戏

目标栏显示三种契约之一：寻找钥匙、追击标记携带者或激活两个封印。获得钥匙后需返回地图上记忆的出口位置。

DelveRL 中转站

开始代理开发

建议使用Python 3.10或更高版本。在虚拟环境中安装训练器依赖：

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
python -m pip install -r requirements.txt

启动无渲染器桥接器：

godot --headless --path . --script res://scripts/agent_bridge.gd -- --port 28767

在第二个终端中：

python tools/bridge_client.py --port 28767 --command ping
python tools/bridge_client.py --port 28767 --playtest --seed 731 --max-turns 5000

训练新的递归PPO候选模型：

python -u tools/train_ppo.py --port 28767 --envs 32 --steps 200000 \
  --demo-steps 50000 --demo-epochs 3 --eval-episodes 32 \
  --checkpoint models/my_candidate.pt \
  --deployed-checkpoint models/my_agent.pt \
  --metrics models/my_metrics.json

训练器在检测到CUDA时自动使用GPU，支持 --cpu 参数进行快速测试。发布版本使用RTX 4090显卡运行，但环境与代理特意设计为适合本地实验的规模。

评估包含的检查点：

python -u tools/train_ppo.py --port 28767 --eval-only \
  --checkpoint models/floor_agent.pt --hybrid \
  --eval-seed 8500000 --eval-episodes 32 --max-episode-turns 1500

构建提交版本或修改协议前请阅读：

• 桥接与观测API
• 训练架构与复现
• 基准协议与发布结果
• 游戏设计与扩展规则
• 贡献指南

仓库结构

scenes/                 Godot场景入口点
scripts/rogue_sim.gd    权威确定性规则与生成器
scripts/main.gd         UI构建与人类输入
scripts/dungeon_board.gd 地图渲染与交互
scripts/agent_env.gd    无渲染器环境与离散适配器
scripts/agent_bridge.gd NDJSON TCP服务器与批处理模拟器
tools/bridge_client.py  参考客户端与观测基线
tools/train_ppo.py      递归PPO训练器与评估器
models/                 发布的检查点与原始审计
tests/test_sim.gd       确定性集成测试套件

验证检出

godot --headless --path . --script res://tests/test_sim.gd
godot --headless --path . --script res://scripts/dump_state.gd -- --seed 731
python -m py_compile tools/bridge_client.py tools/train_ppo.py

预期测试结果为：PASS: 12 DelveRL v1 generation, composition, contracts, tactics, loadout, observation, and UI tests

许可证

DelveRL采用 MIT许可证。欢迎贡献新基线、替代训练器、能力探测模块及兼容生成器。