Godot API and specification

Choosing a package

Godot public types

Godot runtime surface

gua_godot... translates Godot and GDScript types, while gua_runtime.dll is the engine-neutral runtime. The former links to the latter, so Windows packages place both under addons/gua/bin.

cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug --target gua-godot

Test-host API

UI mapping

Every frame recollects role, label, text/value, visibility, enabled and focused state, selection, range, scroll, parent ID, and viewport bounds. IDs default to NodePath relative to the root; use gua_id only where identity must remain stable.

Actions and completion

External requests are consumed during update(screen) and applied through normal Godot properties, signals, and input events. The adapter then returns a result event with the same requestId. Clicks emit BaseButton pressed, selections use ItemList and OptionButton selection signals, and key input is routed to the focused Control.

press_key modifier bits are 1=Shift, 2=Alt, 4=Control, and 8=Command. Hidden or disabled Controls and unsupported values or actions produce explicit results rather than being reported as successful.

Engine-neutral specification

• The Semantic UI Tree, roles, action/request/event model, and JSON schemas are shared with every adapter, including Unity.
• Bounds use physical viewport pixels with a top-left origin and positive right/down axes.
• Inspector, MCP, and external tests connect to the same WebSocket bridge. The default port is 8765 and GUA_BRIDGE_PORT can override it.
• Screenshot completion checks frame sequence and session, and reports headless or disabled rendering explicitly.

Extending another engine

Gua.Core, Gua.Runtime, Gua.Testing, and the protocol can be reused. Godot's GDExtension, GDScript, Control traversal, and signals cannot. Each engine needs an adapter that collects its UI types and applies operations through native events. Unity has a separate Unity API and adapter.

Lifecycle and ownership

The game owns GuaAutoAdapter. Create it in _ready(), pass the root Control to attach, and call update(screen) from _process(). The adapter loads the GDExtension and creates the native context through ClassDB.instantiate("GuaContext").

const GuaAutoAdapterScript := preload(
  "res://addons/gua/gua_auto_adapter.gd"
)

var ui := GuaAutoAdapterScript.new()

func _ready() -> void:
  ui.attach(self)
  ui.start_inspector_bridge(8765)
  ui.update("title")

func _process(_delta: float) -> void:
  ui.update("title")

Key parts of the main.gd sample

View the complete main.gd on GitHub ↗

Usage notes

• Use the GDScript addon for new Godot integrations. The experimental C# sample is not a feature-equivalent replacement.
• gua_sensitive hides semantic values but does not automatically mask text already rendered into a PNG.
• When running multiple Godot processes in parallel, allocate an available port per test instead of sharing one fixed port.
• A missing, stale, or platform-incompatible native DLL prevents creation of GuaContext.