How Gua manages state, actions, and waits

Example: click Start, then wait for the game screen

The next screen may not be ready as soon as a button is clicked. Gua first confirms that the game processed the click, then reads fresh state until the game screen appears. Action completion and the resulting screen change are separate checks.

External .NET test examplecsharp

using System;
using Gua.Testing;

await GuaAssertions.Query(host.Context)
    .ById("start").ClickAsync();

await GuaAssertions.WaitForVisibleAsync(host.Context, "game-title",
    timeout: TimeSpan.FromSeconds(5));

host.Context connects to the running game. ById("start") finds the published button; ClickAsync waits for readiness and game-side completion. GuaAssertions.WaitForVisibleAsync checks fresh state for up to five seconds until game-title on the next screen is visible.

Who keeps what

Read the diagram from the game down to AI and tests. Action requests travel back in the other direction. Runtime is the part of Gua that manages published state and the exchange of action requests and results.

SOURCE OF TRUTHGodot or Unity

Owns the actual scene, UI controls, gameplay values, and input state.

COLLECTIONEngine integration

Collects only the UI and world information the game is allowed to publish on each update.

PUBLISHED PROTOCOL STATEGua Runtime

Keeps the current snapshots and change numbers, queues action requests, and correlates host completion results.

DESKTOP AIgui-mcp → AI client

The stdio MCP server reaches the game bridge over WebSocket.

BROWSER AIgua-webmcp → AI client

Page tools use an engine-owned port in the same browser tab.

OTHER PROTOCOL CONSUMERSTests and Inspector

Use local bindings or the game bridge directly; they do not pass through the two MCP connectors.

The engine owns the real game state. Gua Runtime owns the published view and action requests and results. MCP and WebMCP connect AI clients; tests and Inspector are independent consumers of the same protocol.

A published view follows game updates

The engine integration collects UI and objects approved for publication. Gua Runtime switches to each completed view. Semantic UI Tree means the UI list and its hierarchy; World Object Tree means the published list of doors, enemies, and other objects. Each tree updates separately.

Field	Meaning	Purpose
`frameSequence`	How many updates of this tree have completed.	Shows that a fresh update arrived even if the content stayed the same.
`revision`	How many times this tree’s content changed.	Distinguishes updates with changed state.
`sessionEpoch`	The execution session separated by reset.	Prevents mixing old execution data with new data.

Compare frameSequence and revision only within the same tree and sessionEpoch, never between UI and World. A successful reset starts a new epoch and restarts the applicable counters.

From request to completion

Send a request
AI or a test requests a click on start.
Runtime queues it
A requestId tracks this operation. Acceptance into the queue is not completion.
The game processes it
The integration checks the current target and required permissions, then uses the game’s normal action path.
Return a result
Success or failure carries the same request ID. Check later UI or world changes with a separate condition wait.

Wait for a condition, or just let time pass

A condition wait reads fresh state to check “the game screen appeared” or “the door is open.” It ends on a match or timeout; connections that propagate cancellation can stop it earlier. Sleeping for two seconds does not prove the desired state appeared.

MCP wait_for_node checks ID presence, which does not imply visibility. World wait_for_world_object checks a selector. Nearby searches recalculate distances within each fresh snapshot rather than retaining old positions. See the testing guide for richer conditions.

What changes between MCP and WebMCP

Concern	gui-mcp	gua-webmcp
Connection	A separate process uses WebSocket to reach the game.	Uses the game’s port in the same browser tab.
Published view	Chosen by the host; Debug by default. Player-facing use requires host configuration.	Always Player-facing. The page cannot request Debug.
Shared behavior	Published snapshots, game-side action completion, condition waits, and connection-owned input.

Held input belongs to its connection

Holding W belongs to the connection or input session that started it. A lease limits how long input can remain held. Release, lease expiry, disconnect, reset, session disposal, tool unregistration, or game shutdown neutralizes that owner’s input without releasing another owner’s controls. Input setup and usage

The AI client keeps conversations and reasoning

Gua does not retain AI conversations or intermediate reasoning. Whether AI can do other work during a wait depends on its client and execution environment. Trace records test observations and results, not AI thought processes.

Next steps: Desktop AI connection · Browser AI connection · UI view · World view · Runtime implementation details