From 73405e9f13cece0195287c49a4ff3ae039d18f55 Mon Sep 17 00:00:00 2001 From: link1345 Date: Tue, 6 Oct 2026 09:32:48 +0900 Subject: [PATCH] docs: use latest packages in ordinary install guides --- src/pages/docs/dotnet-packages.astro | 3 ++- src/pages/docs/github-actions.astro | 8 ++++---- src/pages/docs/gua-runtime.astro | 2 +- src/pages/docs/npm-packages.astro | 9 +++++---- src/pages/docs/runtime-adapters.astro | 2 +- src/pages/docs/value.astro | 2 +- src/pages/godot/testing.astro | 16 ++++++++-------- src/pages/godot/ui.astro | 4 ++-- src/pages/inspector/index.astro | 2 +- src/pages/ja/docs/dotnet-packages.astro | 3 ++- src/pages/ja/docs/github-actions.astro | 8 ++++---- src/pages/ja/docs/gua-runtime.astro | 2 +- src/pages/ja/docs/npm-packages.astro | 9 +++++---- src/pages/ja/docs/runtime-adapters.astro | 2 +- src/pages/ja/docs/value.astro | 2 +- src/pages/ja/godot/testing.astro | 16 ++++++++-------- src/pages/ja/godot/ui.astro | 4 ++-- src/pages/ja/inspector/index.astro | 2 +- src/pages/ja/mcp/index.astro | 2 +- src/pages/ja/recording/index.astro | 2 +- src/pages/ja/unity/testing.astro | 14 +++++++------- src/pages/ja/unity/ui.astro | 4 ++-- src/pages/ja/visual-testing/index.astro | 2 +- src/pages/ja/webmcp/index.astro | 2 +- src/pages/ja/world-object-tree/index.astro | 2 +- src/pages/mcp/index.astro | 2 +- src/pages/recording/index.astro | 2 +- src/pages/unity/testing.astro | 12 ++++++------ src/pages/unity/ui.astro | 2 +- src/pages/visual-testing/index.astro | 2 +- src/pages/webmcp/index.astro | 2 +- src/pages/world-object-tree/index.astro | 2 +- 32 files changed, 76 insertions(+), 72 deletions(-) diff --git a/src/pages/docs/dotnet-packages.astro b/src/pages/docs/dotnet-packages.astro index 302a181..0629bb6 100644 --- a/src/pages/docs/dotnet-packages.astro +++ b/src/pages/docs/dotnet-packages.astro @@ -2,7 +2,8 @@ import DocPage from '../../components/DocPage.astro'; import CodeBlock from '../../components/CodeBlock.astro'; import Callout from '../../components/Callout.astro'; --- -

Install

The examples pin 1.1.0. Keep the game integration and all Gua packages in one project on the same version. Visual, Snapshots, and Recording are independent opt-ins.

+

Install

Keep the game integration and all Gua packages in one project on the same version. Visual, Snapshots, and Recording are independent opt-ins.

+

Check the installed version

Without a version argument, the command selects the latest compatible stable version from the configured NuGet feeds when it runs. A concrete version is recorded in .csproj, or Directory.Packages.props with central management. Later builds do not continually update it to the latest release. Commit those files and align the game integration and related Gua packages. For an existing game or CI, specify its actual version with --version. Official CLI specification

NuGet: Core · Testing · Testing.Godot · Testing.Unity · Runtime · Testing.Visual · Testing.Snapshots · Testing.Recording

Choose a package

diff --git a/src/pages/docs/github-actions.astro b/src/pages/docs/github-actions.astro index 6b19103..2d072c8 100644 --- a/src/pages/docs/github-actions.astro +++ b/src/pages/docs/github-actions.astro @@ -4,9 +4,9 @@ import CodeBlock from '../../components/CodeBlock.astro'; import Callout from '../../components/Callout.astro'; --- -

Use the published v3.2 actions. The action version (@v3.2), Gua version (for example gua-v1.1.0), and Godot/Unity version are independent selections.

 +

Use the published v3.2 actions. The action version (@v3.2), Gua version (for example gua-v1.1.1), and Godot/Unity version are independent selections.

 -

The Godot action downloads gua-godot-addon-*.zip and the Unity workflow downloads com.link1345.gua-*.tgz from the selected Gua release. The examples below pin gua-v1.1.0; use 1.1.0 NuGet packages in the test project too. See Godot or Unity for game installation. Omitting the tag selects the latest stable release containing the required package. Pin the tag for reproducible CI.

 +

The Godot action downloads gua-godot-addon-*.zip and the Unity workflow downloads com.link1345.gua-*.tgz from the selected Gua release. The examples below pin gua-v1.1.1; use 1.1.1 NuGet packages in the test project too. See Godot or Unity for game installation. Omitting the tag selects the latest stable release containing the required package. Pin the tag for reproducible CI.

Godot 4.7

The Godot composite action downloads the official Godot build matching its runner, links the released Gua addon, exports GODOT_EXECUTABLE, prepares project imports, and runs the external Gua.Testing.Godot test project.

+ gua-plugin-tag: gua-v1.1.1`} />
test-project (required)

The .csproj that references Gua.Testing.Godot.

project-path

Godot project path; default game.

godot-version / godot-status

Default 4.7 and stable.

test-logger

Default trx;LogFileName=godot.trx.

The outputs are godot-executable and addon-path. Component actions remain available as gua-project/gua-tester/setup-godot@v3.2 and gua-project/gua-tester/link-gua-gdscript-addon@v3.2.

@@ -37,7 +37,7 @@ import Callout from '../../components/Callout.astro'; artifact-key: game platform: LinuxX64 unity-version: auto - gua-tag: gua-v1.1.0 + gua-tag: gua-v1.1.1 secrets: UNITY_EMAIL: \${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: \${{ secrets.UNITY_PASSWORD }} diff --git a/src/pages/docs/gua-runtime.astro b/src/pages/docs/gua-runtime.astro index cda9c6a..838e9c5 100644 --- a/src/pages/docs/gua-runtime.astro +++ b/src/pages/docs/gua-runtime.astro @@ -16,7 +16,7 @@ import Callout from '../../components/Callout.astro';
Inspector / MCP / Testsobserve and request↔native gua_runtimestate, queues, bridge↔Gua.Runtimemanaged API↔Custom adapterengine translation↔Game UIreal widgets
Figure 1: Gua.Runtime is the managed boundary between the protocol runtime and engine-specific UI APIs.

Install and deploy

- +

Align the game integration and related Gua package versions. See version management for recording and pinning the result.

The package targets net10.0 and netstandard2.1. Use matching native libraries for the target OS/CPU: gua.dll/gua_runtime.dll on Windows, libgua.so/libgua_runtime.so on Linux, or libgua.dylib/libgua_runtime.dylib on macOS. Missing or mismatched libraries produce an explicit load error in the constructor.

One adapter frame

diff --git a/src/pages/docs/npm-packages.astro b/src/pages/docs/npm-packages.astro index 6368344..49d2adb 100644 --- a/src/pages/docs/npm-packages.astro +++ b/src/pages/docs/npm-packages.astro @@ -18,12 +18,13 @@ import Callout from '../../components/Callout.astro';

parseWorldObjectTree validates the tree; selectorFromArguments builds an “unlocked door” selector. It does not execute a search. Pass the selector to GuaWorldProvider.findWorldObjects to query the host-approved view. World state uses ordinary string/number/boolean/null values, not typed Value JSON.

World proximity searches use published coordinates. Physics queries such as raycasts are separate. gua-world-tools also supplies request types for them, but the game performs physics calculations and authorizes access. Details

Install and combine

-

These examples use the 1.1.0 APIs. Pin the same Gua version as the game integration. Install only the packages your setup needs.

- +

For a new setup, these commands request the current npm latest tag. Install only what you need and align the result with the game integration. For an existing game or reproducible MCP setup, use a matching explicit version.

+

Start the game’s Gua WebSocket bridge and register this command in the AI client. The default endpoint is ws://127.0.0.1:8765; use GUA_BRIDGE_URL to change it. Connection steps

- +

gua-webmcp depends on gua-value-tools and gua-world-tools; a normal installation brings them in. Load the exported game first, wait for its port, then register tools. The browser must support the experimental document.modelContext API. Registration example

- +

Both libraries work in browsers. They do not connect to a game or collect a scene automatically; pass data obtained from the game or a connector. gui-mcp bundles the shared libraries, so running it does not require separate installations.

+

npm install records a dependency range in package.json and resolved versions in package-lock.json. Commit both; use npm ci in CI. It does not make a running app continuously update itself. npm install specification

Implementation and published packages: gui-mcp · gua-webmcp · gua-value-tools · gua-world-tools. World API · Value API

 diff --git a/src/pages/docs/runtime-adapters.astro b/src/pages/docs/runtime-adapters.astro index ad09dca..449e1b4 100644 --- a/src/pages/docs/runtime-adapters.astro +++ b/src/pages/docs/runtime-adapters.astro @@ -12,7 +12,7 @@ import CodeBlock from '../../components/CodeBlock.astro';
GoalAddUse it for
Write ordinary semantic UI testsGua.Testing + engine hostVisibility, enabled state, text, values, and state transitions after actions.
Gua.Testing.SnapshotsSemantic UI/World JSON baseline comparisonOptional external .NET tests
Gua.Testing.VisualPNG baseline comparison and diff artifacts, shared by Godot and UnityOptional external .NET tests
Gua.Testing.RecordingSemantic action recording and request-correlated replay, shared by Godot and UnityOptional external .NET tests
-

The game needs addons/gua with matching native libraries. See Godot installation for the file source and 1.1.0 setup.

 +

The game needs addons/gua with matching native libraries. See Godot installation for the file source and setup.

Godot public types

diff --git a/src/pages/docs/value.astro b/src/pages/docs/value.astro index ca2146f..cebbbef 100644 --- a/src/pages/docs/value.astro +++ b/src/pages/docs/value.astro @@ -8,7 +8,7 @@ import Callout from '../../components/Callout.astro';

The game registers values outside the standard UI as Observe values: additional published observations. gua-value-tools handles received values; it does not register them or connect to the game. Register observations · Combine npm packages

Install the npm package

- +

This is for a new setup. See npm packages for aligning an existing game and recording a lockfile.

gua-value-tools provides TypeScript types and validation, JSON parsing/serialization, enum catalogs, and semantic equality.

An enum is a value chosen from named alternatives. If a boss phase is First or Second, register those names in an EnumCatalog. Validation rejects unknown members or the wrong type.

-

1. Install the required NuGet packages

External Godot tests require all three packages: Gua.Core, Gua.Testing, and Gua.Testing.Godot. Run these commands in the test project directory to resolve the 1.1.0 packages, then commit the versions written to the project.

1. Install the required NuGet packages

External Godot tests require all three packages: Gua.Core, Gua.Testing, and Gua.Testing.Godot. Run these commands in the test project directory to resolve the latest compatible stable packages, then commit the versions written to the project.

Align the game integration and related Gua package versions. See version management for recording and pinning the result.

With GitHub Actions, pass artifacts/gua/** to actions/upload-artifact after the test step so evidence remains available from a failed run.

-

Run tests with GitHub Actions

The example below installs the gua-v1.1.0 add-on. Use matching 1.1.0 NuGet packages in the test project. See CI setup and version selection.

The public gua-project/gua-tester/godot@v3.2 action installs the official Godot build matching its runner, links the selected released Gua add-on, sets GODOT_EXECUTABLE, and runs dotnet test.

Run tests with GitHub Actions

The example below installs the gua-v1.1.1 add-on. Use matching 1.1.1 NuGet packages in the test project. See CI setup and version selection.

The public gua-project/gua-tester/godot@v3.2 action installs the official Godot build matching its runner, links the selected released Gua add-on, sets GODOT_EXECUTABLE, and runs dotnet test.

Wait for actionable UI

Gua.Testing locators resolve a current strict single match when used. Actions wait for visible/enabled state and the advertised action, then correlated host completion. Multiple matches fail immediately. Resolution, enqueue, and completion share one timeout budget; rejected enqueue and host failure are not automatically retried.

ResolveAsync waits for the next node to exist; add the state assertion your test requires. Locator API and timeout rules.

-

Compare semantic state without pixels

Add Gua.Testing.Snapshots at 1.1.0 to compare UI IDs, hierarchy, text, values, and state against reviewed JSON baselines. It works with host.Context, including a headless host. Add Gua.Testing.Visual separately when rendered pixels matter. Installation, masks, and baseline update example.

- +

Compare semantic state without pixels

Add Gua.Testing.Snapshots to compare UI IDs, hierarchy, text, values, and state against reviewed JSON baselines. It works with host.Context, including a headless host. Add Gua.Testing.Visual separately when rendered pixels matter. Installation, masks, and baseline update example.

+

Save test evidence with Gua.Testing Trace

Trace belongs to Gua.Testing; no extra Trace package is needed. Enable it for a test scope, complete it with the test's actual outcome, and create an offline HTML report at a new output path.

Trace records evidence; it does not replay the flow or change its result. Capture UI/World or Observe values explicitly when required, and handle sensitive data before recording. Trace capture APIs · Open a saved Trace in Inspector.

diff --git a/src/pages/godot/ui.astro b/src/pages/godot/ui.astro index e1ae996..fedff23 100644 --- a/src/pages/godot/ui.astro +++ b/src/pages/godot/ui.astro @@ -17,8 +17,8 @@ func _process(_delta: float) -> void: ui.update("title")`; --- -

Download gua-godot-addon-v1.1.0.zip from the Gua 1.1.0 release assets. The ZIP contains native libraries for Windows x64, Linux x64, macOS x64/arm64, and Debug/Release WASM for Godot Web. Copy addons/gua into the game and add matching-version NuGet packages to the external test project. NuGet alone does not install the game add-on.

 -

Install the packaged add-on

  1. Open the Gua 1.1.0 release

    Download the Godot ZIP from the release assets and extract it.

  2. Copy addons/gua

    Download gua-godot-addon-v<version>.zip from the latest Gua release assets. The ZIP contains native libraries for Windows x64, Linux x64, macOS x64/arm64, and Debug/Release WASM for Godot Web. Copy addons/gua into the game and add matching-version NuGet packages to the external test project. NuGet alone does not install the game add-on.

    <version> means the actual version shown in Assets; for 1.1.1, the file name contains 1.1.1. For an existing test setup, choose the release matching that setup.

    +

    Install the packaged add-on

    1. Open the latest Gua release

      Download the Godot ZIP from the release assets and extract it.

    2. Copy addons/gua -

      Download the Windows installer Gua.Inspector_*_x64-setup.exe or MSI from the Gua 1.1.0 release assets, install it, and launch Gua Inspector.

      Run and connect

      1. Launch Inspector

        Open the installed Gua Inspector application.

      2. Start the in-game bridge

        Run the Gua-integrated game with its WebSocket bridge enabled.

      3. Enter the connection URL

        The default is ws://127.0.0.1:8765. Match the port configured by the game.

      +

      Download the Windows installer Gua.Inspector_*_x64-setup.exe or MSI from the latest Gua release assets, install it, and launch Gua Inspector.

      Run and connect

      1. Launch Inspector

        Open the installed Gua Inspector application.

      2. Start the in-game bridge

        Run the Gua-integrated game with its WebSocket bridge enabled.

      3. Enter the connection URL

        The default is ws://127.0.0.1:8765. Match the port configured by the game.

      Run from source (development)

      Run the following commands in the Gua repository checked out at gua-v1.1.0. Browser development requires Bun.

      1. Install repository dependencies
      2. Start browser Inspector
      3. Start the in-game bridge

        The Godot sample starts its bridge inside the game process. Use the sample bridge when you only need to exercise the protocol.

      4. Connect to the URL
      diff --git a/src/pages/ja/docs/dotnet-packages.astro b/src/pages/ja/docs/dotnet-packages.astro index d814633..52edc5e 100644 --- a/src/pages/ja/docs/dotnet-packages.astro +++ b/src/pages/ja/docs/dotnet-packages.astro @@ -2,7 +2,8 @@ import DocPage from '../../../components/DocPage.astro'; import CodeBlock from '../../../components/CodeBlock.astro'; import Callout from '../../../components/Callout.astro'; --- -

      インストール

      例は1.1.0に固定しています。ゲーム側の導入物とテストプロジェクトのGuaパッケージは同じバージョンに合わせます。Visual、Snapshots、Recordingは必要に応じて追加します。

      +

      インストール

      ゲーム側の導入物とテストプロジェクトのGuaパッケージは同じバージョンに合わせます。Visual、Snapshots、Recordingは必要に応じて追加します。

      +

      導入したバージョンを確認する

      版指定なしのコマンドは、設定済みのNuGetソースから互換性のある最新安定版を実行時に選びます。具体的な版は.csprojへ、中央管理ではDirectory.Packages.propsへ記録されます。後日のビルドだけで常に最新版へ更新されるわけではありません。記録したファイルをcommitし、ゲーム側と関連するGuaパッケージの版を揃えます。既存のゲームやCIに合わせる場合は--versionで実際の版を指定してください。公式CLI仕様

      NuGet: Core · Testing · Testing.Godot · Testing.Unity · Runtime · Testing.Visual · Testing.Snapshots · Testing.Recording

      どのパッケージを選ぶか

Type / settingContract
diff --git a/src/pages/ja/docs/github-actions.astro b/src/pages/ja/docs/github-actions.astro index ccbaa60..9dd3241 100644 --- a/src/pages/ja/docs/github-actions.astro +++ b/src/pages/ja/docs/github-actions.astro @@ -4,9 +4,9 @@ import CodeBlock from '../../../components/CodeBlock.astro'; import Callout from '../../../components/Callout.astro'; --- -

公開済みv3.2を使います。Actionのバージョン（@v3.2）、Guaのバージョン（例：gua-v1.1.0）、Godot／Unityのバージョンは別々に指定します。

 +

公開済みv3.2を使います。Actionのバージョン（@v3.2）、Guaのバージョン（例：gua-v1.1.1）、Godot／Unityのバージョンは別々に指定します。

 -

Godot Actionは選択したGua Releaseのgua-godot-addon-*.zipを、Unity workflowはcom.link1345.gua-*.tgzを取得します。以下の例はgua-v1.1.0を指定し、テストプロジェクトのNuGetも1.1.0に揃えます。ゲームへの導入手順はGodot／Unityを参照してください。タグを省略すると、必要なパッケージを含む最新のstable Releaseが選択されます。再現性のあるCIではタグを明示します。

 +

Godot Actionは選択したGua Releaseのgua-godot-addon-*.zipを、Unity workflowはcom.link1345.gua-*.tgzを取得します。以下の例はgua-v1.1.1を指定し、テストプロジェクトのNuGetも1.1.1に揃えます。ゲームへの導入手順はGodot／Unityを参照してください。タグを省略すると、必要なパッケージを含む最新のstable Releaseが選択されます。再現性のあるCIではタグを明示します。

Godot 4.7

Godot composite Actionはrunnerに合うGodot公式版を取得し、配布済みGua addonを配置してGODOT_EXECUTABLEを設定します。project import後、外部Gua.Testing.Godotテストを実行します。

+ gua-plugin-tag: gua-v1.1.1`} />
test-project（必須）

Gua.Testing.Godotを参照する.csprojです。

project-path

Godot projectのパス。既定値はgameです。

godot-version / godot-status

既定値は4.7とstableです。

test-logger

既定値はtrx;LogFileName=godot.trxです。

出力はgodot-executableとaddon-pathです。構成Actionのgua-project/gua-tester/setup-godot@v3.2とgua-project/gua-tester/link-gua-gdscript-addon@v3.2も個別に利用できます。

@@ -37,7 +37,7 @@ import Callout from '../../../components/Callout.astro'; artifact-key: game platform: LinuxX64 unity-version: auto - gua-tag: gua-v1.1.0 + gua-tag: gua-v1.1.1 secrets: UNITY_EMAIL: \${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: \${{ secrets.UNITY_PASSWORD }} diff --git a/src/pages/ja/docs/gua-runtime.astro b/src/pages/ja/docs/gua-runtime.astro index 0979eb0..44b1c52 100644 --- a/src/pages/ja/docs/gua-runtime.astro +++ b/src/pages/ja/docs/gua-runtime.astro @@ -19,7 +19,7 @@ import Callout from '../../../components/Callout.astro';

導入とnative library

- +

ゲーム側と関連Guaパッケージの版を揃えます。取得後の版の記録・固定はバージョンの管理を参照してください。

Gua.Runtimeはnet10.0とnetstandard2.1を対象にします。実行時には対象OS／CPUと一致するnativeライブラリを使います。Windowsはgua.dll／gua_runtime.dll、Linuxはlibgua.so／libgua_runtime.so、macOSはlibgua.dylib／libgua_runtime.dylibです。不一致や欠落はconstructorで明示的なload errorになります。

adapterの1 frame

diff --git a/src/pages/ja/docs/npm-packages.astro b/src/pages/ja/docs/npm-packages.astro index 826b30a..c755d3c 100644 --- a/src/pages/ja/docs/npm-packages.astro +++ b/src/pages/ja/docs/npm-packages.astro @@ -18,12 +18,13 @@ import Callout from '../../../components/Callout.astro';

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

Worldの近傍検索は公開された座標を使います。レイを飛ばして衝突を調べる物理照会は別の機能です。gua-world-toolsはその要求形式も提供しますが、物理計算や権限判断はゲーム側が行います。 詳しい違い

導入と組み合わせ

-

以下は1.1.0のAPIを使う例です。ゲーム側パッケージと同じGuaバージョンを指定します。各パッケージをすべて入れる必要はありません。

- +

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

+

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

- +

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

- +

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

 diff --git a/src/pages/ja/docs/runtime-adapters.astro b/src/pages/ja/docs/runtime-adapters.astro index 9c6a241..aac6400 100644 --- a/src/pages/ja/docs/runtime-adapters.astro +++ b/src/pages/ja/docs/runtime-adapters.astro @@ -12,7 +12,7 @@ import CodeBlock from '../../../components/CodeBlock.astro';
やりたいこと追加するパッケージ使う場面
通常のSemantic UIテストGua.Testing + engine host表示、活性状態、text、value、操作後の状態遷移を検証。
Gua.Testing.SnapshotsUI／Worldの意味的JSON baseline比較追加の外部.NETテスト
Gua.Testing.VisualPNG baseline比較と差分artifact。Godot・Unity共通必要な外部.NETテスト
Gua.Testing.RecordingSemantic操作の記録とrequest相関付きReplay。Godot・Unity共通必要な外部.NETテスト
-

ゲームにはnativeライブラリを含むaddons/guaが必要です。ファイルの入手先と1.1.0の導入方法はGodotの導入手順を参照してください。

 +

ゲームにはnativeライブラリを含むaddons/guaが必要です。ファイルの入手先と導入方法はGodotの導入手順を参照してください。

Godot公開型

diff --git a/src/pages/ja/docs/value.astro b/src/pages/ja/docs/value.astro index 65a4f25..70686d9 100644 --- a/src/pages/ja/docs/value.astro +++ b/src/pages/ja/docs/value.astro @@ -8,7 +8,7 @@ import Callout from '../../../components/Callout.astro';

ゲーム側では、画面に直接出ていない値をObserveとして登録します。これは「追加の観測値を公開する」機能です。gua-value-toolsは受け取った値を扱い、ゲームへの登録や接続は行いません。Observeの登録・npmパッケージの組み合わせ

パッケージを導入する

- +

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

gua-value-toolsはTypeScriptの型と検証、JSON入出力、enum catalog、意味的な等価比較を提供します。

enumは、決められた候補から選ぶ値です。例えばボスの段階がFirstかSecondのどちらかなら、その候補をEnumCatalogへ登録します。未知の候補や別の型は検証で拒否されます。

-

1. 必須NuGetパッケージを入れる

Godotの外部テストにはGua.Core、Gua.Testing、Gua.Testing.Godotの3パッケージが必要です。テストプロジェクトのディレクトリで次を実行して1.1.0を解決し、projectへ書き込まれたversionをcommitします。

1. 必須NuGetパッケージを入れる

Godotの外部テストにはGua.Core、Gua.Testing、Gua.Testing.Godotの3パッケージが必要です。テストプロジェクトのディレクトリで次を実行して互換性のある最新安定版を取得し、projectへ書き込まれたversionをcommitします。

ゲーム側と関連Guaパッケージの版を揃えます。取得後の版の記録・固定はバージョンの管理を参照してください。

GitHub Actionsを使う場合は、テスト後にartifacts/gua/**をactions/upload-artifactへ渡すと、失敗した実行から診断ファイルを取得できます。

-

GitHub Actionsで実行する

以下の例はgua-v1.1.0のアドオンを導入します。テストプロジェクトのNuGetも1.1.0に揃えます。CIの導入方法とバージョン指定を参照してください。

公開Actionのgua-project/gua-tester/godot@v3.2を使うと、runnerに合うGodot公式版の導入、選択したReleaseのGuaアドオンの配置、GODOT_EXECUTABLEの設定、dotnet testの実行をまとめて行えます。

GitHub Actionsで実行する

以下の例はgua-v1.1.1のアドオンを導入します。テストプロジェクトのNuGetも1.1.1に揃えます。CIの導入方法とバージョン指定を参照してください。

公開Actionのgua-project/gua-tester/godot@v3.2を使うと、runnerに合うGodot公式版の導入、選択したReleaseのGuaアドオンの配置、GODOT_EXECUTABLEの設定、dotnet testの実行をまとめて行えます。

操作できるUIを待つ

Gua.Testingのlocatorは使用時に最新のtreeから厳密な単一一致を解決します。actionはvisible／enabledと対応actionを待ち、requestIdに対応するhost completionを待ちます。複数一致は即時失敗です。解決・enqueue・completionは同じtimeoutを共有し、enqueue拒否やhost失敗は自動再試行しません。

ResolveAsyncは次のnodeの存在を待ちます。テストで必要な状態のassertionも加えます。locator APIとtimeout規則。

-

ピクセルを使わず意味的な状態を比較する

Gua.Testing.Snapshots 1.1.0を追加すると、UIのID、階層、text、value、stateをreview済みJSON baselineと比較できます。headlessでもhost.Contextで使えます。描画結果も調べる場合はGua.Testing.Visualを別途追加します。導入・mask・baseline更新の例を参照してください。

- +

ピクセルを使わず意味的な状態を比較する

Gua.Testing.Snapshotsを追加すると、UIのID、階層、text、value、stateをreview済みJSON baselineと比較できます。headlessでもhost.Contextで使えます。描画結果も調べる場合はGua.Testing.Visualを別途追加します。導入・mask・baseline更新の例を参照してください。

+

Gua.Testing Traceでテストの証拠を保存する

TraceはGua.Testingの機能です。追加のTraceパッケージは不要です。テストscopeに設定し、実際の結果で完了させ、新しい出力先にoffline HTML reportを生成します。

Traceは証拠を記録し、flowの再生や結果の変更はしません。UI／WorldやObserve値が必要な場合は明示的に取得し、記録前に機密情報の扱いを決めます。Traceの取得API・Inspectorで保存済みTraceを開くを参照してください。

diff --git a/src/pages/ja/godot/ui.astro b/src/pages/ja/godot/ui.astro index 1e9f64f..c43082f 100644 --- a/src/pages/ja/godot/ui.astro +++ b/src/pages/ja/godot/ui.astro @@ -17,8 +17,8 @@ func _process(_delta: float) -> void: ui.update("title")`; --- -

Gua 1.1.0のRelease Assetsからgua-godot-addon-v1.1.0.zipを取得します。ZIPにはWindows x64、Linux x64、macOS x64／arm64のnative libraryと、Godot Web用のDebug／Release WASMが含まれます。ゲームにはaddons/guaを配置し、外部テストには同じバージョンのNuGetパッケージを追加します。NuGetだけではゲーム側アドオンは導入されません。

 -

配布済みアドオンを入れる

  1. Gua 1.1.0のReleaseを開く

    AssetsからGodot用ZIPをダウンロードして展開します。

  2. addons/guaをコピー

    最新GuaのRelease Assetsからgua-godot-addon-v<version>.zipを取得します。ZIPにはWindows x64、Linux x64、macOS x64／arm64のnative libraryと、Godot Web用のDebug／Release WASMが含まれます。ゲームにはaddons/guaを配置し、外部テストには同じバージョンのNuGetパッケージを追加します。NuGetだけではゲーム側アドオンは導入されません。

    <version>はAssetsに表示された実際の版です。例えば1.1.1なら、ファイル名にも1.1.1が入ります。既存のテスト環境では、その環境と同じ版のReleaseを選びます。

    +

    配布済みアドオンを入れる

    1. 最新GuaのReleaseを開く

      AssetsからGodot用ZIPをダウンロードして展開します。

    2. addons/guaをコピー -

      Gua 1.1.0のRelease AssetsからWindowsインストーラーGua.Inspector_*_x64-setup.exeまたはMSIを取得し、インストールして起動します。

      起動と接続

      1. Inspectorを起動

        インストールしたGua Inspectorを開きます。

      2. ゲーム側ブリッジを起動

        Guaを導入したゲームを起動し、WebSocketブリッジを有効にします。

      3. 接続先URLを入力

        既定の接続先はws://127.0.0.1:8765です。ゲーム側で変更したポートに合わせて接続します。

      +

      最新GuaのRelease AssetsからWindowsインストーラーGua.Inspector_*_x64-setup.exeまたはMSIを取得し、インストールして起動します。

      起動と接続

      1. Inspectorを起動

        インストールしたGua Inspectorを開きます。

      2. ゲーム側ブリッジを起動

        Guaを導入したゲームを起動し、WebSocketブリッジを有効にします。

      3. 接続先URLを入力

        既定の接続先はws://127.0.0.1:8765です。ゲーム側で変更したポートに合わせて接続します。

      ソースから起動する（開発用）

      gua-v1.1.0のGuaリポジトリで以下を実行します。ブラウザー版の開発にはBunが必要です。

      1. Guaリポジトリで依存関係を入れる
      2. ブラウザー版Inspectorを起動
      3. ゲーム側ブリッジを起動

        Godotサンプルはゲームプロセス内でブリッジを開始します。プロトコルだけ試す場合はサンプルブリッジも使えます。

      4. URLを入力して接続
      diff --git a/src/pages/ja/mcp/index.astro b/src/pages/ja/mcp/index.astro index 72617e3..79ca6b7 100644 --- a/src/pages/ja/mcp/index.astro +++ b/src/pages/ja/mcp/index.astro @@ -4,7 +4,7 @@ const config = `{ "mcpServers": { "gua": { "command": "bunx", - "args": ["gui-mcp@1.1.0", "mcp"], + "args": ["gui-mcp@latest", "mcp"], "env": { "GUA_BRIDGE_URL": "ws://127.0.0.1:8765", "GUA_ARTIFACT_DIR": ".gua" diff --git a/src/pages/ja/recording/index.astro b/src/pages/ja/recording/index.astro index bb61dd6..4dda192 100644 --- a/src/pages/ja/recording/index.astro +++ b/src/pages/ja/recording/index.astro @@ -19,7 +19,7 @@ import Callout from '../../../components/Callout.astro';

      導入

      - +

      ゲーム側と関連Guaパッケージの版を揃えます。取得後の版の記録・固定はバージョンの管理を参照してください。

      操作を記録する

      1. テストパッケージを追加する

      -

      Gua.Testing.UnityはNuGetで公開されています。次のコマンドは1.1.0を解決します。projectへ書き込まれたversionをcommitし、3つのGuaパッケージを同じversion系列へ揃えてください。

      - +

      Gua.Testing.UnityはNuGetで公開されています。次のコマンドは互換性のある最新安定版を取得します。projectへ書き込まれたversionをcommitし、3つのGuaパッケージを同じversion系列へ揃えてください。

      +

      ゲーム側と関連Guaパッケージの版を揃えます。取得後の版の記録・固定はバージョンの管理を参照してください。

      2. PlayerまたはEditorを起動する

      操作できるUIを待つ

      Gua.Testingのlocatorは使用時に最新のtreeから厳密な単一一致を解決します。actionはvisible／enabledと対応actionを待ち、requestIdに対応するhost completionを待ちます。複数一致は即時失敗です。解決・enqueue・completionは同じtimeoutを共有し、enqueue拒否やhost失敗は自動再試行しません。

      ResolveAsyncは次のnodeの存在を待ちます。テストで必要な状態のassertionも加えます。locator APIとtimeout規則。

      -

      ピクセルを使わず意味的な状態を比較する

      Gua.Testing.Snapshots 1.1.0を追加すると、UIのID、階層、text、value、stateをreview済みJSON baselineと比較できます。headlessでもhost.Contextで使えます。描画結果も調べる場合はGua.Testing.Visualを別途追加します。導入・mask・baseline更新の例を参照してください。

      - +

      ピクセルを使わず意味的な状態を比較する

      Gua.Testing.Snapshotsを追加すると、UIのID、階層、text、value、stateをreview済みJSON baselineと比較できます。headlessでもhost.Contextで使えます。描画結果も調べる場合はGua.Testing.Visualを別途追加します。導入・mask・baseline更新の例を参照してください。

      +

      Gua.Testing Traceでテストの証拠を保存する

      TraceはGua.Testingの機能です。追加のTraceパッケージは不要です。テストscopeに設定し、実際の結果で完了させ、新しい出力先にoffline HTML reportを生成します。

      Traceは証拠を記録し、flowの再生や結果の変更はしません。UI／WorldやObserve値が必要な場合は明示的に取得し、記録前に機密情報の扱いを決めます。Traceの取得API・Inspectorで保存済みTraceを開くを参照してください。

      diff --git a/src/pages/ja/unity/ui.astro b/src/pages/ja/unity/ui.astro index 7451bee..5359de1 100644 --- a/src/pages/ja/unity/ui.astro +++ b/src/pages/ja/unity/ui.astro @@ -6,8 +6,8 @@ import CodeNotes from '../../../components/CodeNotes.astro'; ---

      1. UPMパッケージを追加する

      -

      Gua 1.1.0のRelease Assetsからcom.link1345.gua-1.1.0.tgzを取得し、Package ManagerのAdd package from tarballで導入します。UPMパッケージにはWindows x64、Linux x64、macOS x64／arm64のnative pluginと、WebGL用のnative library／GuaWebMcp.jslibが含まれます。Gua.Testing.Unityは外部テストプロジェクト用の別パッケージです。ゲームとテストのGuaバージョンを1.1.0に揃えます。

       -
      1. Gua 1.1.0のReleaseを開く

        AssetsからUnity用.tgzをダウンロードします。

      2. Package Managerへ追加

        ＋ → Add package from tarballを選択して、ダウンロードしたファイルを指定します。

      3. サンプルを取り込む

        Package ManagerのGua詳細画面でSamplesを開き、Runtime UI FixtureをImportすると、対応UIをまとめたシーンを確認できます。

      +

      最新GuaのRelease Assetsからcom.link1345.gua-<version>.tgzを取得し、Package ManagerのAdd package from tarballで導入します。UPMパッケージにはWindows x64、Linux x64、macOS x64／arm64のnative pluginと、WebGL用のnative library／GuaWebMcp.jslibが含まれます。Gua.Testing.Unityは外部テストプロジェクト用の別パッケージです。ダウンロードしたファイル名の版にテストパッケージを揃えます。

      <version>はAssetsに表示された実際の版です。例えば1.1.1なら、ファイル名にも1.1.1が入ります。既存のテスト環境では、その環境と同じ版のReleaseを選びます。

       +
      1. 最新GuaのReleaseを開く

        AssetsからUnity用.tgzをダウンロードします。

      2. Package Managerへ追加

        ＋ → Add package from tarballを選択して、ダウンロードしたファイルを指定します。

      3. サンプルを取り込む

        Package ManagerのGua詳細画面でSamplesを開き、Runtime UI FixtureをImportすると、対応UIをまとめたシーンを確認できます。

      Windows x86_64、Linux x86_64、またはmacOS x64／arm64でMonoと.NET Standard 2.1 API Compatibility Levelを使用します。TextMeshProを使う場合はImport TMP Essential Resourcesを先に実行します。

      2. 自動起動の仕組みを理解する

      Godot版ではゲーム側がattach()とupdate()を呼びますが、Unity版ではUPMパッケージが同じ責務を自動で引き受けます。sceneごとにGua初期化scriptを追加する必要はありません。

      diff --git a/src/pages/ja/visual-testing/index.astro b/src/pages/ja/visual-testing/index.astro index bb52093..4acc1ff 100644 --- a/src/pages/ja/visual-testing/index.astro +++ b/src/pages/ja/visual-testing/index.astro @@ -20,7 +20,7 @@ import Callout from '../../../components/Callout.astro';

      導入

      - +

      ゲーム側と関連Guaパッケージの版を揃えます。取得後の版の記録・固定はバージョンの管理を参照してください。

      1. baselineを明示的に作る

      baselineが無い通常実行は失敗します。初回または意図したUI変更時だけ、developerが明示的に更新します。

      diff --git a/src/pages/ja/webmcp/index.astro b/src/pages/ja/webmcp/index.astro index 9bb8755..ee18daa 100644 --- a/src/pages/ja/webmcp/index.astro +++ b/src/pages/ja/webmcp/index.astro @@ -5,7 +5,7 @@ import DocPage from '../../../components/DocPage.astro'; import CodeBlock from '

      この統合には、実験的なdocument.modelContext WebMCP APIを実装したbrowserが必要です。未対応browserでもゲームは通常どおり動作し、tool登録だけを行いません。

      gui-mcpとの違い

      gua-webmcp

      export済みゲームのpage内で動き、同じtabのengine-owned JavaScript portへ接続します。Godot Web／Unity WebGLをbrowser-nativeにAI playtestするときに使います。

      gui-mcp

      別processのstdio MCP serverとして動き、native gameへWebSocket接続します。desktop版GodotやUnity Player／Editorの自動化に使います。

      WebMCPとMCPに共通するRuntimeの動作と、各接続が所有するlifetimeは状態・操作・待機の仕組みを参照してください。

       -

      Installとtool登録

      Installとtool登録

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

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

      diff --git a/src/pages/ja/world-object-tree/index.astro b/src/pages/ja/world-object-tree/index.astro index 6b29373..a824bde 100644 --- a/src/pages/ja/world-object-tree/index.astro +++ b/src/pages/ja/world-object-tree/index.astro @@ -20,5 +20,5 @@ $Door.set_meta(&"gua_world_state", {"locked": true})`} />

      World v1にworld action toolはありません。操作はSemantic UIを使うか、用途を限定したSemantic Game Actionを公開してください。

      Player向けの安全な投影

      bridgeの既定はDebugです。Player向けhostではGUA_OBSERVATION_PROFILE=playerを設定し、transportへ渡す前にUIとWorldを投影します。近傍検索の基準objectも投影後に解決するため、private、未知、座標がomitされた基準はいずれも距離を含まない同じ空結果になります。clientからDebugへ昇格できません。続いてエージェント公開ポリシー編を参照してください。

      Worldの半径検索と物理queryの違い

      relativeToObjectId／maxDistanceは、projection後の公開済みWorld objectの位置を検索します。colliderへのraycastではありません。物理queryには別途providerを接続し、Testing／Debugの明示的な認可が必要です。local managed adapterはGua.Runtime.GuaRuntimeSpatialClient、外部.NETテストはGua.Testing.GuaWebSocketContext.GetSpatialInfo／QuerySpatialBatch、gui-mcpはget_spatial_info／query_spatial_batchを使います。

      検証したproviderはGodot 4.7 GodotPhysics3D／JoltとUnity 6000.5.3f1 desktop Mono／PhysXです。reset、scene／provider変更、認可解除でrequestは無効になります。query数と結果の上限はproviderが示す範囲を守ります。組み込みbrowser WebMCPの権限付きqueryは非対応です。provider設定と上限を参照してください。

      -

      TypeScriptからWorld型を使う

      gua-world-tools@1.1.0で物体一覧の形式を検証し、検索条件を組み立てます。追加の型付き観測値を比較する場合はgua-value-toolsを使います。Worldのstateは通常の文字列・数値・boolean・nullで、Valueの型付きJSONとは別です。npmパッケージの導入とドア・所持アイテムの例を参照してください。

      +

      TypeScriptからWorld型を使う

      gua-world-tools@latestで物体一覧の形式を検証し、検索条件を組み立てます。追加の型付き観測値を比較する場合はgua-value-toolsを使います。Worldのstateは通常の文字列・数値・boolean・nullで、Valueの型付きJSONとは別です。npmパッケージの導入とドア・所持アイテムの例を参照してください。

       diff --git a/src/pages/mcp/index.astro b/src/pages/mcp/index.astro index 78ec2fb..22eea5e 100644 --- a/src/pages/mcp/index.astro +++ b/src/pages/mcp/index.astro @@ -4,7 +4,7 @@ const config = `{ "mcpServers": { "gua": { "command": "bunx", - "args": ["gui-mcp@1.1.0", "mcp"], + "args": ["gui-mcp@latest", "mcp"], "env": { "GUA_BRIDGE_URL": "ws://127.0.0.1:8765", "GUA_ARTIFACT_DIR": ".gua" diff --git a/src/pages/recording/index.astro b/src/pages/recording/index.astro index 9a46059..277f3b6 100644 --- a/src/pages/recording/index.astro +++ b/src/pages/recording/index.astro @@ -10,7 +10,7 @@ import Callout from '../../components/Callout.astro';
      Semantic targetID / role / focus→Enqueue actionassign requestId→Host completionsame requestId→recording.jsontarget, timing, revision→Replay + waitresolve every step
      Figure 1: Recording waits for host completion instead of treating queue acceptance as success.
      -

      Install

      +

      Install

      Align the game integration and related Gua package versions. See version management for recording and pinning the result.

      Record a flow

      -

      1. Add test packages

      Gua.Testing.Unity is published on NuGet. These commands resolve the 1.1.0 packages; commit the versions written to the project and keep the three Gua packages on the same version line.

      1. Add test packages

      Gua.Testing.Unity is published on NuGet. These commands resolve the latest compatible stable packages; commit the versions written to the project and keep the three Gua packages on the same version line.

      Align the game integration and related Gua package versions. See version management for recording and pinning the result.

      2. Start a Player or Editor

      Wait for actionable UI

      Gua.Testing locators resolve a current strict single match when used. Actions wait for visible/enabled state and the advertised action, then correlated host completion. Multiple matches fail immediately. Resolution, enqueue, and completion share one timeout budget; rejected enqueue and host failure are not automatically retried.

      ResolveAsync waits for the next node to exist; add the state assertion your test requires. Locator API and timeout rules.

      -

      Compare semantic state without pixels

      Add Gua.Testing.Snapshots at 1.1.0 to compare UI IDs, hierarchy, text, values, and state against reviewed JSON baselines. It works with host.Context, including a headless host. Add Gua.Testing.Visual separately when rendered pixels matter. Installation, masks, and baseline update example.

      - +

      Compare semantic state without pixels

      Add Gua.Testing.Snapshots to compare UI IDs, hierarchy, text, values, and state against reviewed JSON baselines. It works with host.Context, including a headless host. Add Gua.Testing.Visual separately when rendered pixels matter. Installation, masks, and baseline update example.

      +

      Save test evidence with Gua.Testing Trace

      Trace belongs to Gua.Testing; no extra Trace package is needed. Enable it for a test scope, complete it with the test's actual outcome, and create an offline HTML report at a new output path.

      Trace records evidence; it does not replay the flow or change its result. Capture UI/World or Observe values explicitly when required, and handle sensitive data before recording. Trace capture APIs · Open a saved Trace in Inspector.

      diff --git a/src/pages/unity/ui.astro b/src/pages/unity/ui.astro index 44e100c..77653c0 100644 --- a/src/pages/unity/ui.astro +++ b/src/pages/unity/ui.astro @@ -5,7 +5,7 @@ import CodeBlock from '../../components/CodeBlock.astro'; import CodeNotes from '../../components/CodeNotes.astro'; --- -

      1. Add the UPM package

      Download com.link1345.gua-1.1.0.tgz from the Gua 1.1.0 release assets and install it through Package Manager's Add package from tarball. The UPM package contains native plugins for Windows x64, Linux x64, macOS x64/arm64, plus WebGL native libraries and GuaWebMcp.jslib. Gua.Testing.Unity is a separate package for the external test project. Keep the game and test packages on version 1.1.0.

      1. Open the Gua 1.1.0 release

        Download the Unity .tgz from Assets.

      2. Add it in Package Manager

        Choose ＋ → Add package from tarball and select the downloaded archive.

      3. Import the sample

        Open Samples on the Gua package page and import Runtime UI Fixture for a scene containing the supported UI systems.

      +

      1. Add the UPM package

      Download com.link1345.gua-<version>.tgz from the latest Gua release assets and install it through Package Manager's Add package from tarball. The UPM package contains native plugins for Windows x64, Linux x64, macOS x64/arm64, plus WebGL native libraries and GuaWebMcp.jslib. Gua.Testing.Unity is a separate package for the external test project. Match the test packages to the version shown in the downloaded file name.

      <version> means the actual version shown in Assets; for 1.1.1, the file name contains 1.1.1. For an existing test setup, choose the release matching that setup.

      1. Open the latest Gua release

        Download the Unity .tgz from Assets.

      2. Add it in Package Manager

        Choose ＋ → Add package from tarball and select the downloaded archive.

      3. Import the sample

        Open Samples on the Gua package page and import Runtime UI Fixture for a scene containing the supported UI systems.

      Use Windows x86_64, Linux x86_64, or macOS x64/arm64 with Mono and the .NET Standard 2.1 API Compatibility Level. Import TMP Essential Resources before building when TextMeshPro is present.

      2. Understand automatic startup

      Godot game code calls attach() and update(). The Unity UPM package owns the equivalent work automatically, so each scene does not need a Gua initialization script.

      BeforeSceneLoad→Create runtime and driver→LateUpdate→Collect UI and dispatch actions
型 / 設定公開契約
Internal stepWhat it means for game code
GuaUnityRuntime.EnsureStarted()Creates the runtime and WebSocket bridge once before scenes load.
GuaUnityBootstrap.LateUpdate()Collects UI after ordinary Update work for the frame.
BeginFrame → collect → EndFramePublishes UI Toolkit, uGUI, and TMP as one consistent semantic snapshot.
Action dispatchApplies remote requests to Unity controls and returns request-correlated results.

The package manages new GuaRuntime(), attach(), per-frame update(), manual semantic registration, bridge startup, and disposal. Game code implements normal Unity UI plus stable IDs where needed.

3. Implement UI Toolkit controls

Place standard controls below a runtime UIDocument; name or viewDataKey provides stable identity.

diff --git a/src/pages/visual-testing/index.astro b/src/pages/visual-testing/index.astro index 5ce6e48..a2279d1 100644 --- a/src/pages/visual-testing/index.astro +++ b/src/pages/visual-testing/index.astro @@ -11,7 +11,7 @@ import Callout from '../../components/Callout.astro';
Stable UI frameoptionally wait→Actual PNGfrom diagnostics→Reviewed baselinename + variant→Pixel comparisonthreshold + masks→PASS / artifactsreview differences
Figure 1: The baseline is selected by test name and variant; failures preserve all comparison evidence.
-

Install

+

Install

Align the game integration and related Gua package versions. See version management for recording and pinning the result.

Create a baseline deliberately

This integration requires a browser that implements the experimental document.modelContext WebMCP API. Feature detection is non-fatal: unsupported browsers continue running the game without registering tools.

How it differs from gui-mcp

gua-webmcp

Runs in the exported game's page and talks to an engine-owned JavaScript port in that same tab. Use it for browser-native AI playtesting of Godot Web or Unity WebGL.

gui-mcp

Runs as a separate stdio MCP server and connects to a native game through WebSocket. Use it for desktop Godot or Unity Player/Editor automation.

See How Gua manages state, actions, and waits for the Runtime behavior shared by WebMCP and MCP and the lifetime each connection owns.

 -

Install and register

Install and register

This is for a new setup. See npm packages for aligning an existing game and recording a lockfile.

The engine port must exist before the bridge is created and tools are registered, because game-input capabilities are read once during registration. Load the engine export first, wait for window.__guaGodotWebPort, then call the no-argument createGodotWebBridge(). For Unity WebGL, wait for window.__guaUnityWebPort and call the no-argument createUnityWebGlBridge(). Each helper resolves its default global port name; do not pass the port object itself.

diff --git a/src/pages/world-object-tree/index.astro b/src/pages/world-object-tree/index.astro index 66ced41..0f0a25f 100644 --- a/src/pages/world-object-tree/index.astro +++ b/src/pages/world-object-tree/index.astro @@ -20,5 +20,5 @@ $Door.set_meta(&"gua_world_state", {"locked": true})`} />

World v1 has no world-action tools. Operate UI semantically or publish a bounded Semantic Game Action instead of exposing arbitrary scene mutation.

Player-safe projection

The bridge defaults to Debug. Set GUA_OBSERVATION_PROFILE=player in a player-facing host so UI and World data are projected before any transport receives them. Nearby search resolves its reference only after projection; private, unknown, and coordinate-omitted references therefore produce the same empty result and reveal no distance. A client cannot request an upgrade to Debug. Continue with the Agent exposure policy guide.

World radius search versus physics queries

relativeToObjectId/maxDistance searches the projected positions of published World objects. It does not raycast against colliders. Physics queries need a separately bound and explicitly authorized Testing/Debug provider. Local managed adapters use Gua.Runtime.GuaRuntimeSpatialClient; external .NET tests use Gua.Testing.GuaWebSocketContext.GetSpatialInfo/QuerySpatialBatch; gui-mcp uses get_spatial_info/query_spatial_batch.

The tested providers are Godot 4.7 GodotPhysics3D/Jolt and Unity 6000.5.3f1 desktop Mono/PhysX. Reset, scene/provider changes, and revoked access invalidate requests; keep query count and result bounds within the provider's advertised limits. Built-in browser WebMCP privileged queries are unsupported. Provider setup and limits.

-

Use World types in TypeScript

Use gua-world-tools@1.1.0 to validate object trees and build selectors. Use gua-value-tools to compare additional typed observations. World state uses ordinary strings, numbers, booleans, or null rather than typed Value JSON. See npm installation and the door/inventory examples.

+

Use World types in TypeScript

Use gua-world-tools@latest to validate object trees and build selectors. Use gua-value-tools to compare additional typed observations. World state uses ordinary strings, numbers, booleans, or null rather than typed Value JSON. See npm installation and the door/inventory examples.