DOS2 Game Master

dos2-gm-mcp

English · Русский

AI アシスタントが Divinity: Original Sin 2 – Definitive Edition のゲームマスターモードのキャンペーンを準備し、実行できる MCP サーバーです。

次の 2 つのレイヤーで動作します。

• キャンペーンファイル。 ディスク上の GM キャンペーンを読み込み、編集します。NPC とアイテムのテンプレート、独自のアートを使ったビネット、マップの付箋、ジャーナル、シーンの雰囲気、アドオン MOD などが対象です。書き込みの前には毎回バックアップを作成します。
• ゲームのライブ操作。 Norbyte's Script Extender 用の小さなブリッジ MOD を介して、実行中のゲームと通信します。レベル内のキャラクター一覧表示、テンプレートからの NPC 生成、移動、名前変更、レベルアップ、非表示と表示、ゲームサーバー上での任意の Lua の実行ができます。

GM の付箋がある概要マップ	商人と隠し場所のある酒場のシーン

依頼できること

• 「キャンペーン My Campaign に何があるか見せてください。シーン、テンプレート、ビネットを確認したいです。」
• 「魔女のアーキタイプをベースに、レベル 10 で、指定した 3 つのスキルを持つ Old Greta の NPC テンプレートを作成してください。アーキタイプは Larian のサンプルキャンペーンから使ってください。」
• 「この画像と 3 つの投票オプションを使って、ビネットを追加してください。」
• 「概要マップに、戦闘のチェックリストを付箋として追加してください。」
• 「ゲームは実行中です。船長の隣に火のインプを 2 体生成して、全員の体力を教えてください。」

Larian が同梱している GM キャンペーンも読み取れるため、コピーして使える NPC テンプレートのライブラリとして利用できます。

必要条件

• Windows、Divinity: Original Sin 2 – Definitive Edition（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 には、1 ファイルのバンドルも用意されています。最新リリースから dos2-gm-mcp.mcpb をダウンロードして開き、アシスタントに dos2_fetch_lslib を 1 回呼び出すよう依頼してください。このバンドルでは、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	ゲームの Documents 内にある 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	XPath フィルターを指定して、任意のキャンペーンファイルを LSX として取得
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 MOD をキャンペーンに追加するか、MOD フォルダーを .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 を実行するよう依頼します（ゲームは終了している必要があります）。ブリッジ MOD がビルドされ、キャンペーンのアドオンに追加されます。
3. GM モードでキャンペーンを読み込み、dos2_live_status を呼び出します。

ブリッジはサーバーサイドの Lua MOD（bridge/）です。ティックごとに Osiris Data/dos2gm-mcp からコマンドを読み取り、実行して結果を書き込みます。ソケットはなく、ネットワーク上で待ち受けるものもありません。マルチプレイヤーでは、他の DOS2 MOD と同様に、すべてのプレイヤーに同じ .pak と Script Extender が必要です。

GM モードについてわかったこと

独自のツールを作る方向けのメモです。すべてゲーム内で確認済みです。

• NPC テンプレートは、キャンペーンの Eggs.lsf に GMExportCharacter として格納されています。テンプレートの 2 番目の Attribute ノードには、ベースのステータスとの差分としてゲームマスターによる変更が保存されています。
• 装備スロット：0 はヘルメット、1 は胴体、2 は脚、3 は武器、4 は盾、5 と 10 は指輪、6 はベルト、7 はブーツ、8 は手袋、9 はアミュレット、12 は角、15 以降はバックパックです。
• マップの付箋は Type = 2、UI = マップ UUID、NoteUIX/Y = マップ上のピクセル座標です。シーンの付箋は Type = 0 で、LevelCache 内の非表示マーカーアイテムに紐づいています。
• MOD の meta.lsx には Definitive Edition の PublishVersion が必要です（例：909321303）。1.0.0.0 の場合、ゲームは MOD を Classic Edition 向けと判定し、読み込みを拒否します。
• 「キャンペーンをプレイ」はキャンペーンのコピー上で実行されるため、準備したキャンペーンは変更されません。GM セーブデータの読み込みにはメインメニューの MOD リストが使われるため、そこでアドオン MOD も有効にしてください。
• キャンペーンまたはレベルの読み込み中に Osi.* を呼び出すと、Ext.Osiris.IsCallable() がすでに true を返していても、Script Extender がネイティブレベルでクラッシュします。ゲームの状態が 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