UIを意味のあるツリーとして観測
id、role、text、親子関係、boundsに加え、visible、enabled、value、focus、checked、selected、caret、scroll、rangeなどの状態をframe・revision付きで取得します。
Semantic UI Tree · Node state · Logs · Runtime capabilities英語版が正式な参照です。内容に差異がある場合は、英語版を優先してください。
PLAYWRIGHT-STYLE UI AUTOMATION FOR GAMES
DEMO AIエージェントがMCP経由でゲームUIを操作
ゲームUIを、意味で操作する。
GuaはGodot・Unityのゲームをテストし、AIから操作するための仕組みです。「Startというボタン」「施錠されたドア」のように、ゲームが公開した名前や状態を使います。ボタンを押し、画面やゲームの変化を確認できます。AIによる開発・検証にも、公開を許可された情報だけで遊ぶAIプレイヤーにも使えます。
AIがゲームを作る。AIがリリース版で遊ぶ。
Guaには、開発者を支援するAIと、ゲームの参加者になるAIという二つの使い方があります。使う情報と権限は同じではありません。
AIによるゲーム開発・検証
AIコーディングエージェントがコードを変更し、Debug profileでUI、ログ、スクリーンショットを調べ、実行結果を検証して修正します。
リリース版を遊ぶAIプレイヤー
AIエージェントプレイヤーがPlayer profileで許可されたUI・World情報を読み、許可されたUI操作とゲーム入力だけを使ってゲームを進めます。
使うエンジンとツールを選ぶ
Godot／Unityの導入手順に沿ってゲーム側へ導入し、必要なテストパッケージを追加します。ゲームを調べる場合はInspectorの導入を参照してください。各ガイドでReleaseのゲーム用パッケージとInspectorの導入方法、テストパッケージとのバージョンの揃え方を説明します。
Guaについての質問・相談は、サポートDiscordサーバーへどうぞ。
HOW IT WORKSゲームの入力経路を壊さずに観測する
01 / DRAWゲームエンジンが通常どおりUIを描画
02 / REFLECTアダプターが意味情報を自動収集
03 / CONNECTWebSocketブリッジが外部へ公開
04 / ACTテスト・Inspector・MCPが操作
観測、操作、検証、再現までを一つのプロトコルで
GuaはUIテストだけの道具ではありません。UI、明示したゲーム世界、許可したゲーム入力を意味のあるプロトコルとして公開し、テスト、Inspector、MCP、WebMCP、Recording、Visual比較から一貫して利用できます。
座標ではなく、役割と状態から検索
id・role・text・valueを完全一致、部分一致、正規表現で検索。親要素の内側、直下の子、表示中、有効、選択中などを組み合わせ、件数も検証できます。
GetById · GetByRole · GetByText · Within · QueryAll通常のゲーム入力経路で操作
click、focus、値入力、check、select、scroll、key入力をSemantic targetへ送ります。queueへの受理ではなく、同じrequest IDのホスト完了eventまで確認できます。
Click · SetValue · SetChecked · Select · Scroll · PressKeyUIの状態変化を待ってテスト
NUnit、xUnit、MSTestなどの通常の.NETテストから、表示・値・focus・選択・件数・安定snapshotを待機。固定sleepに頼らないテストを構築できます。
Gua.Testing · C++ helpers · Async waits · Cancellation描画frameのスクリーンショットを取得
GodotやUnityの描画付き実行からPNGを要求し、寸法、session、frame情報とともに保存。headless、未対応、timeout、cancelも区別できます。
CaptureScreenshot · SaveScreenshot · Test attachmentPNGベースラインとの差分を検出
Gua.Testing.Visualでpixel閾値、許容差分率、mask、OS・renderer別variantを指定。失敗時はExpected、Actual、Diff画像とmanifestを出力します。
Semantic操作を録画して再生
Gua.Testing.Recordingで操作、timing、前後revision、待機条件を記録し、ホスト完了確認付きでReplay。機密値は平文ではなくsecret keyだけを保存します。
失敗した瞬間の証拠を残す
UI Tree、前後差分、pending request、event履歴、ログ、runtime version、環境情報、スクリーンショット、ゲームプロセス出力を一つのartifactへ集約します。
Failure diagnostics · stdout/stderr · Strict isolationInspectorから人間が調査・操作
ブラウザー版とWindowsデスクトップ版で、UI Tree、ノード状態、ログ、スクリーンショットを確認。全Semantic action、Recording、Replay、Visual比較を画面から実行できます。
Tree inspector · Node bounds · Automation panel開発AIとAIプレイヤーを接続
開発中はgui-mcpからDebug機能を利用します。リリース版のネイティブゲームはhostがPlayer profileに設定したgui-mcp、Webゲームは常にPlayerに固定されるWebMCPから、制限された観測・操作だけを利用できます。
明示したworld objectだけを観測
door、objective、enemy、checkpointなどを、意味状態とplayer visibilityを持つ独立したread-only treeとして公開します。
World Object Tree · Selector · Wait · Inspector範囲を限定したゲーム入力を操作
Semantic Game Action Mapまたはcapability制御のRaw Inputを、owner分離、lease、confirmation、neutral cleanup付きで公開します。
Action Map · Keyboard · Pointer · Gamepad · TextAIエージェントへ安全な情報だけを見せる
開発者用Debug dataを完全に保ちつつ、AIエージェントプレイヤーへ公開するUI・World情報とUI操作をゲーム側で制限します。
Debug / Player · Field rule · Action allowlistWeb Exportをbrowser tab内で公開
別MCP serverやWebSocketを使わず、Godot Web／Unity WebGLのSemantic toolをpageの実験的WebMCP APIへ登録します。
gua-webmcp · Godot Web · Unity WebGL · Player profileGodotとUnityの実UIを自動収集
Godot 4.7
推奨GDScriptアドオンがControlツリーを再帰収集し、Button、LineEdit、TextEdit、CheckBox、OptionButton、ItemList、Range、ScrollContainerなどを観測・操作します。外部テストホストはシーン起動、空きport、headless/rendered実行、stdout/stderr、Strict resetを管理します。
Unity 6
UPMパッケージがUI Toolkit、uGUI、TextMeshProを自動収集します。Editor Play ModeまたはWindows Mono Playerを外部テストから起動し、headless Semanticテストと描画付きScreenshot・Visualテストを実行できます。
テストを壊れにくくする仕組み
状態ベースの待機
visible、enabled、text、value、focus、checked、selected、件数、安定snapshotを最新frameから待ちます。
厳密なロケーター
0件や複数件を曖昧に通さず失敗させ、複数取得が必要な場合だけ明示的にQueryAllを使います。
request相関
操作要求とホスト側の観測結果をrequest IDで結び、別のeventを誤って成功扱いしません。
テスト間の分離
Strict resetが未消費request、処理中操作、event漏れを検出し、前のテストの状態を持ち込みません。
機密情報の保護
sensitiveな入力値をsnapshot、log、diagnostics、Recordingからredactし、Replay時だけmemory上で解決します。
CIで再現
Godot用公開Actionと通常のdotnet testを使い、失敗時の診断・Visual artifactをCIへ残せます。
やりたいことの関係から読む
各章を、導入、ゲーム側からの公開、AIからの操作、テストと調査、安全性と再現性にまとめました。
1. エンジンへ導入して使い始める
利用するゲームエンジン、AIによる開発、AIプレイヤー対応の目的から始めます。
2. ゲームの情報と入力を公開する
ゲーム側がUI、ゲーム世界、操作方法をどんな意味情報として提供するかを決めます。
3. AIエージェントから接続して操作する
公開したUI、World、ゲーム入力を、実行環境に合うAI接続方法から利用します。
4. テストして、失敗を調査する
人間による実行中状態の確認、画像差分、操作の記録と再生を扱います。
5. 自動化の安全性と再現性を高める
特定の操作方法に属さず、テストやAIプレイ全体へ適用する横断機能です。
Docs・APIリファレンス
実装時に必要なプロトコル、パッケージ、API、CI設定を参照します。