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. Inspector renders the result in its separate World Object Tree panel.
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. A client cannot request an upgrade to Debug. Continue with the Agent exposure policy guide.