What is World Object Tree?
Semantic UI Tree describes interface elements such as buttons, labels, and input fields. World Object Tree describes the game world outside that UI: for example, “the reactor door is locked,” “enemy A is active,” or “checkpoint B is available.” It gives each published object a stable identity and semantic state without exposing the engine's complete scene graph.
What an object contains
World Object Tree v1 stores a stable id, semantic kind, optional label and parent, 2D or 3D position, active and player-visible state, tags, and flat primitive state. State values are strings, finite numbers, booleans, or null.
$Door.add_to_group(&"gua_world_object")
$Door.set_meta(&"gua_world_id", "door-a")
$Door.set_meta(&"gua_world_kind", "door")
$Door.set_meta(&"gua_world_label", "Reactor door")
$Door.set_meta(&"gua_world_visible_to_player", true)
$Door.set_meta(&"gua_world_state", {"locked": true})Godot and Unity
Add a Node2D or Node3D to the gua_world_object group and supply gua_world_* metadata. IDs must be unique and parent references must resolve inside the same published frame.
Add GuaWorldObject to an active GameObject and configure its ID, kind, visibility, tags, and state. The adapter publishes only registered components.
Query and wait
MCP exposes get_world_object_tree, find_world_objects, and wait_for_world_object. Selectors can match ID, kind, label, tags, state, ancestor, activity, and visibility. Supply relativeToObjectId and maxDistance to search around a reference object, with an optional positive limit. Inspector renders the tree in its separate World Object Tree panel.
{
"kind": "enemy",
"relativeToObjectId": "player",
"maxDistance": 12,
"limit": 5
}Nearby search uses one projected World snapshot: XY Euclidean distance for world2d and XYZ for world3d. The maximum is inclusive, the reference object is excluded, and results are ordered by distance then object ID before the limit is applied. Distances use the host-defined world unit, so a scene must publish positions and radii in one consistent unit convention.
Every successful query returns sessionEpoch, frameSequence, and revision. A nearby result also includes spatial.distances aligned with its returned matches and truncated when the limit omitted further matches.
Player-safe projection
The bridge defaults to Debug. Set GUA_OBSERVATION_PROFILE=player in a player-facing host so UI and World data are projected before any transport receives them. Nearby search resolves its reference only after projection; private, unknown, and coordinate-omitted references therefore produce the same empty result and reveal no distance. A client cannot request an upgrade to Debug. Continue with the Agent exposure policy guide.
World radius search versus physics queries
relativeToObjectId/maxDistance searches the projected positions of published World objects. It does not raycast against colliders. Physics queries need a separately bound and explicitly authorized Testing/Debug provider. Local managed adapters use Gua.Runtime.GuaRuntimeSpatialClient; external .NET tests use Gua.Testing.GuaWebSocketContext.GetSpatialInfo/QuerySpatialBatch; gui-mcp uses get_spatial_info/query_spatial_batch.
The tested providers are Godot 4.7 GodotPhysics3D/Jolt and Unity 6000.5.3f1 desktop Mono/PhysX. Reset, scene/provider changes, and revoked access invalidate requests; keep query count and result bounds within the provider's advertised limits. Built-in browser WebMCP privileged queries are unsupported. Provider setup and limits.
Use World types in TypeScript
Use gua-world-tools@latest to validate object trees and build selectors. Use gua-value-tools to compare additional typed observations. World state uses ordinary strings, numbers, booleans, or null rather than typed Value JSON. See npm installation and the door/inventory examples.