Gua is a game testing and automation protocol for Godot and Unity, built around Playwright-like design principles. Semantic UI Tree automation remains its core, with the World Object Tree, gameplay input, MCP and WebMCP, AI agent exposure policy, virtual time, Recording, and visual comparison. AI can develop and verify a game, then use approved information and operations to play its release build as a player.
Gua supports both an AI that assists the developer and an AI that participates in the game. They do not receive the same information or permissions.
An AI coding agent changes code and uses the Debug profile to inspect UI, logs, and screenshots, verify the result, and fix failures.
An AI agent player uses the Player profile to read approved UI and World information and advances the game with only authorized UI operations and gameplay input.
Download the Godot add-on and Windows Inspector from GitHub Releases / Latest. Building Gua from source is intended for contributors working on Gua itself.
HOW IT WORKSGua goes beyond UI testing. It exposes UI, explicitly selected game-world information, and authorized gameplay input through one semantic protocol used consistently by tests, Inspector, MCP, WebMCP, Recording, and visual comparison.
Read id, role, text, hierarchy, and bounds together with visible, enabled, value, focus, checked, selected, caret, scroll, and range state, all tied to a frame and revision.
Semantic UI Tree · Node state · Logs · Runtime capabilitiesMatch id, role, text, and value exactly, by substring, or by regular expression. Combine parent scope, direct children, visibility, enabled, selection, and count conditions.
GetById · GetByRole · GetByText · Within · QueryAllSend click, focus, value, check, select, scroll, and key actions to semantic targets. Confirm the correlated host completion event instead of treating queue acceptance as success.
Click · SetValue · SetChecked · Select · Scroll · PressKeyFrom NUnit, xUnit, MSTest, or C++, wait for visibility, values, focus, selection, counts, and stable snapshots. Build deterministic tests without fixed sleeps.
Gua.Testing · C++ helpers · Async waits · CancellationRequest PNGs from rendered Godot or Unity runs and save them with dimensions, session, and frame metadata. Headless, unsupported, timeout, and cancellation remain distinct outcomes.
CaptureScreenshot · SaveScreenshot · Test attachmentGua.Testing.Visual supports pixel thresholds, allowed difference ratios, masks, and OS/renderer variants. Failures produce Expected, Actual, Diff, and a comparison manifest.
Gua.Testing.Recording stores actions, timing, revisions, and wait conditions, then replays with host completion checks. Sensitive values are represented only by secret keys.
Collect the UI tree and diff, pending requests, event history, logs, runtime version, environment, screenshot, and game-process output into one failure artifact.
Failure diagnostics · stdout/stderr · Strict isolationThe browser and Windows desktop Inspector show the tree, node state, logs, and screenshot. Invoke every semantic action, Recording, Replay, and Visual comparison from the UI.
Tree inspector · Node bounds · Automation panelDuring development, gui-mcp exposes Debug capabilities. For a native release build, the host must configure gui-mcp with the Player profile; browser WebMCP is always fixed to Player. Both paths then expose only Player-scoped observation and operations.
Publish stable doors, objectives, enemies, and checkpoints as a separate read-only tree with semantic state and player visibility.
World Object Tree · Selectors · Waits · InspectorExpose a Semantic Game Action map or capability-gated raw input with owner isolation, bounded leases, confirmation, and neutral cleanup.
Action Map · Keyboard · Pointer · Gamepad · TextKeep developer Debug data complete while the game restricts the UI and World information and UI operations exposed to an AI player.
Debug / Player · Field rules · Action allowlistRegister Godot Web or Unity WebGL semantic tools through the page's experimental WebMCP API without a separate MCP server or WebSocket.
gua-webmcp · Godot Web · Unity WebGL · Player profileThe recommended GDScript add-on recursively reflects the Control tree, including Button, LineEdit, TextEdit, CheckBox, OptionButton, ItemList, Range, and ScrollContainer. The external host manages scene startup, available ports, headless/rendered runs, stdout/stderr, and strict resets.
The UPM package automatically reflects UI Toolkit, uGUI, and TextMeshPro. External tests can launch Editor Play Mode or a Windows Mono Player for headless semantic tests and rendered Screenshot or Visual tests.
Wait for visible, enabled, text, value, focus, checked, selected, count, or a stable snapshot from fresh frames.
Zero or multiple matches fail clearly; multi-result queries are explicit through QueryAll.
Pair actions with observed host results by request ID without consuming unrelated events.
Strict reset detects pending requests, in-flight actions, and leaked events between tests.
Redact sensitive values from snapshots, logs, diagnostics, and recordings, resolving them in memory only during replay.
Run ordinary dotnet test with the public Godot Action and retain diagnostic and Visual artifacts on failure.
The guides are grouped into getting started, exposing the game, operating it with AI, testing and inspection, and cross-cutting safety and reproducibility.
Begin with your game engine, AI-assisted development, or AI player support.
Attach the GDScript adapter, collect the Control tree, and test live scenes externally.
GET STARTEDReflect Unity 6 UI Toolkit, uGUI, and TextMeshPro and test Editor or Player processes externally.
GET STARTEDUnderstand AI-assisted implementation and verification, AI players in release builds, and their different permissions.
Define which UI, world, and input semantics the game provides.
Understand the meaning, state, selectors, and UI operations exposed by game UI.
EXPOSE / WORLDExpose selected doors, objectives, enemies, and other game-world information.
EXPOSE / INPUTMake semantic actions such as jump and move, plus necessary keyboard or pointer input, operable.
Use the published UI, world, and gameplay input through the connection that fits the runtime.
Inspect live state, compare rendered output, and record reproducible operations.
View the UI Tree and state, invoke semantic operations, and investigate diagnostics.
VERIFYCompare rendered PNG output with a baseline and detect visual regressions.
REPRODUCERecord semantic operations and wait conditions, then replay them with host completion checks.
Apply these cross-cutting controls across tests and AI play rather than through one connection method.
Consult protocol, package, API, and CI details while implementing an integration.