Unity API and specification

Choosing a package

Unity public types

Gua.Runtime surface

Normal Unity projects do not need to call this layer directly because the UPM package manages it. When building a custom engine adapter, GuaRuntime creates and owns the native runtime and destroys its bridge and handle in Dispose(). Its primary API includes StartInspectorBridge/StopInspectorBridge, SetAdapterVersion, BeginFrame/EndFrame, RegisterNode, TryConsumeAction/EmitActionResult, TryConsumeScreenshotRequest/CompleteScreenshot, AddLog, GetUiTreeJson, and GetVersionJson.

Test-host API

UI mapping

Each frame collects role, label, text/value, visible, enabled, focused, checkbox checked state, ListView item selected state, slider range, parentId, and bounds. Virtualized offscreen ListView entries still get nodes, but unrealized entries have visible: false and zero bounds.

Actions and completion

The adapter consumes only actions declared by the target role. It emits the original requestId after synchronous Unity listeners return; it does not wait for coroutines, async void, or next-frame work. Invalid numbers, choices, and keys return invalid_value; unavailable combinations return unsupported. Exceptions are logged to both Gua and the Unity Console and become failed results.

press_key modifier bits are 1=Shift, 2=Alt, 4=Control, and 8=Command. Enter, Esc, and Arrow* aliases are normalized to Unity KeyCode names. A global key request is routed to the focused textbox.

Engine-neutral specification

• version_v1 includes an optional adapterVersions map. Unity reports the loaded native runtime version as {"unity":"<runtime version>"}.
• godotPluginVersion remains for compatibility and is null outside Godot.
• Adapter bounds use physical viewport pixels with a top-left origin and positive right/down axes; NaN and Infinity are not allowed.
• GuaWebSocketContext, the remote tree, and captured screenshots are available from Gua.Testing.
• The C ABI includes gua_runtime_set_adapter_version(runtime, adapter, version); existing exports remain available.
• A screenshot consumed before a session reset completes as stale_session, preventing an old image from appearing in the new session.

Lifecycle and ownership

BeforeSceneLoad creates two persistent GameObjects: a bootstrap driver and the runtime. Driver LateUpdate() runs begin → collect → end → dispatch actions → service screenshot requests. Destruction stops the bridge and disposes the native handle. The UPM artifact bundles Gua.Core.dll, Gua.Runtime.dll and dependencies, gua.dll, and gua_runtime.dll.

Usage notes

• For screens that need external integer-slider changes, use Slider for now. SliderInt state can still be observed.
• Toggle clicks are delivered as value changes. Custom behavior should listen for value/change events as well as pointer events.
• When registering a custom Control, implement the role's actions in TryApply. Observation-only controls can use a role without interactive actions.
• Parallel Unity test hosts use dynamic ports. Avoid running an unrelated process that pins the same port range.

Observe and physics API

The engine integration can register typed Observe values on published UI/World owners. External Gua.Testing.GuaWebSocketContext uses GetObserveSnapshotJson/SubscribeObservations when observe_v1 is advertised. Engine registration examples · Managed and remote examples.

Physics queries use an explicitly authorized Testing/Debug provider; Debug observation alone is insufficient. External tests call GetSpatialInfo/QuerySpatialBatch. GodotPhysics3D/Jolt and Unity PhysX setup documents bounds and invalidation. Built-in browser WebMCP privileged physics queries are unsupported. Query semantics and limits.