doom-mcp

通过 MCP 玩 DOOM

DOOM 能运行吗？当然可以——你的 AI 编码助手可以运行 DOOM。

在 Claude Code、Cursor 或任何兼容 MCP 的客户端中玩 DOOM。AI 可以看到游戏、与恶魔战斗、探索关卡并汇报情况；你也可以逐步指挥它行动。

> Let's play DOOM!

  Starting E1M1 on medium difficulty...

  HP:100 Armor:0 | Pistol (key:2) | Ammo: 50b 0s 0r 0c | Kills:0 | E1M1
  No enemies in sight. Exploring the corridor ahead.

> Go forward and find some enemies

  Sprinting down the hallway... I can see an opening ahead.

  HP:100 Armor:0 | Pistol (key:2) | Ammo: 50b 0s 0r 0c | Kills:0 | E1M1
  ENEMIES IN SIGHT (aim for angle~0 then fire): Imp (HP:60) to your left (turn_left ~9) nearby

  There's an Imp to the left! Turning to face it...

> Shoot it!

  Aimed and firing!

  HP:100 Armor:0 | Pistol (key:2) | Ammo: 47b 0s 0r 0c | Kills:0 | E1M1
  ENEMIES IN SIGHT (aim for angle~0 then fire): Imp (HP:15) AHEAD close

  Hit! The Imp is wounded (HP:15). One more burst should finish it.

  HP:95 Armor:0 | Pistol (key:2) | Ammo: 44b 0s 0r 0c | Kills:1 | E1M1
  ITEMS: Stimpack (+10 HP) slightly to your right (turn_right ~4) point-blank (~3 ticks fwd+run to reach)
  1 kill! Want to see a screenshot?

阅读博客文章，了解完整故事。

---

目录

• 工作原理
• 快速开始
• 游玩模式
• 工具参考
• 配置
• 常见问题
• 架构
• 开发
• 致谢
• 许可证

---

工作原理

一个 Rust MCP 服务通过 FFI 直接嵌入真正的 DOOM 引擎（doomgeneric）。无需模拟，也无需子进程。每次工具调用都会让游戏推进若干个 tick，并返回：

1. 游戏状态 - HP、护甲、弹药、击杀数、位置、当前武器
2. 敌人情报 - 可见敌人的易读方向、距离和 HP
3. 附近物品 - 拾取范围内的生命值、弹药、护甲和武器
4. 门和开关 - 检测范围内可交互的线段
5. 画面图像 - 供 AI 视觉识别的小型 PNG 缩略图

AI 会利用这些信息来导航、战斗和探索。你可以指挥它，也可以让它自主游玩。

graph LR
    A[MCP Client] -->|doom_start| B[doom-mcp binary]
    A -->|doom_action| B
    A -->|doom_screenshot| B
    B -->|FFI| C[doomgeneric C engine]
    C -->|frame buffer| B
    B -->|game state + PNG| A

---

快速开始

1. 在 MCP 客户端中注册

Claude Code：

claude mcp add doom --scope user -- npx -y doom-mcp

Cursor、Windsurf 或任何 MCP 客户端 - 添加到 .mcp.json：

{
  "mcpServers": {
    "doom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doom-mcp"]
    }
  }
}

2. 开始游玩

开启一个新会话并说：

“我们来玩 DOOM 吧”

AI 会询问你想要哪种模式，在 E1M1 开始游戏并开始游玩。

---

游玩模式

模式	工作方式	适合场景
你来指挥	你发出指令（“向前走”“打开那扇门”“射击小恶魔”）。AI 每次执行一个动作，并描述发生了什么。	沉浸式引导游玩
AI 自主游玩	AI 自行决定所有行动，包括移动、战斗和探索。你可以观看，并在需要时介入。	观看 AI 游玩

---

工具参考

doom_start

开始或重新开始 DOOM。可随时安全调用——如果游戏已经在运行，它会干净地重新开始，无需新建会话。

参数	类型	默认值	描述
skill	int (1-5)	3	难度：1=婴儿级，2=简单，3=中等，4=困难，5=噩梦
episode	int (1-4)	1	章节编号
map	int (1-9)	1	地图编号

doom_action

推进游戏。所有列出的动作都会在 tick 持续时间内同时执行。

参数	类型	必填	描述
actions	string	yes	以逗号分隔：forward、backward、turn_left、turn_right、strafe_left、strafe_right、fire、use、run、1-7
ticks	int (1-105)	no	要推进的游戏 tick 数。默认值为 7。速度为每秒 35 tick：7 约为 0.2 秒，35 约为 1 秒

游戏说明：

• fire 会在整个持续时间内扣住扳机。手枪大约每 10 个 tick 自动射击一次。
• 转向和射击应分开操作（边转向边射击会浪费弹药）。
• use 用于开门和启动开关。
• 武器按键：1=拳头，2=手枪，3=霰弹枪，4=链式机枪，5=火箭发射器，6=等离子枪，7=BFG。

doom_screenshot

将 320x200 的全分辨率截图保存到系统临时目录，并在默认图像查看器中打开。不会推进游戏（除了为等待画面稳定而短暂停顿）。

---

配置

环境变量	说明
DOOM_WAD_PATH	自定义 IWAD 文件的路径（例如你自己的 DOOM.WAD 或 DOOM2.WAD）
DOOM_MCP_DEBUG	设置为 1，即可在系统临时目录中的 doom-mcp.log 启用调试日志

捆绑的 Freedoom WAD 开箱即用，但原版 DOOM 共享软件版 WAD 的关卡和精灵图更好。使用方法：

1. 从 doomworld.com/classicdoom/info/shareware.php 下载 DOOM1.WAD（合法且免费）
2. 在 MCP 配置中设置 DOOM_WAD_PATH：

{
  "mcpServers": {
    "doom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doom-mcp"],
      "env": {
        "DOOM_WAD_PATH": "/path/to/DOOM1.WAD"
      }
    }
  }
}

如果你拥有 DOOM 或 DOOM 2，也可以用同样的方法使用对应的 WAD。使用任何自定义 WAD：

{
  "mcpServers": {
    "doom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doom-mcp"],
      "env": {
        "DOOM_WAD_PATH": "/path/to/DOOM.WAD"
      }
    }
  }
}

---

常见问题

这能在 Windows 上运行吗？ 可以。npm 包包含 Windows x64 二进制文件。按照 macOS/Linux 上的相同方式注册即可。

我可以使用自己的 DOOM WAD（DOOM.WAD、DOOM2.WAD）吗？ 可以。在 MCP 配置中设置 DOOM_WAD_PATH。共享软件版 DOOM1.WAD 可从 doomworld.com 免费下载，其关卡比捆绑的 Freedoom 好得多。详情请参阅配置部分。

这会消耗多少 API 令牌？ 每次 doom_action 调用会返回约 1-2KB 的文本（游戏状态 + 敌人信息）以及约 6KB 的 PNG 缩略图。每次操作约消耗 1,500-2,500 个令牌。典型的游戏过程包含 50 次操作，约消耗 75,000-125,000 个令牌。

AI 真的能玩好 DOOM 吗？ 它可以探索关卡、寻找敌人、瞄准和战斗。在中等难度下，它在 E1M1 每局能击杀约 5-10 个敌人。它难以应对部分被掩体遮挡的敌人，也难以通过复杂的连续门区。你对它进行引导后，它的表现会更好。

我可以玩指定关卡吗？ 可以。向 doom_start 传入 episode 和 map 参数。例如，第 1 集第 3 张地图应设置为 episode:1, map:3。

我死亡后会怎样？ 引擎会报告 HP:0，并提供死亡画面的截图。目前无法在同一会话中重启——开始新对话即可重新游玩。

支持多人游戏吗？ 暂不支持。DOOM 的多人游戏协议理论上可以支持多 Agent 游戏，但目前尚未实现。

AI 会作弊吗？它能隔墙看见东西吗？ 不会。敌人检测使用 DOOM 原生的视线检查（P_CheckSight）。AI 只能看到屏幕上本来就能看到的敌人。物品会根据距离检测，但 AI 仍必须走到物品上才能拾取。

---

架构

src/main.rs         MCP JSON-RPC server over stdio
src/doom.rs         Engine FFI wrapper: init, tick, frame capture, state extraction
src/renderer.rs     PNG rendering (216-color palette thumbnails for MCP, full RGB for screenshots)
src/paths.rs        WAD file discovery across platforms
src/log.rs          Debug logging to file
build.rs            Compiles doomgeneric C sources via cc crate (whitelist approach)
csrc/platform.c     DG_ callbacks, virtual time, key injection, enemy/item/door detection

该二进制文件在编译时链接 doomgeneric C 引擎。运行时，它是单个进程，不会启动子进程。帧从共享屏幕缓冲区读取，按键输入则通过 FFI 注入。

虚拟时间 - 引擎时钟与实际时间解耦。每次 doomgeneric_Tick() 恰好推进一个游戏刻度（1/35 秒），不受实际经过时间影响。这使游戏过程具有确定性，并可避免跳过刻度。

敌人和物品检测 - 服务会遍历引擎的内部对象列表（thinker_t 链），以查找附近的敌人和可拾取物品。视线检查使用 Doom 原生的 P_CheckSight()。为避免“透视墙壁”作弊，只会报告可见的敌人。

---

开发

需要：Rust 工具链、GCC、Make、Git、curl、unzip。

git clone https://github.com/gunnargrosch/doom-mcp.git
cd doom-mcp
bash scripts/setup.sh      # clones engines, downloads Freedoom WAD
cargo build --release       # compiles everything into a single binary
cargo test                  # runs unit + integration tests

注册本地构建以进行测试：

claude mcp add doom --scope user -- ./target/release/doom-mcp

启用调试日志：

claude mcp add doom --scope user -e DOOM_MCP_DEBUG=1 -- ./target/release/doom-mcp
tail -f /tmp/doom-mcp.log   # Linux/macOS (Windows: %TEMP%\doom-mcp.log)

npm 包

在本地构建 npm 包：

bash scripts/build-npm.sh   # copies binary + WAD into npm/
cd npm && npm pack           # creates doom-mcp-0.1.2.tgz

发布（需要 npm 账户，并为 CI 配置 NPM_TOKEN）：

cd npm && npm publish

---

致谢

• doomgeneric，作者 ozkl - 可移植的 DOOM 引擎
• Freedoom - 开源 IWAD 文件
• id Software - 原版 DOOM（GPL-2.0）

---

更新日志

详细的变更列表请参阅 CHANGELOG.md。

许可证

本仓库中的 MCP 服务代码采用 MIT 许可证。

doomgeneric 采用 GPL-2.0 许可证，并在构建时克隆（而非随仓库分发）。Freedoom WAD 采用 BSD 风格许可证。