英語版が正式な参照です。内容に差異がある場合は、英語版を優先してください。

RUNTIME UI AUTOMATION FOR GAMES

ゲームUIを、意味で操作する。

Guaは、実行中のゲームUIをSemantic UI Treeとして公開する。座標や画像認識に頼らず、テストとAIから「開始ボタン」をその名前で見つけて操作できる。

Unity編を読む →Docsから調べる

AIエージェントがGua MCPサーバーを使い、Semantic UI Treeを読み取ってGodotゲームのStart Gameボタンを遠隔操作するデモ — DEMO AIエージェントがMCP経由でゲームUIを操作

GET THE LATEST

まず最新Releaseを取得する

GodotアドオンとWindows版InspectorはGitHub Releases / Latestから取得できます。ソースビルドはGua本体を開発するときの経路です。

HOW IT WORKS

ゲームの入力経路を壊さずに観測する

01 / DRAWゲームエンジンが通常どおりUIを描画

02 / REFLECTアダプターが意味情報を自動収集

03 / CONNECTWebSocketブリッジが外部へ公開

04 / ACTテスト・Inspector・MCPが操作

WHAT YOU CAN DO

観測、操作、検証、再現までを一つのプロトコルで

Guaは「スクリーンショットが撮れる」「UIテストができる」だけの道具ではありません。実行中ゲームのUIを意味情報として公開し、その同じ情報をテスト、差分比較、操作録画、Inspector、AIから利用できます。

OBSERVE / 01

UIを意味のあるツリーとして観測

id、role、text、親子関係、boundsに加え、visible、enabled、value、focus、checked、selected、caret、scroll、rangeなどの状態をframe・revision付きで取得します。

Semantic UI Tree · Node state · Logs · Runtime capabilities

LOCATE / 02

座標ではなく、役割と状態から検索

id・role・text・valueを完全一致、部分一致、正規表現で検索。親要素の内側、直下の子、表示中、有効、選択中などを組み合わせ、件数も検証できます。

GetById · GetByRole · GetByText · Within · QueryAll

ACT / 03

通常のゲーム入力経路で操作

click、focus、値入力、check、select、scroll、key入力をSemantic targetへ送ります。queueへの受理ではなく、同じrequest IDのホスト完了eventまで確認できます。

Click · SetValue · SetChecked · Select · Scroll · PressKey

TEST / 04

UIの状態変化を待ってテスト

NUnit、xUnit、MSTestなどの通常の.NETテストから、表示・値・focus・選択・件数・安定snapshotを待機。固定sleepに頼らないテストを構築できます。

Gua.Testing · C++ helpers · Async waits · Cancellation

CAPTURE / 05

描画frameのスクリーンショットを取得

GodotやUnityの描画付き実行からPNGを要求し、寸法、session、frame情報とともに保存。headless、未対応、timeout、cancelも区別できます。

CaptureScreenshot · SaveScreenshot · Test attachment

VISUAL / 06

PNGベースラインとの差分を検出

Gua.Testing.Visualでpixel閾値、許容差分率、mask、OS・renderer別variantを指定。失敗時はExpected、Actual、Diff画像とmanifestを出力します。

Baseline comparison · Masks · CI artifacts

RECORD / 07

Semantic操作を録画して再生

Gua.Testing.Recordingで操作、timing、前後revision、待機条件を記録し、ホスト完了確認付きでReplay。機密値は平文ではなくsecret keyだけを保存します。

GuaRecorder · GuaReplayer · recording.schema.json

DIAGNOSE / 08

失敗した瞬間の証拠を残す

UI Tree、前後差分、pending request、event履歴、ログ、runtime version、環境情報、スクリーンショット、ゲームプロセス出力を一つのartifactへ集約します。

Failure diagnostics · stdout/stderr · Strict isolation

INSPECT / 09

Inspectorから人間が調査・操作

ブラウザー版とWindowsデスクトップ版で、UI Tree、ノード状態、ログ、スクリーンショットを確認。全Semantic action、Recording、Replay、Visual比較を画面から実行できます。

Tree inspector · Node bounds · Automation panel

AGENT / 10

MCPからAIエージェントへ公開

gui-mcpが同じWebSocketブリッジへ接続し、UI取得、待機、全操作、ログ・PNG取得、Recording、Replay、Visual比較をAIのtoolとして公開します。

get_ui_tree · wait_for_node · run_test · visual artifacts

ENGINE SUPPORT

Godotと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テストを実行できます。

RELIABLE AUTOMATION

テストを壊れにくくする仕組み

状態ベースの待機

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へ残せます。

GUIDES & REFERENCES

導入するエンジンと道具から読む

ENGINE / 01