DOS2 Game Master

dos2-gm-mcp

English · Русский

一个 MCP 服务，让 AI 助手能够准备并运行 《神界：原罪 2 — 终极版》中的 GM 模式战役。

它分为两个层面：

• 战役文件。 读取并编辑磁盘上的 GM 战役：NPC 和物品模板、使用自制美术素材的插画、地图便签、日志、场景氛围、附加模组。每次写入前都会先创建备份。
• 实时游戏。 通过适用于 Norbyte's Script Extender 的小型桥接模组与正在运行的游戏通信：列出当前关卡中的角色、从模板生成 NPC、移动、重命名、升级、隐藏和显示，或在游戏服务端运行任意 Lua 代码。

GM 便签概览地图	有商人和储藏物的酒馆场景

你可以提出的请求

• “向我展示战役 My Campaign 中的内容：场景、模板、插画。”
• “创建一个名为 Old Greta 的 NPC 模板，等级为 10，基于 Larian 示例战役中的女巫原型，并包含以下三个技能。”
• “添加一张带有这张图片和三个投票选项的插画。”
• “在概览地图上添加一张便签，写上战斗检查清单。”
• “游戏正在运行：在船长旁边生成两个火焰小鬼，并告诉我所有人的生命值。”

Larian 随游戏提供的 GM 战役也可以读取，因此可用作 NPC 模板库，供你复制使用。

要求

• Windows、《神界：原罪 2 — 终极版》（已在 Steam 版本 3.6.117.3735 上测试）
• uv 和 Python 3.11+
• .NET 8 运行时或更高版本（LSLib 的 Divine.exe 需要它）
• 仅实时层需要：Script Extender v58 或更高版本（已在 v60 上测试）

安装

git clone https://github.com/o-shabashov/dos2-gm-mcp
cd dos2-gm-mcp
uv sync
uv run dos2-gm-fetch-lslib

最后一条命令会将官方的 LSLib v1.20.4 版本下载到 ./lslib，并校验其 SHA-256。LSLib 是 Norbyte 在 MIT 许可证下开发的项目；本仓库不会重新分发它。

将其连接到 Claude Code：

claude mcp add dos2-gm --scope user -- uv --directory C:\path\to\dos2-gm-mcp run dos2-gm-mcp

或连接到其他 MCP 客户端：

{
  "mcpServers": {
    "dos2-gm": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\dos2-gm-mcp", "run", "dos2-gm-mcp"]
    }
  }
}

Claude Desktop 也可使用单文件软件包：从最新版本下载 dos2-gm-mcp.mcpb，打开后让助手调用一次 dos2_fetch_lslib。该软件包会将 LSLib 和备份保存在 ~/.dos2-gm-mcp 中。

系统会自动查找游戏文件夹和 Documents\Larian Studios\Divinity Original Sin 2 Definitive Edition（包括 Steam 库和已迁移的 Documents 文件夹）。可通过环境变量或项目根目录中的 config.json 覆盖这些路径：

变量	含义
DOS2GM_CAMPAIGNS	GMCampaigns 文件夹
DOS2GM_GAME	游戏文件夹
DOS2GM_DIVINE	Divine.exe 的路径
DOS2GM_BACKUPS	备份保存位置（默认值：./backups）
DOS2GM_MODS, DOS2GM_OSIRIS_DATA	游戏文档目录中的 Mods 和 Osiris Data 文件夹
DOS2GM_HOME	LSLib、备份、缓存和 config.json 的存放位置（默认值：项目根目录）

工具

campaign 参数接受战役名称、战役文件夹名称、UUID，或其中任意名称的一部分。

读取	返回内容
dos2_status	路径、游戏是否正在运行、战役列表
dos2_fetch_lslib	一次性设置：下载 LSLib 并校验其 SHA-256（与 uv run dos2-gm-fetch-lslib 相同）
dos2_campaign	元数据和附加组件、场景、带标记的地图、插图、模板、便笺、日志
dos2_scene	场景中的角色（名称、模板、位置、生命值、阵营、遭遇）、遭遇、便笺
dos2_templates、dos2_template	NPC 和物品模板，或某个模板的完整内容
dos2_find_templates	按名称、属性、技能、物品搜索所有战役中的模板
dos2_vignettes、dos2_notes	完整的插图和便笺
dos2_raw	任意战役文件的 LSX 内容，可使用 XPath 筛选
dos2_backups	战役的备份

写入	操作
dos2_put_npc_template	NPC 模板：从任意战役复制基础模板，设置名称、等级、阵营、属性和能力变更、天赋、技能、装备
dos2_put_item_template	物品模板
dos2_put_vignette	插图，可使用自定义图片或内置图片，并提供投票选项
dos2_put_note	在总览地图上添加便笺；编辑场景便笺的文本
dos2_put_journal	日志分类、章节和段落
dos2_scene_settings	场景氛围和音乐
dos2_campaign_meta	战役名称、描述、作者
dos2_addon、dos2_mod_install	将现成的 .pak 模组附加到战役，或将模组文件夹打包成 .pak 并附加
dos2_delete_template、dos2_delete_vignette、dos2_delete_note	删除
dos2_backup、dos2_restore	完整复制战役，或从任意备份恢复

实时（游戏运行时）	操作
dos2_live_status	查看已就绪项目：游戏、Script Extender、桥接 .pak、已附加的战役、桥接心跳
dos2_bridge_install、dos2_bridge_detach	将桥接打包为 Mods\DOS2GMBridge_….pak 并作为附加组件附加到战役，或将其分离
dos2_live_characters	查看当前关卡中的角色：GUID、名称、模板、属性、等级、生命值、阵营、位置
dos2_live_spawn	从根模板或 GM 模板生成角色，可放置在指定点或某人旁边
dos2_live_move、dos2_live_set、dos2_live_stage	传送；更改名称、等级、阵营；使角色离场并将其带回
dos2_live_lua	在游戏服务端运行 Lua（Ext、Osi）并获取返回值

安全

• 写入操作针对已关闭的战役：游戏已关闭，或停留在主菜单。游戏进程正在运行时，写入需要设置 allow_running=true。
• 每次写入前，都会将先前的文件复制到 backups\<campaign folder>\<time>-<operation>。dos2_restore 可还原其中任意备份。
• 已放置的 NPC 和遭遇存储在场景缓存中，在此处为只读；你可以在游戏中或通过实时层放置它们。
• dos2_live_lua 会在游戏中执行任意 Lua。请仅与可信任的助手一起使用。

实时层设置

1. 安装 Script Extender：将其 DXGI.dll 放在 DefEd\bin 中，与 EoCApp.exe 同目录。
2. 请助手为你的战役运行 dos2_bridge_install（游戏必须关闭）。该操作会构建桥接模组并将其添加到战役的附加组件中。
3. 以 GM 模式加载战役并调用 dos2_live_status。

桥接是一个服务端 Lua 模组（bridge/）。每个 tick，它都会从 Osiris Data/dos2gm-mcp 读取命令、执行命令并写入答案；没有套接字，也不会监听网络。多人游戏中，每位玩家都需要相同的 .pak 和 Script Extender，与任何 DOS2 模组的要求相同。

我们对 GM 模式的了解

给自行构建工具的人提供的说明；均已在游戏中验证。

• NPC 模板位于战役的 Eggs.lsf 中，类型为 GMExportCharacter。模板的第二个 Attribute 节点保存了游戏主持人对基础属性所做的调整。
• 装备槽位：0 头盔，1 胸甲，2 腿部，3 武器，4 盾牌，5 和 10 戒指，6 腰带，7 靴子，8 手套，9 护身符，12 角，15 及以上背包。
• 地图便签的 Type = 2，UI = 地图 UUID，NoteUIX/Y 使用地图像素坐标。场景便签的 Type = 0，附着在 LevelCache 中的一个隐形标记物品上。
• 模组的 meta.lsx 需要使用 Definitive Edition 的 PublishVersion（例如 909321303）。如果使用 1.0.0.0，游戏会将模组标记为适用于 Classic Edition，并拒绝加载。
• “Play campaign”会在战役副本上运行；准备好的战役不会受到影响。加载 GM 存档时会使用主菜单中的模组列表，因此也要在那里勾选你的附加模组。
• 战役或关卡加载期间，任何 Osi.* 调用都会导致 Script Extender 原生崩溃，即使 Ext.Osiris.IsCallable() 已返回 yes。只有游戏状态为 Running、Paused 或 GameMasterPause 时才调用。
• 游戏主持人暂停期间，Osiris 会延迟世界操作（放置、传送），直到解除暂停；创建角色后立即调用 SetOnStage 也会失效。桥接程序会为此类响应标记 applies_on_unpause。
• CombatRoundStarted 和 CharacterVitalityChanged 在 GM 模式下永远不会触发。请按回合统计轮数，并轮询生命值。
• 游戏主持人暂停期间，Script Extender 的控制台会拒绝命令；文件桥接程序仍可正常工作。
• 运行时，物品支持 CustomDisplayName、CustomDescription 和 CustomBookContent，这些值会传递给玩家。

测试

uv run python tests/bridge_test.py                    # the real bridge Lua in Lua 5.3 against stubs
uv run python tests/mcp_probe.py                      # MCP handshake, tool list and one call over stdio
uv run python tests/check_mapping.py                  # scenes of all campaigns, read-only
uv run python tests/smoke_read.py "My Campaign"       # read-only
uv run python tests/write_test.py <temp folder>       # writes into copies of campaigns

致谢

• Norbyte 开发的 LSLib 和 Script Extender 让这一切成为可能。
• Divinity: Original Sin 2 是 Larian Studios 制作的游戏。这是一款非官方粉丝工具，与 Larian Studios 无关，也未获其认可。截图展示的是游戏本身的美术内容。

许可证

MIT