WebゲームをブラウザのAIツールへ直接公開する

gui-mcpとの違い

Installとtool登録

npm install gua-webmcp@latest

新規導入向けの指定です。既存のゲームに合わせる版の選び方とlockfileはnpmパッケージガイドを参照してください。

import { createGodotWebBridge, registerGuaWebMcp } from "gua-webmcp";

const registration = await registerGuaWebMcp(createGodotWebBridge());
if (!registration.supported) console.info(registration.error);

game-input capabilityはtool登録時に一度だけ読み取るため、bridgeを作成する前にengine portが存在している必要があります。先にengine exportを読み込み、window.__guaGodotWebPortの生成を待ってから、引数なしのcreateGodotWebBridge()を呼びます。Unity WebGLではwindow.__guaUnityWebPortを待ち、引数なしのcreateUnityWebGlBridge()を呼びます。helperは既定のglobal port名を解決するため、port objectそのものは渡しません。

Godot Web Exportを準備する

1. 統合済みGodot addonを導入

   Godotの導入手順からReleaseのZIPを導入します。ZIPにはWeb向けのDebug／Release GDExtension WASMを含むaddons/guaが同梱されています。

2. Extension Supportを有効化

   Web export presetでExtension Supportを有効にし、single-thread variantを使います。Godotがweb.wasm32.single.debugまたはweb.wasm32.single.releaseを自動選択します。

3. HTTP(S)で配信

   生成HTMLをfileとして直接開かず、HTTP(S) serverから配信します。browser／export設定が要求する場合はcross-origin isolation headerも付けます。

Unity WebGL buildを準備する

Unityの導入手順からパッケージを用意します。ReleaseのUPMパッケージにはWebGL native libraryとGuaWebMcp.jslibが含まれます。WebGL経路は実験的です。初期bridgeはSemantic UI、World Object Tree、有効化済みgame-input capabilityを公開しますが、screenshot capabilityは公開しません。

公開される機能

Semantic UIの取得・操作・待機、read-onlyのWorld Object Tree、engine input pumpが初期化済みのSemantic Game Action／Raw Inputだけをtool登録します。現在のReleaseに含まれるGodot／Unityの組み込みportはscreenshot capabilityを公開しません。互換性のある描画frame readbackを実装した独自のGuaInPagePortだけが明示的に追加できます。操作はenqueue受理ではなく、同じrequest IDのhost完了まで待ちます。

Securityとlifetime

browser portは常にhostのPlayer投影とPlayer action認可を使います。local Debug Inspectorを有効にしてもprivate dataはWebMCPへ出ず、toolからDebugへ昇格できません。ゲーム入力も、hostがPlayer向けSemantic／Raw capabilityを個別許可するまで既定拒否です。各tabがtool登録とinput sessionを所有し、timeout、caller cancel、unregister、engine shutdownでpage-owned inputを解放します。

Player向けの追加観測値を読む

observe_v1がある場合、gua-webmcpはsame-page engine portからget_observe_snapshot、subscribe_observations、poll_observations、unsubscribe_observationsを提供します。値はゲーム側が登録し、Player projectionに従います。再接続、detach、gapでは新しい購読が必要です。Observeのライフサイクルを参照してください。

入力値metadataを取得する

エンジンがsemantic_game_input_metadata_v1を公開した場合、get_game_input_actions_v2／find_game_input_actions_v2で上限付きvalueSchema／examplesを明示的に取得します。Player入力の認可や確認を省略しません。入力metadataの説明を参照してください。

物理queryの境界

組み込みGodot Web／Unity WebGL port経由の権限付きspatial queryは非対応です。Worldの半径検索は意味的snapshotの検索で、エンジンのraycastやoverlapではありません。物理queryには明示的に認可したnative Testing／Debug providerを使います。World検索と物理queryの違いを参照してください。