npmパッケージ | Gua 日本語リファレンス

最初に選ぶもの

AIでゲームを操作するなら、デスクトップにはgui-mcp、ブラウザーにはgua-webmcpを使います。独自の画面やデータ処理を作る場合に、gua-value-toolsとgua-world-toolsを直接使います。

gui-mcp

デスクトップのゲームをAIから操作する

AIの要求をWebSocket経由でゲームへ送り、状態や操作結果を返す。Bunで動くコマンド。

MCPサーバー

gua-webmcp

ブラウザーのゲームをAIから操作する

Godot Web／Unity WebGLのページにAI向け操作を登録する。ゲームが用意した同じタブの接続口を使う。

ブラウザーWebMCP

gua-value-tools

ゲームから届く値を検証・比較する

型付きJSONを検証し、TypeScriptで使える値を返す。enumの候補や、順序を無視するsetの比較にも使う。

Valueツール

gua-world-tools

ゲーム世界の情報を扱う独自ツールを作る

公開された物体の一覧や検索結果を検証し、検索条件や読み取り専用ツールを組み立てる。

World Object Tree

ValueとWorldは何が違うか

共通点は、ゲームが公開したデータを安全に読み取るための型と検証を提供することです。扱う単位は異なります。Valueは「所持アイテムの集合」など1つの型付きの値、Worldは「どのドアがどこにあり、施錠されているか」など物体の一覧です。

Value: アイテムの順番が違っても同じ集合ts

import { parseValue, valuesEqual } from "gua-value-tools";

const actual = parseValue('{"type":"set","elementType":"string","value":["key","map"]}');
const expected = parseValue('{"type":"set","elementType":"string","value":["map","key"]}');
console.log(valuesEqual(actual, expected)); // true

2つのJSON文字列を渡すと、検証済みの値が得られ、valuesEqualはtrueを返します。setの比較では順番を無視します。listなら順番も比較します。

World: ドアの一覧と検索条件ts

import { parseWorldObjectTree, selectorFromArguments } from "gua-world-tools";

const tree = parseWorldObjectTree({
  schemaVersion: 1, sessionEpoch: 1, frameSequence: 12, revision: 2,
  scene: "level-1",
  objects: [{ id: "door", kind: "door", space: "world2d",
    position: { x: 4, y: 2 }, visibleToPlayer: true, active: true,
    agentExposure: "auto", state: { locked: false } }]
});
const selector = selectorFromArguments({ kind: "door", stateKey: "locked", stateValue: false });
console.log(tree.objects[0].id); // "door"
console.log(selector); // { kind: "door", state: { key: "locked", value: false } }

parseWorldObjectTreeは一覧の構造を検証し、selectorFromArgumentsは「施錠されていないドア」という検索条件を返します。この関数だけでは検索しません。条件をGuaWorldProvider.findWorldObjectsへ渡し、ゲーム側が許可した情報から結果を取得します。Worldのstateは通常のstring／number／boolean／nullを使い、Valueの型付きJSONではありません。

導入と組み合わせ

新規導入では、以下のコマンドでnpmのlatestタグが指す版を取得します。必要なパッケージだけを入れ、ゲーム側と版を揃えます。既存のゲームや再現用のMCP設定には、一致する具体的な版を指定してください。

デスクトップのAI接続（Bun）powershell

bunx gui-mcp@latest mcp

ゲームでGuaのWebSocketブリッジを起動し、AIクライアントにこのコマンドを登録します。既定の接続先はws://127.0.0.1:8765です。別の接続先はGUA_BRIDGE_URLで指定します。接続手順

ブラウザーのAI接続powershell

npm install gua-webmcp@latest

gua-webmcpはgua-value-toolsとgua-world-toolsを依存パッケージとして使います。通常の導入では別途追加する必要はありません。ゲームのWeb出力を先に読み込み、その接続口ができてからtoolを登録します。実験的なdocument.modelContext APIに対応したブラウザーが必要です。登録例

独自のデータ処理powershell

npm install gua-value-tools@latest gua-world-tools@latest

2つのライブラリはブラウザーでも使えます。自動でゲームに接続したり、シーンを収集したりはしません。ゲームや接続ツールから得たデータを渡します。gui-mcpは共通ライブラリをビルドへ組み込むため、実行のために別途インストールする必要はありません。

npm installは依存する版の範囲をpackage.jsonへ、解決した版をpackage-lock.jsonへ記録します。両方をcommitし、CIではnpm ciを使います。実行中のアプリが常時自動更新される設定ではありません。npm installの仕様

実装と公開パッケージ: gui-mcp · gua-webmcp · gua-value-tools · gua-world-tools. World API · Value API