Skip to main content
Glama
Infection Free Zone MCP

Infection Free Zone MCP

by tianq021

无感染区 MCP · v0.2.2

🌐 多语言文档 / Translations

语言

文档

简体中文(当前)

README.md

English

docs/i18n/README.en.md

日本語

docs/i18n/README.ja.md

Русский

docs/i18n/README.ru.md

工具描述同样支持多语言:node server.mjs --lang zh-CN|en|ja|ru(或 IFZ_MCP_LANG),详见 §2 多语言。


《Infection Free Zone》的人机协作 MCP 服务:BepInEx 插件在 Unity 主线程读写游戏,Node 侧用标准 MCP stdio 暴露 92 个工具,供 DSH / Codex 等 AI 客户端实时读取局势、下达订单,并与玩家 1 倍速同步协作。

适用 Steam build 26104777、Windows x64、Unity Mono。最后更新:2026-11-13。

架构总览


Related MCP server: OniMods MCP Server

目录


1. 这是什么

层

组成

说明

游戏层

《无感染区》Steam build 26104777

存档位于 %LOCALAPPDATA%Low\JutsuGames\Infection Free Zone\Saves

插件层

plugin/IfzMcp.csproj → IfzMcp.dll(v0.2.2)

BepInEx 5 插件,Harmony 捕获游戏控制器

桥接层

Windows 命名管道 \\.\pipe\infection-free-zone-mcp-steam-v1

同用户 ACL,单次调用 16–20 ms,整轮 7 类读取约 115 ms

服务层

server.mjs

MCP stdio 服务,默认 92 个工具,DSH 平民协作配置 65 个,纯只读 59 个

客户端层

DSH / Codex / client.mjs / 游戏内浮窗 / 只读监视器

AI 通过 MCP 对话;玩家在游戏里用浮窗插话/打断

核心设计

  • 只读优先:绝大多数分析用复合工具一次聚合(observe、get_daily_report、get_mission_plan…),减少往返与 token。

  • 写入受控:常规游戏订单写入要求「写租约 + 显式暂停 + 请求 UUID」,未知结果可用同一 request_id 安全重试。

  • 作弊兜底:11 个 cheat_* 工具只在紧急情况由 AI 判断使用,默认走正常玩法。

  • 离线可用:天气、进度解锁、存档信息直接从 data.json 读取,不需要游戏在运行。

工具分布


运行截图

聚落地图显示小队状态、任务目标、资源图标和地形,左上角显示插件的游戏内 HUD。

聚落地图实况

2. 快速开始

# 0) 依赖(首次)
npm ci

# 1) 游戏已从 Steam 启动并进入聚落后,确认桥接
node client.mjs --steam status        # 期望 version=0.2.2, ready=true

# 2) 一次看全局势(推荐入口)
node client.mjs --steam observe '{}'

# 3) 查任务与行动计划
node client.mjs --steam get_missions '{}'
node client.mjs --steam get_mission_plan '{}'

# 4) 查敌情 / 资源图标 / 远征 / 车辆
node client.mjs --steam get_enemy_report '{}'
node client.mjs --steam find_buildings_by_poi '{"poi":["Gun","Fuel"]}'
node client.mjs --steam get_vehicle_map '{}'
node client.mjs --steam get_expedition_summary '{}'   # 先在游戏里打开世界地图

# 5) 工具清单自检(不需要游戏)
npm run tools:list

client.mjs 支持两种参数形式:直接 JSON 或 @文件路径(UTF-8 JSON 文件,避免 PowerShell 5.1 引号/中文转义问题)。 连接隔离测试副本时去掉 --steam。

多语言(MCP 工具描述)

  • node server.mjs --lang zh-CN|en|ja|ru,或设置环境变量 IFZ_MCP_LANG,可切换 MCP 工具描述语言(默认 en)。

  • 翻译表在 i18n.mjs,缺失项自动回退英文;stderr 会打印 [ifz-mcp] language=... 便于确认。

  • 文档翻译:English · 日本語 · Русский(配英文版架构/流程图为 docs/i18n/images/)。


3. 构建、安装与升级(v0.2.2)

3.1 编译插件

$gameRoot = 'C:\path\to\Infection Free Zone'
dotnet build plugin\IfzMcp.csproj -c Release `
  -p:IfzManaged="$gameRoot\Infection Free Zone_Data\Managed" `
  -p:BepInExCore="$gameRoot\BepInEx\core"

3.2 安装/升级到 Steam 版

# 必须先退出游戏(DLL 被加载时会锁定)
$target = Join-Path $gameRoot 'BepInEx\plugins\IfzMcp.dll'
if (Test-Path -LiteralPath $target) {
    Copy-Item -LiteralPath $target -Destination "$target.bak-$(Get-Date -Format yyyyMMdd)"
}
Copy-Item plugin\bin\Release\netstandard2.1\IfzMcp.dll $target -Force

如需通过脚本安装 BepInEx,把 BepInEx 5.4.23.2 Windows x64 压缩包放到 .local/tools/BepInEx_win_x64_5.4.23.2.zip,然后运行:scripts/Install-SteamPlugin.ps1 -GameRoot '<Steam 游戏安装目录>'(会校验 Ifz.dll SHA256 并退出要求)。

3.3 升级后自检

node client.mjs --steam status          # version 必须为 0.2.2
npm run tools:list                      # 默认 92 个工具
npm run tools:list -- --steam --workforce-only --allow-construction  # DSH 配置 65 个

3.4 v0.2.2 新增内容一览

批次

能力

工具

桥接

地形栅格(水/路/桥/高程)

get_terrain_grid

桥接

建筑资源图标、搜刮进度、按图标搜索

get_building_info、get_scavenge_progress、find_buildings_by_poi

桥接

远征地块、全图车辆(含未发现)

get_expedition_tiles、get_vehicle_map

桥接

任务详情/标记/目标进度

get_missions

桥接

作弊/调试 11 项

cheat_*

复合

地形报告、路线规划、搜刮目标/计划、日报、人口、武器、岗位、变更、找车

11 个

复合

敌人分析:总览/窝点/移动/战力/密度/变体/动物/中立

8 个

复合

进度解锁、暂停诊断、等待恢复

3 个

复合

资源热点、远征汇总、任务行动计划

3 个


4. 工程结构

InfectionFreeZone-MCP/
├─ plugin/                      # C# 插件(BepInEx)
│  ├─ Plugin.cs                 # 入口、会话、租约、Dispatch、advance
│  ├─ PipeBridge.cs             # 命名管道与主线程队列
│  ├─ WorldData.cs              # get_world_data 各类目
│  ├─ MapQuery.cs               # get_map_buildings(全图/近邻/走廊)
│  ├─ UnitControl.cs            # 小队/NPC 订单、装备、导航点
│  ├─ VehicleLogistics.cs       # 车辆与回仓
│  ├─ Terrain.cs                # get_terrain_grid(A* 图采样)
│  ├─ BuildingInfo.cs           # 建筑详情/资源图标/搜刮进度/按图标搜索
│  ├─ Expedition.cs             # 远征地块、全图车辆
│  ├─ Missions.cs               # 任务详情、单任务完成
│  ├─ Cheats.cs                 # 11 个作弊/调试桥接
│  └─ Hud.cs                    # 游戏内 HUD 提示
├─ server.mjs                   # MCP 服务与工具注册
├─ tools-extra.mjs              # 复合工具第一批(观察/经济/威胁/天气…)
├─ tools-extra2.mjs             # 第二批(地形报告/路线/搜刮计划/日报/岗位…)
├─ tools-extra3.mjs             # 第三批(敌人/感染变体/动物/中立/进度/暂停)
├─ tools-extra4.mjs             # 第四批(资源热点/远征汇总/任务行动计划)
├─ weather.mjs                  # 存档天气/月相解析(离线)
├─ client.mjs / map-query.mjs   # 命令行客户端
├─ coop.mjs                     # 1 倍速协作命令(brief/scavenge/return/check)
├─ runtime/                     # 常驻运行时(状态缓存/事件/执行/DSH 唤醒)
├─ handover/                    # 交接文档 + PS 5.1 浮窗启动器
├─ docs/img/                    # 文档配图(本 README 引用)
├─ scripts/                     # 构建/安装/测试副本启动
├─ renew/                       # 变更登记(每次改动必须写入)
├─ .local/                      # 本地缓存、测试脚本、监视器、快照(不入库)
└─ *.md                         # 架构/地图/路线/经验/协作规则等文档

测试与自检脚本

脚本

作用

npm run tools:list

MCP 握手并列出工具。可加 -- --read-only 检查纯只读配置

npm run tools:call

检查聚落、无线电、存档和态势,失败时退出码非零。可加 -- --steam --read-only 检查 Steam 连接

npm test

运行 Runtime 测试,无需启动游戏


5. 工具总览

平民派工与建筑

Codex 和 DSH 的示例配置使用 --workforce-only --allow-construction。AI 可以派工、建造和管理设施,玩家负责小队。get_enemy_report 和 get_fog_of_war 提供敌情与迷雾查询。

  • get_workforce 列出可用人数、分配模式和任务。update_work_task 接收刚读到的 expected_value。手动模式设置 assigned_workers,优先级模式设置 max_workers 或 priority。

  • get_construction_catalog 列出可建造类型、解锁和尺寸限制。preview_construction 核对整块地基的水面、坡度、相邻建筑和材料,并返回人员容量、施工与生产工时。

  • new 可直接指定最终用途、中心 x 和 z、长宽高及外墙。完工时自动成为目标建筑。adapt 使用 building_id 改造现有建筑。取得写租约后通过 queue_construction 提交,再用同一 request_id 查询 get_construction_order。

  • 指定位置可以说「总部中心向东 30 米、向北 20 米」。向东增加 x,向北增加 z。

  • get_facilities 按生产、防御或医疗类型查询设施。set_facility_production 可安排配方切换,set_facility_defense_weapon 可更换城门和塔的武器。医院提供医生和床位查询,医生人数走派工工具。

5.1 桥接·只读

工具

说明

status

桥接版本、场景、会话、租约持有者

get_state

时间、暂停原因、总部、小队概览、advance 状态

get_current_weather

当前聚落的天气、气温(°C)、降水、风和月相

get_mood

居民情绪等级、趋势、起因以及对工人效率和出生率的影响

get_order

查询某次移动订单的结果

get_world_data

14 类对象分页读取(见 §5.5)

get_map_buildings

建筑查询:全图/近邻/路线走廊,可只返回可搜刮

get_navigation_point

单点投影:地面坐标、高度、area、偏移

get_terrain_grid

地形栅格:水/路/建筑/墙/桥候选/高程,一次调用(A* 图采样)

get_building_info

建筑详情:类型、状态、资源图标、搜刮进度、剩余物资

get_scavenge_progress

进行中的搜刮:进度、剩余时间、剩余物资箱、内部人数

find_buildings_by_poi

按图标找建筑:["Gun","Fuel","Drugs"...]

get_expedition_tiles

远征地块:类型/位置/资源图标/搜刮进度/已获资源

get_vehicle_map

全图车辆(含未发现):类型/状态/油量/货物/距离

get_missions

任务详情:标题键/章节/限时/目标类型与进度/标记坐标

get_active_dialogue

无线电正文、可选项、后果提示和上次选择后的台词

get_squad_experience

队员的各项熟练度、已激活技能和当前武器实际射程

get_weapon_details

武器的基础射程、伤害、攻击间隔、弹药和使用限制

get_attack_conditions

指定小队对可见敌群的实时射程、视线、弹药、冷却和开火状态

5.2 桥接·写操作(17)

工具

说明

acquire_control / release_control

领取/续租/释放写租约(默认 90 秒)

pause

显式暂停(常规订单写入前必需)

advance

有界推进(1–12 墙钟秒,keep_running 保持 1x)

hud_message

游戏内 HUD 短提示

move_squad

小队移动(6–100 单位/步,replace_orders 覆盖)

cancel_squad_order

按原请求 ID 终止一个已跟踪的原生小队订单

move_npc_group

非玩家群组移动目标

attack_group

攻击可见敌对群

scavenge_building

派队搜刮建筑

return_to_stockroom

回仓卸货(步行/乘车语义不同)

take_vehicle

占领废弃车辆

set_stockpile_amount

设置库存数量(先读 expected_amount)

set_building_workers

调整工地岗位上限

equip_squad_member

从背包/库存装备武器

refill_squad_member_ammo

从容器补充弹药

choose_dialogue_option

通过游戏原生按钮提交当前无线电选项

5.3 桥接·作弊/调试(11,紧急使用)

工具

说明

cheat_list

列出作弊项

cheat_heal_squads

全员满血

cheat_refill_ammo

弹药补满

cheat_add_resources

直接向库存加资源

cheat_unlock_expedition

解锁全部远征地块

cheat_complete_missions

完成全部进行中任务

cheat_complete_mission

完成单个任务(更精细)

cheat_scavenge_all

全图废弃建筑标记已搜刮

cheat_set_time

设置天数/小时/时间流速

cheat_spawn_squad

指定坐标刷小队

cheat_reveal_groups

显示全部敌对群(含隐藏)

5.4 本地/复合(34 + 天气)

基础聚合

工具

说明

get_weather

天气/月相/38 天预报(读存档,离线可用)

observe

一次拿全:时间/小队+载具/库存/缺口/敌情/天气

get_daily_report

日报:时间/天气/缺口/工地/威胁/任务

get_threats

敌情摘要(距离/方位/是否逼近,含隐藏群)

get_economy

资源缺口 + 空置岗位

get_squads_report

小队名册(指令/血量/载货/油量)

get_events_report

任务与事件精简列表

get_save_info

最新存档信息 + 天气(离线)

get_map_info

城市/瓦片/边界

get_recommendations

启发式建议(回防/补资源/调岗/撤退)

bridge_probe

桥接延迟测量

export_snapshot

导出世界快照到 .local/snapshots/

地形与路线

工具

说明

get_terrain_report

水域/道路/建筑占比、桥梁坐标、高程、最通畅走廊

plan_route

A* 步行路线(道路便宜、水/墙阻挡),返回距离/途经点/过桥格数

搜刮与发展

工具

说明

get_loot_targets

未搜刮建筑按距离排序 + 每队最近目标 + 300 m 聚类

get_scavenge_plan

贪心分配:每队独立建筑序列

get_colonists_report

人口/儿童/武装人数/伤员/岗位分布

get_weapons_report

武器类型表 + 各队武器构成

get_worker_balance

空置岗位 vs 岗位分布 + 配人建议

get_vehicle_hunt

车辆清单 + 最近小队 + 未占领车辆

get_changes

与上次调用差异(库存/血量/指令/威胁数;落盘缓存)

敌情与生物

工具

说明

get_enemy_report

敌群总览:武器构成/火力评分/距离方位/逼近判断

get_enemy_lairs

窝点清单(感染者/感染犬窝点分类、威胁排序)

get_enemy_moves

移动追踪(两次调用间位移,落盘缓存)

get_combat_estimate

对可见敌群评估战力,并结合当前开火条件和补给给出建议

get_enemy_density

敌群密度 ASCII 热图

get_infected_types

感染者变体识别(普通/自爆/阿尔法/犬/鸟/尖啸/巨型/巨兽/强化)

get_animal_report

感染动物 + 普通野生动物(物种/数量/敌对性)

get_neutral_report

中立群/野生动物/移民(标注不可攻击)

进度、暂停与任务

工具

说明

get_progression

存档 232 项内容解锁状态(建筑/生产/敌人生成/科技;离线)

diagnose_pause

暂停原因诊断 + 恢复建议

wait_unpaused

轮询等待解除暂停(超时返回具体原因)

get_resource_hotspots

按资源图标统计建筑数量与最近位置

get_expedition_summary

远征汇总:地块分布、资源图标总量、最富地块

get_mission_plan

任务行动计划:按目标类型给可执行下一步

5.5 get_world_data 类目

category

数据

squads

小队、成员坐标/生命/武器/弹药/背包

citizens / workers

人口 / 工人、生命、年龄类别、当前工作

groups / virtual_groups

实体/虚拟非玩家群(含隐藏)、阵营、位置、可见性

map

城市、瓦片、世界边界

worksites

有工作的建筑、在岗/上限/原始上限

vehicles

已发现或玩家拥有的车辆(含后备箱/油量)

stockrooms

可用共享仓库/总部

stockpile / ground_resources

共享库存(实物+虚拟) / 地面资源

resource_types

可写入库存的资源 ID

weapons

武器定义、弹药类型、弹匣容量

events

已触发事件、任务目标完成状态、标记坐标


6. 复合工具详解

6.1 一次看全(省 token 首选)

node client.mjs --steam observe '{}'
# { time, headquarters, squads[], stockpile, shortfalls[], threats{count,closing,nearest[]}, weather }

6.2 任务全部真做(不跳过)

node client.mjs --steam get_missions '{"include_types":true}'
node client.mjs --steam get_mission_plan '{}'

get_mission_plan 会按目标类型给出可执行动作:

目标类型

给出的动作

KillCharacters / DefeatInfected / ClearLair

最近敌对群/窝点 + 最近队伍 + 先 get_combat_estimate

ScavengeResource / SendSquadToScavengeBuilding

最近可搜刮建筑(可直接 scavenge_building)

CollectResource / ProduceResource

空置工地(可派工)

AssignWorkers

空置岗位 + 可设置的岗位上限

HealGroup

低于 60 血的队伍

SendToMarker / SendToMarkers

任务标记坐标 + 最近队伍

AdaptBuilding 类

提示"需玩家在游戏内选楼"

SurviveNight

日落倒计时

6.3 资源图标(与游戏地图图标同规则)

node client.mjs --steam find_buildings_by_poi '{"poi":["Gun","Fuel"]}'
node client.mjs --steam get_resource_hotspots '{"radius":2000}'
node client.mjs --steam get_building_info '{"building_id":"534237227"}'

图标枚举:Research、Drugs、Tools、Food、Bakery、Barn、Fuel、Gun、Parking、Expedition、Warehouse、Sport、Museum、Metal。

建筑内具体物资清单只有玩家小队首次进入后才生成(ScavengeWork.ResourcesToFind),进入前靠图标判断;进入后 get_building_info 可读剩余物资与进度。

6.4 地形与路线

node client.mjs --steam get_terrain_report '{"step":75}'
node client.mjs --steam plan_route '{"from_x":1430,"from_z":1146,"to_x":1580,"to_z":960}'
  • 地形采样自 A* recast 图(Tag:0 地面 / 2 水 / 4 墙 / 6·7 建筑 / 29·31 道路)

  • 一次调用 42×42 网格约 26 KB,1.2 s 内返回(含 CLI 启动)

6.5 敌人与生物

node client.mjs --steam get_enemy_report '{}'
node client.mjs --steam get_enemy_lairs '{}'
node client.mjs --steam get_infected_types '{}'
node client.mjs --steam get_combat_estimate '{"group_id":"<群ID>"}'
node client.mjs --steam get_enemy_density '{"step":250}'

感染者变体(来自 ResourceID / InfectedTypes):

变体

ID

tier

战力权重

普通感染者

eq_inf_human

1

0.4

感染犬 / 鸟

eq_inf_dog / eq_inf_bird

1

0.35 / 0.5

低吼者 / 尖啸者

eq_inf_growler / eq_inf_screamer

2

0.7 / 0.8

自爆感染者

eq_inf_human_explosives

3

1.3

巨型感染者

eq_inf_huge

3

1.5

阿尔法感染者

eq_inf_alpha

4

1.6

感染熊/驼鹿/公牛

eq_inf_bear/moose/bull

3

1.4

巨兽(坦克级)

inf_tank_bear/bull/moose

4

2.0

强化版

*_boosted

+1

+0.2~0.5

巨兽/自爆/阿尔法/感染鸟属于后期进度解锁或未启用的生成项(见 get_progression 的 GroupSpawn_* 状态)。

6.6 进度与暂停

node client.mjs --steam get_progression '{"category":"enemy"}'
node client.mjs --steam diagnose_pause '{}'
node client.mjs --steam wait_unpaused '{"timeout_s":30}'
  • get_progression 读存档 ContentStateController(232 项,当前档已解锁 72 项)

  • 暂停四类:popup_pause(弹窗,需玩家点)/ ui_pause(面板,Esc)/ paused(空格)/ 失焦降频


无线电可选回复会产生 dialogue_options_available 事件。读取和选择流程见 Runtime 无线电剧情选择。

6.7 小队经验和武器详情

  • get_squad_experience 接受可选的 squad_id。每名存活队员返回射击、近战、搜刮和驾驶的当前经验与上限,以及已激活技能、当前使用的武器和 effective_range。射程使用游戏对该队员的实际计算,包含神枪手技能修正。

  • get_weapon_details 接受可选的 weapon_id,例如 eq_sniper_rifle。武器目录给出聚落与远征基础射程、近距阈值、武器提示中的近远伤害、射击间隔、弹药、弹匣和使用条件。

  • 两个工具都使用 get_state 返回的 session_id,可在原生 MCP 的 --read-only 模式下调用。射程以游戏世界单位计。

6.8 开火条件和紧急中止

  • get_attack_conditions 接受 session_id、squad_id 和 group_id。每名队员以最近的敌方成员为目标,返回有效射程、视线、剩余弹药、冷却以及当前站位能否开火。虚拟敌群传 virtual: true,返回虚拟战斗模式。

  • get_combat_estimate 汇总所选小队的开火人数,优先提示低血、缺弹、暂停、站位或冷却问题。

  • 协作模式用 Runtime 的 action_force_stop 按任务 ID 终止订单并显示原因。原生写模式可用 cancel_squad_order,order_id 传原订单的 request_id,另生成一个取消请求 ID。两者都按订单实例取消。

7. 写入链路与人机协作

写入链路

标准写入流程(详见 runtime/README.md 与 AI游戏协作规则.md):

get_state → acquire_control → pause → 下单(request_id) → advance(keep_running) → 复查 → release_control

7.1 一次移动示例

node client.mjs --steam get_state
# 记下 session_id / 空闲小队
node client.mjs --steam acquire_control '{"owner":"dsh-lead","ttl_seconds":180}'
# 记下 lease
node client.mjs --steam pause '{"lease":"<lease>","session_id":"<sid>"}'
node client.mjs --steam get_navigation_point '{"session_id":"<sid>","x":1500,"z":1600,"y":25}'
node client.mjs --steam move_squad '{"lease":"<lease>","session_id":"<sid>","request_id":"<uuid>","squad_id":"53","x":1500,"z":1600}'
node client.mjs --steam advance '{"lease":"<lease>","session_id":"<sid>","seconds":8,"keep_running":true,"allow_background":true}'
node client.mjs --steam release_control '{"lease":"<lease>"}'

7.2 1 倍速协作命令(coop.mjs)

node client.mjs --steam coop brief --near 835
node client.mjs --steam coop scavenge --session <sid> --player 834 --squad 835 --building 417900143 --notice "去总部东南约200米的楼搜刮"
node client.mjs --steam coop return  --session <sid> --squad 835
node client.mjs --steam coop check   --session <sid> --squad 835

7.3 错误码速查

错误码

处理

bridge_offline

启动游戏(Steam 版或测试副本)

not_ready / stale_session

载入聚落后重新 get_state

lease_required

先 acquire_control;持有时传入原 lease 续租

control_busy

其他客户端持租约;用原 lease 续租或等待

pause_required

重新 pause(玩家操作会让游戏解除暂停)

speed_locked

玩家锁定速度,不要强制改速

scavenge_unavailable

目标不可搜/已搜/远征中/不可达(CanGoToStructure)

squad_unavailable

小队忙/在车上;显式 replace_orders 或换队

result_unknown

用同一 request_id 重试

order_not_found

移动回执不存在或已超出最近记录,重新读取小队实际状态


8. 作弊/调试工具与使用政策

启动原生 MCP 时可加 --enable-cheats,通过 cheat_catalog 查询分类和参数,通过 cheat_apply 执行单项操作。纯只读模式可查询目录。

  • 11 个 cheat_* 全部要求写租约,走游戏原生 GameConsoleCommandHandler 与容器接口。

  • 仅限紧急:关键小队即将全灭、存档卡死、任务无法完成、玩家明确要求;先用非作弊手段。

  • 执行顺序:只读诊断 → 最小干扰命令 → 立刻复查数据(observe/get_threats/get_state)→ 记录到 .local/runs/。

  • 详细政策见 handover/README.md 第 9 节。

node client.mjs --steam cheat_list '{"lease":"<lease>","session_id":"<sid>"}'
node client.mjs --steam cheat_heal_squads '{"lease":"<lease>","session_id":"<sid>"}'
node client.mjs --steam cheat_add_resources '{"lease":"<lease>","session_id":"<sid>","resource_id":"res_metal","quantity":20}'

9. 游戏内聊天浮窗与多智能体监视

  • 浮窗:handover/Start-ChatWindow-ps5.ps1(PowerShell 5.1 兼容),回车插话、Ctrl+回车打断;需要 runtime 在 8790 端口运行。

  • 启动方式、恢复清单、故障排查见 handover/README.md。

  • 可用 Runtime 的 /state 和 /events 实现本地只读监视,协作模式由单个执行方持有游戏写租约。


10. 数据来源与离线能力

数据

来源

是否需要游戏运行

实时状态/订单/单位

命名管道 → 插件(Unity 主线程)

是

实时天气、气温、居民情绪

游戏 WeatherController、MoodController

是

天气、月相、38 天预报

存档 data.json → WeatherControllerSerialized

否

进度解锁(232 项)

存档 ContentStateController._contentStatesList

否

存档信息(天数/城市/时间)

存档 info.json

否

地形原始块

存档 Terrain/*.bytes(3×3,MessagePack 结构,约 300 KB/块)

否(解析器待做;当前用插件在线栅格)


11. 常见问题(FAQ)

Q1:vehicles 类目为空? get_world_data(vehicles) 只返回已发现或玩家拥有的车。用 get_vehicle_map 看全图(含未发现的废弃车)。

Q2:建筑里有什么查不到? 物资列表在小队首次进入废墟时才生成。进入前用 find_buildings_by_poi / get_building_info 的 poi_icons 判断;进入后用 get_building_info / get_scavenge_progress 读剩余物资与进度。

Q3:远征查不到? get_expedition_tiles 需要先在游戏里打开世界地图(远征界面)让瓦片加载,否则返回 expedition_not_ready。

Q4:任务能直接跳过吗? 可以(cheat_complete_mission(s)),但默认不用——按 get_mission_plan 逐步真做;作弊仅紧急。

Q5:搜索/搜刮经常 scavenge_unavailable? 插件校验四条件(远征中/不可搜/已搜过/CanGoToStructure),其中 Draft.IsInteractable、Creating、Deconstructing、hideout 权限都会拒绝;换目标或先 get_building_info 看状态。

Q6:游戏一直暂停? 先 diagnose_pause:弹窗需玩家点击;面板按 Esc;手动暂停按空格;失焦切回前台。

Q7:桥接离线怎么办? 本地工具仍可用:get_weather、get_save_info、get_progression、export_snapshot(部分)、bridge_probe 除外。

Q8:deflate/MessagePack 地形解析做到哪了? 已确认 Terrain/*.bytes 是 MessagePack(0x83 "version"/"1"/"data" 头),解析器尚未完成;当前优先用插件 get_terrain_grid(更快且含道路/水面语义)。


12. 项目文档索引

文档

内容

架构分析-三大基础能力.md

实时状态/持续交流/异步执行系统设计;DSH 驱动/流式/中断;数据体量排名与查询策略

地图数据量分析.md

地图类目实测:金华 6749 栋≈1.58 MB/68 页;Ruciane 378 栋≈164 KB

地图数据优化方案.md

P0 纯 Node → P1 插件过滤 → P2 推送订阅的渐进优化

地图分块读取方案.md / 地图分块分配策略.md / 地图分块数量与障碍物分析.md

按网格分块读取、坐标→块定位、覆盖块数、A* 障碍信息

地图分层结构分析.md

聚落地图与远征地图的分层/分块策略

路线分析.md

游戏类、字段与原生修改入口(本机反编译记录)

AI游戏协作规则.md

人机分工、车辆补给、敌情优先级、同步操作约定

经验-无感染区AI协作.md

实战经验手册 + 问题分析(工具边界、搜刮/战斗/天气坑位、沟通协议、实测数据)

handover/README.md

交接:游戏内浮窗 + 多智能体监视 + 恢复清单 + 故障排查 + 作弊政策

runtime/README.md

常驻运行时:状态缓存、事件、执行队列、DSH 唤醒

renew/README.md / renew/0.1.txt

变更登记规范与全部修改记录

docs/img/

文档配图:architecture / workflow / toolmap

docs/i18n/README.en.md

English README(英文版文档,含英文架构/流程图为 docs/i18n/images/)

docs/i18n/README.ja.md

日本語 README(日文版文档)

docs/i18n/README.ru.md

Русский README(俄文版文档)

docs/i18n/

多语言文档目录(English / 日本語 / Русский + 英文配图)

LICENSE

许可证全文:PolyForm Noncommercial 1.0.0(允许非商业使用/修改/再分发,禁止商用)

THIRD_PARTY_NOTICES.md

第三方依赖许可证与游戏知识产权说明(本仓库不分发游戏文件)


13. 变更登记

每次更新必须写入 renew/README.md 与 renew/0.1.txt。

  • v0.2.2(2026-11-12):插件版本 0.2.2;工具 74 个(+地形栅格、建筑图标、远征、车辆、任务、11 个作弊、任务行动计划等);新增文档配图与详细 README。

  • v0.2.0(2026-11-11):作弊/地形批次;工具 32→43。

  • v0.1(2026-11-10):桥接、只读查询、移动/搜刮/攻击/装备、天气、运行时与协作层。


14. 许可证 / License

本项目采用 PolyForm Noncommercial 1.0.0:

允许

不允许

✅ 下载、阅读、学习

❌ 任何商业用途(付费分发、商业服务、企业内部商业运营等)

✅ 修改、二次开发

❌ 移除版权/许可声明后分发

✅ 非商业再分发(需附带 LICENSE 与 Required Notice)

❌ 分发游戏本体/游戏资源/Ifz.dll

  • 许可全文:LICENSE(含 Required Notice: Copyright (c) 2026 tianq021 and InfectionFreeZoneMcp contributors)。

  • 第三方依赖(MCP SDK / zod / ws / BepInEx / Harmony / A* / Odin / Zenject 等)各自保留原许可证;游戏本体与资源 © JutsuGames,本仓库不分发游戏文件。详见 THIRD_PARTY_NOTICES.md。

  • 需要商业授权时请通过仓库 Issue 联系作者。

  • 说明:PolyForm Noncommercial 属于"源码可见 + 非商业"许可,并非 OSI 认证的开源许可;如需 OSI 开源许可(如 MIT/Apache-2.0)可另议。

Available Tools

74 tools
acquire_controlB

Claim the shared write lease or renew it by passing the existing token.

Inputs: owner (required), lease.

advanceA

Run the simulation at normal speed for at most 1–12 wall-clock seconds. Poll get_state. The bridge reapplies gameplay pause at the deadline unless keep_running is set. Background advance requires Unity to run in the background and explicit allow_background.

Inputs: lease (required), seconds (required), session_id (required), keep_running, +2 more.

attack_groupB

Queue a native attack on a visible hostile group. Read the squad's active and queued orders to follow it.

Inputs: lease (required), group_id (required), squad_id (required), request_id (required), +3 more.

bridge_probeB

Measure round-trip latency of the game bridge and report session readiness.

Inputs: samples.

cheat_add_resourcesA

Add resources straight into the shared stockpile, bypassing scavenging. Requires the write lease.

Inputs: lease (required), session_id (required), resource_id (required), quantity.

cheat_complete_missionA

Complete the objectives of ONE active mission (by mission_id). Safer than cheat_complete_missions which finishes everything. Requires the write lease.

Inputs: lease (required), mission_id (required), session_id (required).

cheat_complete_missionsA

Immediately complete all active missions and their objectives (story progression shortcut). Requires the write lease.

Inputs: lease (required), session_id (required).

cheat_heal_squadsA

Heal every member of the player's squads back to full health (keeps current max HP). Requires the write lease.

Inputs: lease (required), session_id (required).

cheat_listA

List the available cheat/debug bridge methods and their arguments. Requires the write lease.

Inputs: lease (required), session_id (required).

cheat_refill_ammoA

Refill the ammunition of every weapon carried by the player's squads. Requires the write lease.

Inputs: lease (required), session_id (required).

cheat_reveal_groupsB

Reveal every hostile group on the map, including hidden ones. Requires the write lease.

Inputs: lease (required), session_id (required).

cheat_scavenge_allB

Mark every abandoned building on the map as scavenged in one step. Requires the write lease.

Inputs: lease (required), session_id (required).

cheat_set_timeA

Set the in-game day/hour or the time-speed multiplier. Requires the write lease.

Inputs: lease (required), session_id (required), day, hour, +1 more.

cheat_spawn_squadA

Spawn a new player squad at a walkable position. Requires the write lease.

Inputs: x (required), z (required), lease (required), session_id (required), +2 more.

cheat_unlock_expeditionA

Unlock every expedition tile on the world map. Requires the write lease.

Inputs: lease (required), session_id (required).

diagnose_pauseA

Explain why the game is paused (popup / UI panel / manual or event pause / focus loss) and what can resume it.

Inputs: no named parameters.

equip_squad_memberC

Equip an existing weapon from squad cargo or stockpile. Uses one weapon and drops the previous non-default weapon via the native handler.

Inputs: lease (required), source (required), squad_id (required), member_id (required), +3 more.

export_snapshotA

Write a JSON snapshot of the current world (time, squads, threats, economy) to .local/snapshots/ and return the file path. Read-only with respect to the game.

Inputs: label.

find_buildings_by_poiC

Find buildings by map resource icon: pass POI archetypes such as ["Gun","Fuel","Drugs","Metal"]. Uses the same OSM tag rules as the in-game icons.

Inputs: poi (required), session_id (required), x, z, +3 more.

get_animal_reportB

Animals overview: infected animals (dogs, birds, bears, moose, bulls, giants) plus normal wildlife (boar, deer), with species, count, distance and hostility.

Inputs: radius, include_hidden, include_normal.

get_building_infoB

Read one building: type, state, scavenge flags, resource icons (Gun/Fuel/Drugs/Tools/Metal/Warehouse...), and loot details when a squad has already entered it (scavenge progress + remaining crates).

Inputs: session_id (required), building_id (required).

get_changesA

Diff since the previous call in this MCP process: stockpile deltas, squad health changes and hostile count change. Call repeatedly to watch the settlement.

Inputs: no named parameters.

get_colonists_reportB

Population overview: totals, children, job distribution, armed/unarmed adults, wounded count and the workers assigned to each job.

Inputs: no named parameters.

get_combat_estimateB

Heuristic combat estimate for chosen squads against one hostile group: firepower scores, member counts, HP, and advice (attack / retreat / need reinforcements).

Inputs: group_id (required), virtual, squad_ids.

get_daily_reportA

Concise situation report combining time, weather/moon, economy shortfalls, hostile summary, mission progress and heuristic recommendations.

Inputs: no named parameters.

get_economyB

Resource shortfalls versus development thresholds plus worksite staffing (idle construction jobs) in one call.

Inputs: include_worksites.

get_enemy_densityB

ASCII heatmap of hostile group members over the map (default 250-unit cells), useful for seeing where the threats concentrate.

Inputs: step, radius, include_hidden.

get_enemy_lairsA

List infected/bandit lairs (hideout groups) with strength, distance, direction and a rough threat ranking, so the AI can decide which nest to clear first.

Inputs: radius.

get_enemy_movesA

Track hostile group movement between calls (persisted to .local/cache): shows groups that changed position/destination, their speed and estimated arrival at HQ.

Inputs: no named parameters.

get_enemy_reportB

Enemy overview: every hostile group with type, member count, weapon mix, firepower score, distance/direction, whether it is moving toward the settlement, and the nearest squad.

Inputs: radius, min_size, include_hidden.

get_events_reportB

Active missions with objective completion and a list of triggered events, condensed.

Inputs: no named parameters.

get_expedition_summaryA

Expedition overview: loaded tile count, scavenged fraction, area/location type distribution, aggregated resource icons (Gun/Fuel/...) and the richest tiles. Open the world map in-game first.

Inputs: limit, radius.

get_expedition_tilesA

List loaded expedition tiles: area/location type, resource icons (Gun/Fuel/Drugs...), scavengable state, scavenge progress and collected resources. Open the world map in-game first so tiles load.

Inputs: session_id (required), limit, radius, only_scavengable.

get_infected_typesA

Break down infected groups by variant: normal infected, infected dogs, suicide bombers (explosives), alpha infected, birds, giants and boosted variants. Returns counts, HP range, tier and which squads are nearest.

Inputs: radius, include_lairs, include_hidden.

get_loot_targetsB

Rank un-scavenged buildings for the AI squads: nearest targets, per-squad distances and building clusters (dense areas give more loot per trip).

Inputs: limit, radius, squad_id.

get_map_buildingsA

Read one page of buildings. Choose full for the whole map, nearby for a circle, or route for a corridor. Follow next_offset for another page.

Inputs: session_id (required), limit, scope, offset, +4 more.

get_map_infoA

Map bounds, tile size and city name from the running game.

Inputs: no named parameters.

get_mission_planA

For every active mission objective, produce concrete next actions from live data: which hostile groups to kill, buildings to scavenge/adapt, markers to visit, wounded squads to heal, idle worksites and sunset countdown. Complements get_missions (which lists objective types).

Inputs: no named parameters.

get_missionsB

Detailed active missions: title key, chapter, time limit and per-objective progress (kill counts, hideout counts, buildings visited). Optionally list all objective types.

Inputs: session_id (required), include_types.

get_navigation_pointC

Project a world point onto the game's walkable ground mesh and read its height and area.

Inputs: x (required), y (required), z (required), session_id (required).

get_neutral_reportA

List non-hostile groups: neutral bandits (hostile_to_player=false), animals, immigrants and other neutral factions, with weapons, distance and whether they can be attacked at all.

Inputs: radius, include_hidden, include_animals.

get_orderC

Inspect the result of a move. Read position and target to verify arrival.

Inputs: order_id (required), session_id (required).

get_progressionA

Read the save's ContentStateController: which buildings, productions, enemy spawn types and tech are unlocked vs still locked by story progression. Works offline (no game bridge needed).

Inputs: filter, category, include_unlocked.

get_recommendationsB

Heuristic action list for the AI squad leader: defend, resupply, reassign workers, retreat wounded.

Inputs: no named parameters.

get_resource_hotspotsB

One-call scan of buildings carrying resource icons: for each POI type (Gun/Fuel/Drugs/Tools/Metal/Warehouse/Food) show how many exist and the nearest few, using the same OSM icon rules as the game.

Inputs: types, radius, per_type.

get_save_infoA

Local save metadata (newest save name, in-game day/time text, city) plus weather and moon phase. Works even when the game bridge is offline.

Inputs: no named parameters.

get_scavenge_planA

Greedy scavenging plan: assigns each squad its own nearest cluster and returns concrete building_id sequences that can be executed with scavenge_building.

Inputs: radius, per_squad, squad_ids.

get_scavenge_progressB

List every in-progress scavenge: progress 0-1, time left, remaining loot crates and characters inside.

Inputs: session_id (required), limit.

get_squads_reportB

Squad roster with orders, health, cargo, assigned vehicle, trunk load and fuel in one call.

Inputs: no named parameters.

get_stateC

Read time, pause reasons, HQ, player squads and the last bounded advance.

Inputs: no named parameters.

get_terrain_gridB

Sample the game's navigation graph into a terrain grid in one call: walkability, water, roads, building interiors, bridge candidates and optional ground heights. Much faster than repeated get_navigation_point calls (needs plugin 0.2).

Inputs: session_id (required), step, max_x, max_z, +4 more.

get_terrain_reportA

One-call terrain analysis: water/road/wall/building shares, bridge candidates with coordinates, elevation range and the clearest corridor rows. Uses get_terrain_grid internally.

Inputs: step, include_ascii.

get_threatsB

List hostile groups with distance/direction to HQ and to player squads, plus whether they are moving toward the settlement. Hidden groups are included by default.

Inputs: limit, max_distance, include_hidden.

get_vehicle_huntB

List vehicles with ownership, cargo/fuel and the nearest squad, plus unowned vehicles suitable for early-game capture.

Inputs: radius.

get_vehicle_mapA

List every vehicle on the map including undiscovered wrecks (get_world_data only shows discovered/owned ones), with type, state, fuel, cargo and distance to HQ.

Inputs: session_id (required), limit, radius, include_undiscovered.

get_weapons_reportA

Weapon and ammunition overview: weapon types available, magazine sizes, per-squad composition and members without firearms.

Inputs: no named parameters.

get_weatherA

Read current weather, moon phase and the 38-day forecast from the newest save file. The bridge has no weather endpoint, so this reads on-disk save data and may lag by up to one in-game day. A full moon night usually brings a large horde.

Inputs: save_root, all_forecast.

get_worker_balanceB

Compare idle construction jobs with the current job distribution and suggest which sites to staff first.

Inputs: no named parameters.

get_world_dataB

Read a page from live game objects across the map. Nonplayer groups include hidden groups. Use get_map_buildings for building details.

Inputs: category (required), session_id (required), limit, offset.

hud_messageC

Show a short message on the in-game HUD overlay so the player can read AI updates and alerts without leaving the game.

Inputs: text (required), seconds.

move_npc_groupC

Submit a native movement target for a nonplayer group. NPC AI may choose another target after simulation resumes.

Inputs: x (required), z (required), lease (required), group_id (required), +3 more.

move_squadA

Queue a native move 6–100 world units away. Set replace_orders to override existing orders or move a vehicle. Pause first. Retry with the same request_id.

Inputs: x (required), z (required), lease (required), squad_id (required), +3 more.

observeA

Composite snapshot: game time, HQ, squads with vehicles, stockpile, hostile summary and weather in one call. Aggregates several bridge reads (no extra plugin support needed).

Inputs: include_groups, max_threat_distance.

pauseB

Apply gameplay pause without dismissing popups.

Inputs: lease (required), session_id (required).

plan_routeB

Plan a walkable route between two world points on the game's pathfinding graph (roads cost less, water/void blocked). Returns distance, waypoints and how many bridge cells the route uses.

Inputs: to_x (required), to_z (required), from_x (required), from_z (required), +2 more.

refill_squad_member_ammoC

Refill a member's weapon from matching ammunition in the chosen container.

Inputs: lease (required), source (required), squad_id (required), member_id (required), +2 more.

release_controlB

Pause any active advance and release the write lease.

Inputs: lease (required).

return_to_stockroomA

Order a squad into a shared stockroom or headquarters. Aboard a vehicle the game unloads the trunk on arrival; a walking squad enters on foot and deposits carried resources. Omit stockroom_id to return to headquarters.

Inputs: lease (required), squad_id (required), request_id (required), session_id (required), +3 more.

scavenge_buildingC

Send a squad to enter and scavenge a building that can be scavenged.

Inputs: lease (required), squad_id (required), request_id (required), session_id (required), +2 more.

set_building_workersC

Change a building job's worker limit using the same setter as the game. Read worksites for assigned workers and valid limits.

Inputs: lease (required), request_id (required), session_id (required), building_id (required), +2 more.

set_stockpile_amountA

Set a supported resource in the shared stockpile while paused. Read resource_types for editable IDs and pass the current quantity as expected_amount.

Inputs: lease (required), amount (required), session_id (required), resource_id (required), +1 more.

statusB

Check whether the configured IFZ game and its current settlement are ready.

Inputs: no named parameters.

take_vehicleA

Order a walking squad to reach a discovered abandoned vehicle and take it over. The squad walks there and boards natively; read squads and vehicles afterwards to confirm the owner change.

Inputs: lease (required), squad_id (required), request_id (required), session_id (required), +2 more.

wait_unpausedA

Poll until the game is unpaused (and no popup/UI pause), up to a timeout. Useful right before issuing orders.

Inputs: timeout_s.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 74 tools

    Disambiguation2/5

    Read-side tools overlap heavily: observe, get_daily_report, get_state, get_world_data, get_save_info and get_threats all return overlapping world snapshots, and the enemy family (get_enemy_report, get_enemy_lairs, get_enemy_moves, get_infected_types, get_animal_report, get_neutral_report, get_enemy_density, get_threats) has fuzzy boundaries. Descriptions hint at differences (e.g. get_mission_plan complements get_missions), but an agent could easily pick the wrong report for a simple question.

    Naming Consistency3/5

    Everything is snake_case and reads consistently, and cheats share a cheat_ prefix. However verbs are mixed: bulk reads use get_*, while many action tools use bare imperatives (observe, status, pause, advance, move_squad, scavenge_building, take_vehicle, hud_message), so there is no single predictable pattern.

    Tool Count1/5

    74 tools for one game bridge is far beyond a well-scoped surface, and many earn no unique place (a dozen near-duplicate enemy/report readers). The cheat_* family alone adds ten rarely-used tools, pushing the set well past the 50+ extreme-mismatch threshold.

    Completeness3/5

    Coverage of reading state, movement/combat/scavenge orders, terrain routing and cheats is broad, but core loop operations are missing: no construction/placement order, no research/tech assignment (only reading progression), no recruitment or squad management beyond equipping, and no save/load. Agents can read nearly everything but cannot drive several major game systems.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents and scripts to inspect objects, call functions, and run Lua in a running UE4SS game via MCP, with no sockets or admin rights required.
      26
      27 PyPI
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents and streamers to monitor and control Oxygen Not Included gameplay through MCP, including world editing, colony alerts, building orders, navigation, dupe management, and game speed control.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients such as AstrBot, Claude, Cursor, or custom scripts to control a Minecraft bot over SSE through 49 tools covering perception, movement, building, gathering, crafting, combat, farming, memory, social interaction, and autonomous skills. It supports multi-client body control, emotion and event context, and survival/companion behaviors.
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI clients to observe and control the game Amazing Cultivation Simulator through an in-game mod bridge, exposing world/NPC/map state, FairyGUI control and map input, native commands, work and schedule settings, plus time control so agents can run an observe-decide-act loop.
      3
      MIT