Inspector | Gua Reference

Run and connect

Launch Inspector
Open the installed Gua Inspector application.
Start the in-game bridge
Run the Gua-integrated game with its WebSocket bridge enabled.
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.

Install repository dependencies

PowerShellpowershell

bun install --frozen-lockfile
bun run --filter gua-world-tools build
bun run --filter gua-value-tools build

Start browser Inspector
Terminal 1powershell
```
bun run --filter @gua/inspector dev
```
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.
Terminal 2 (sample bridge)powershell
```
bun run bridge:ws
```
Connect to the URL
texttext
```
ws://127.0.0.1:8765
```

What to inspect

Semantic UI Tree

Screen, role, ID, text, and parent/child structure. Confirm that the expected Controls were collected.

Node state

Visibility, enabled state, focus, checked state, value, and bounds used by tests.

Logs

Runtime logs published by the game, useful for state changes the connection alone cannot explain.

Screenshot

An explicitly published PNG for comparing semantic state with the rendered frame.

Automation panel

Semantic actions

Click, focus, set a value, check/uncheck, select, scroll, or send a key to the selected node.

Recording / Replay

Record actions, download/import JSON, and replay. Sensitive values resolve from an in-memory secret map.

Visual compare

Use the current screenshot or a selected PNG as a baseline and compare pixels in the browser.

Artifacts

Explicitly download Actual, Expected, Diff images and the comparison manifest.

Desktop development build

Running the Tauri shell from source also requires the Rust toolchain.

PowerShellpowershell

bun run --filter @gua/inspector build
bun run --filter @gua/inspector tauri:dev

Generate a C# test from a node

Select a semantic node to generate Gua.Testing locators, actions, and assertions. Prefer stable IDs, check that the generated context matches your host, and review the expected state before adding it to a test. Supported code-generation forms · Locator action waits.

Inspect additional values

The Observe panel shows values and change notifications registered by the game when observe_v1 is available. Enum choices come from Value catalogs. A gap or stale session requires a new subscription; Inspector does not register remote getters or promote Player to Debug. Registration and lifecycle.

Open Gua Trace offline

Use Open Gua Trace (offline) to read a saved Trace without connecting to a game. Inspect operations, host completion, observations, the runner's outcome, and explicit attachments. Trace is not Recording and does not execute a replay. Gua.Testing.GuaTraceReport.WriteHtml creates a self-contained HTML report without Node or Bun. Create a Trace and report.