# PvZ MCP

通过 MCP 让 AI 游玩《植物大战僵尸》：读取游戏状态，自主决定种植位置和等待时间，再通过工具执行操作。整个过程可以不看画面、不操作鼠标。

当前版本 `0.3.6` 支持 Windows x64 上运行的特定 **1.2.0.1073** 构建。

本项目提供工具源码和安装脚本，不包含游戏文件、资源或存档。使用者需要自行准备兼容的游戏，以及支持本地 stdio MCP 的 AI 客户端。

## 功能

- **自动连接**：自行先开游戏，MCP 自动发现并接入；无需在安装时选择游戏路径，保留当前棋盘。
- **读取局势**：以 JSON 获取植物、僵尸、子弹、血量、阳光、卡牌冷却、物品和波次等状态。
- **控制节奏**：暂停游戏、按指定时长推进后再次暂停，或持续运行；支持调整倍速。
- **执行操作**：选择模式与关卡、选卡、按正常规则种植、拾取物品、推进戴夫对话和使用铲子；支持读取与使用传送带卡牌。
- **观战提示**：显示决策计时、推进倒计时，以及 AI 的打算和操作说明。
- **桌面面板**：发现与连接游戏、开始冒险、暂停 / 持续运行 / 定时推进，调整倍速和观战提示，查看彩色文字棋盘并复制局面 JSON。
- **管理进度**：读取存档信息，在主菜单修改冒险进度并备份原档。
- **检查更新**：MCP 启动后在后台查询本仓库 Release，默认每 24 小时检查一次，也可手动检查。

默认自动拾取阳光、银币、金币和钻石，使用游戏原有的音效和收集动画。关卡奖励仍需手动领取或调用 `pvz_collect`。更新后请重新打开游戏，让新的自动拾取逻辑生效。工具本身不包含自动决策策略，如何游玩由连接它的 AI 决定。

## 兼容性

| 游戏构建 | 状态 | 验证范围 |
| --- | --- | --- |
| 1.2.0.1073，下方所列 SHA-256 | 已适配 | 实机验证冒险 1-4、1-5 和 2-1，覆盖对话、铲除教学、传送带、普通选卡、战斗和领奖 |
| 1.0.0.1051，已检查构建 | 不支持 | 当前适配无法直接使用，可安装工具但不能启用游戏控制 |
| 其他同版本构建、汉化或修改版 | 未验证 | 版本号相同也不保证兼容 |
| 其他 Steam / GOTY 构建、重制版及移动版 | 未适配 | 暂不支持 |

**目前只有下列 EXE 哈希可以启用游戏控制。**安装时无需选择游戏。连接时会校验实际进程；不受支持的构建不会加载桥接。未验证不等于一定不兼容，但需要另行验证后才能启用。

```text
e1511201ec2ae9a7e30259f04bc2ec7272badb2574a2e9b405d0e916ae5c082c
```

可在 PowerShell 中检查：

```powershell
Get-FileHash -LiteralPath 'D:\Games\PvZ\PlantsVsZombies.exe' -Algorithm SHA256
```

尚未覆盖所有关卡和模式。冒险 1-5 支持戴夫对话、铲子教学及传送带坚果保龄球；其他特殊关卡仍需逐一验证。回放、金币编辑、全植物解锁和任意存档编辑也尚未实现。

## 快速开始

### 使用 EXE 安装器

1. 从 [Releases](https://github.com/ZhangAo1999/pvz-mcp/releases) 下载并运行 `PvZ-MCP-版本号-Setup.exe`。
2. 选择工具安装目录，默认 `D:\Programs\PvZ-MCP`。
3. 保持默认的“自动发现已打开的游戏”，无需选择游戏路径。需要 MCP 代为启动游戏时，可选填自己的 EXE 路径。
4. 点击“安装 / 更新”。安装器自带 Node.js、Python 和 MCP 依赖，无需另行下载。
5. 将安装目录生成的 `mcp-config.json` 合并到 AI 客户端的 MCP 配置中，重新连接服务。配置格式可能需要按客户端要求转换。
6. 自行打开受支持的原版游戏，让 AI 调用 `pvz_status` / `pvz_list_games`，再用 `pvz_attach` 连接。`pvz_get_state` 也会自动接入并暂停战斗。

没有运行游戏时，MCP 返回 `NOT_RUNNING`。可以自行启动游戏，或调用 `pvz_launch_game(game_path="D:\Games\PvZ\PlantsVsZombies.exe")`。成功连接后会记住启动路径，后续可省略。多个受支持游戏同时运行时，须从 `pvz_list_games` 返回值中选择 PID；不会静默选取其中一个。

安装器不会自动修改 AI 客户端配置，也不会启动或改写所选游戏。

从源码构建的 ZIP 离线包，解压后可使用 `Install.cmd`，或通过命令行安装：

```powershell
.\Install.ps1 -InstallDir 'D:\Programs\PvZ-MCP' -NonInteractive
```

可选：记住游戏启动路径：

```powershell
.\Install.ps1 -InstallDir 'D:\Programs\PvZ-MCP' -GamePath 'D:\Games\PvZ\PlantsVsZombies.exe' -NonInteractive
```

**源码仓库与安装包不同。**从源码运行和构建 EXE 请参阅[开发说明](docs/DEVELOPMENT.md)。

### 启动方式

安装完成后，可点击「打开控制面板」，或双击安装目录的 `PvZ-MCP-Control.exe`。面板自动只读刷新状态与文字棋盘，不会暂停游戏或中断推进。植物使用彩色简称，支持同格多层植物；僵尸按原生横坐标显示，啃咬时变为红色。点击植物格子或僵尸可查看全名、坐标与血量。读取期间若游戏发生更新，会重试；无法取得一致数据时会标明仍是上次数据。面板与 AI 共享控制状态，手动操作会影响当前进程。关闭面板不会关闭游戏或 MCP。

面板可单独使用；让 AI 游玩仍需在 AI 客户端配置 MCP。更新或回退后，面板入口会读取当前启用版本。

棋盘页提供「运行」和「暂停」，游戏布局自动更新。同排僵尸使用稳定的纵向错位以便区分；点击可查看实际坐标。「运行」和定时推进会自动解除游戏失去焦点时的暂停，切回控制台后也能继续运行。手动打开的设置菜单仍会暂停游戏，需关闭后再继续。

可以先双击原版游戏，再启动或连接 MCP；无需退出游戏。默认识别 PlantsVsZombies.exe、popcapgame1.exe 和名称含“植物大战僵尸”的 EXE。自行改名的文件可通过 `pvz_list_games(pid=...)` / `pvz_attach(pid=...)` 指定，或选填启动路径。

工具在接入已有进程或启动新游戏时加载内存桥接，**不改写游戏 EXE 或资源文件**；关闭游戏后桥接自然消失。游戏仍会正常保存进度，管理员改档操作也会写入存档。

同一时间建议只运行一份游戏，并由一个客户端控制。AI 客户端需要具备本机 MCP 执行能力。

## 让 AI 开始游玩

连接成功后，可以向 AI 提出这样的要求：

> 通过 PvZ MCP 按当前存档进度开始冒险，不增加阳光。每轮暂停读取 JSON，自主决定种植和下一次等待时长，保持 1 倍速，并用简短观战说明解释操作。

典型流程：

```text
发现并连接游戏 → 开始或继续关卡 → 读取暂停快照 → 判断并操作 → 推进一段时间 → 再次判断
```

默认每次推进 2 秒游戏时间，也可以由 AI 按局势选择更长的间隔。种植遵守阳光、冷却与地形规则。选关参数 `level` 只在明确指定关卡时使用；省略时按当前存档进度开始。

工具参数、身份校验、异步推进和领奖处理见[调用说明](docs/USAGE.md)。AI 也可直接调用 `pvz_help`；`pvz_status` 和 `pvz_get_state` 的 `guidance` 会说明当前可用操作和下一步。

## MCP 工具列表

当前提供 **27 个工具**。具体操作受当前场景、模式和解锁状态限制。

| 工具 | 用途 |
| --- | --- |
| `pvz_help` | 无需启动游戏即可查询工具用法、参数约定和操作流程 |
| `pvz_continue_dialogue` | 按句推进冒险开场的戴夫对话。卡槽购买邀约可显式拒绝 |
| `pvz_shovel` | 通过原生铲子流程挖掉单层植物，支持 1-5 教学 |
| `pvz_status` | 查询游戏进程、场景和控制状态，选卡界面就绪时返回所需卡数和可选卡牌 |
| `pvz_check_update` | 查询本仓库新版本、安装器下载地址与 SHA-256 |
| `pvz_list_games` | 发现正在运行的游戏，返回版本校验结果、PID 和会话标识 |
| `pvz_attach` | 连接已打开的受支持原版，无需重启，保留当前棋盘 |
| `pvz_launch_game` | 启动受支持的游戏并加载桥接，或复用已连接的进程 |
| `pvz_list_modes` | 查询模式目录和支持信息 |
| `pvz_start_game` | 开始冒险或指定模式，支持显式选关 |
| `pvz_return_to_menu` | 返回主菜单，离开当前关卡 |
| `pvz_get_state` | 暂停并读取一致的 JSON 游戏状态，包含墓碑坐标 |
| `pvz_observe` | 不暂停地读取棋盘，验证读取前后未更新；失败可重试 |
| `pvz_pause` | 暂停模拟，保留控制入口 |
| `pvz_advance` | 推进指定时长或更新次数，然后再次暂停 |
| `pvz_resume` | 持续运行，可指定倍速 |
| `pvz_select_seeds` | 按实际解锁情况选择卡组，支持分批加卡和单独确认开战 |
| `pvz_can_place` | 检查卡槽、费用、冷却和格子合法性 |
| `pvz_place_plant` | 普通关卡扣阳光并触发冷却；传送带关卡消耗卡牌 |
| `pvz_play_turn` | 批量执行一轮操作、发布观战说明、按指定时长推进并返回下一轮局面 |
| `pvz_collect` | 拾取阳光、钱币、植物卡片、铲子、来信、奖励钱袋和钻石袋 |
| `pvz_read_letter` | 返回当前来信的中文文字、摘要及转录来源，无需识图 |
| `pvz_set_presentation` | 设置倍速、观战提示、说明保留时间和默认推进时长 |
| `pvz_set_commentary` | 显示 AI 的简短打算和本次操作说明 |
| `pvz_get_save_info` | 只读查询当前用户存档、进度和校验信息 |
| `pvz_admin_set_progress` | 管理员功能：备份后修改冒险进度并同步主菜单关卡牌 |
| `pvz_admin_set_sun` | 管理员功能：直接设置局内阳光 |

普通种植与选卡当前覆盖冒险和植物僵尸的相应原生规则，模仿者暂不支持。模式出现在目录中，不代表已解锁或已完成实机验证。

AI 可直接用回合工具返回的棋盘继续决策。棋盘的 `graves` 列出仍在场的墓碑，控制台会同步显示。墓碑吞噬者（类型 11）只能种在墓碑上，普通植物需避开。传送带每回合可种一张卡，使用当前快照的 `cards_revision`。

管理员接口会改变正常游戏状态，应按使用者明确要求调用。返回主菜单会离开当前关卡，未结算的局内进度可能丢失。

## 升级与回退

关闭游戏并断开 MCP，运行新版 EXE 安装器或 ZIP 离线包，选择原安装目录即可升级。用户配置和备份会保留，重新连接 MCP 后使用新版。

需要回退时，在安装目录运行：

```powershell
.\Manage.ps1 -Action Rollback
```

回退只切换工具版本，不恢复游戏存档。

### 自动检查更新

连接 MCP 后，工具在后台从 [本仓库 Releases](https://github.com/ZhangAo1999/pvz-mcp/releases) 检查新版，默认每 24 小时一次。检查结果会加入 `pvz_status` 的 `update` 字段；发现新版时向客户端输出提示。客户端是否直接显示提示取决于其日志界面，AI 也可读取状态后告知你。

预览版默认同时检查正式版和预览版，正式版默认仅检查正式版。工具按版本号比较，忽略草稿和缺少 EXE 安装器的 Release。网络失败或 GitHub 限流会稍后重试，不阻塞 MCP 连接或游戏操作。

可以让 AI 调用 `pvz_check_update` 立即检查，也可在安装目录运行：

```powershell
.\Manage.ps1 -Action CheckUpdate
```

检查更新只获取版本元数据，不会自动下载、安装或重启。升级时下载提示中的 EXE，再选择原安装目录。`0.3.1-preview.1` 及更早版本需要先手动升级一次，才具备此功能。

自动检查开关、更新频道和代理配置见[调用说明](docs/USAGE.md#更新检查)。

## 开发与贡献

欢迎 fork 添加游戏版本适配、补充测试或扩展工具。源码结构、运行环境和测试方法见[开发说明](docs/DEVELOPMENT.md)。

新增适配需要核实函数地址、调用方式和对象结构，并补上验证结果；请保留版本校验，更新兼容性表。请勿提交游戏文件、用户存档或运行日志。

## 许可

Copyright (c) 2026 **ZhangAo1999**。原项目：<https://github.com/ZhangAo1999/pvz-mcp>。

从 `0.3.2-preview.1` 起，项目工具代码使用 [GNU GPL v3，仅第 3 版（GPL-3.0-only）](LICENSE)。二次分发时需保留适用的作者版权和许可证声明，标明修改，并按 GPL 要求提供对应源码；私人修改自用无需公开。作者和来源信息见 [NOTICE](NOTICE)。

已发布的 `0.3.1-preview.1` 保留其 MIT 许可。第三方依赖遵循各自许可证，见[第三方声明](THIRD-PARTY-NOTICES.txt)。

本项目与 EA / PopCap 无隶属或授权关系。使用工具仍需遵守适用的游戏许可协议及法律。

### 奖励与信件

pvz_collect 支持普通阳光、金币、最终种子包、铲子，以及僵尸来信（类型 15）、奖励钱袋（18）和钻石袋（20）。领取后使用 pvz_advance 播放原生过关动画。

pvz_read_letter 可以读取地上或奖励页当前信件的中文文字和摘要，无需模型识图。文字来自本版本游戏图片的人工转录，保留原文错别字；未确认的文字会明确标记。状态也会返回 rewards / award.letter。

新启动的游戏在 AI 暂停时保留菜单按钮交互，战斗、阳光生产及冷却继续冻结。更新前已经运行的旧桥接可继续读取状态及领取奖励；菜单修复在新版桥接加载后生效；升级前的旧桥接若缺少该功能，需要重启一次游戏，再通过 MCP 接入。