ゲーム世界を意味情報として公開する

World Object Treeとは？

Semantic UI Treeがbutton、label、input fieldなどのUI情報を表すのに対し、World Object TreeはUIの外側にあるゲーム世界を表します。たとえば「原子炉の扉は施錠中」「敵Aは活動中」「チェックポイントBは利用可能」といった状態を、安定したIDと意味情報で観測できるようにします。engine内部のscene treeをそのまま公開する仕組みではありません。

Objectが持つ情報

World Object Tree v1は安定したid、意味上のkind、任意のlabel・parent、2D/3D position、active・player visibility、tag、flatなprimitive stateを持ちます。state値はstring、有限number、boolean、nullに限定されます。

Godot: Node2Dを明示公開gdscript

$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とUnity

Godot

Node2DまたはNode3Dをgua_world_object groupへ追加し、gua_world_* metadataを設定します。IDは一意で、parentは同じ公開frame内に存在する必要があります。

Unity

activeなGameObjectへGuaWorldObjectを追加し、ID、kind、visibility、tag、stateを設定します。adapterは登録componentだけを公開します。

検索と待機

MCPはget_world_object_tree、find_world_objects、wait_for_world_objectを提供します。ID、kind、label、tag、state、ancestor、active、visibilityで検索できます。relativeToObjectIdとmaxDistanceを指定すると基準objectの周囲を検索でき、任意の正のlimitで返却数を制限できます。Inspectorは独立したWorld Object Tree panelへtreeを表示します。

近くの公開済みenemyを検索するjson

{
  "kind": "enemy",
  "relativeToObjectId": "player",
  "maxDistance": 12,
  "limit": 5
}

近傍検索は1つの投影済みWorld snapshotを使い、world2dではXY、world3dではXYZのユークリッド距離を評価します。最大距離は境界を含み、基準object自身を除外し、距離とobject IDの順に並べてからlimitを適用します。距離はhostが定めるworld unitなので、scene内の座標と半径は同じ単位規約で公開してください。

成功queryはsessionEpoch、frameSequence、revisionを返します。近傍結果は返却matchと対応するspatial.distances、limitで残りを省略した場合のtruncatedも返します。

Player向けの安全な投影

bridgeの既定はDebugです。Player向けhostではGUA_OBSERVATION_PROFILE=playerを設定し、transportへ渡す前にUIとWorldを投影します。近傍検索の基準objectも投影後に解決するため、private、未知、座標がomitされた基準はいずれも距離を含まない同じ空結果になります。clientからDebugへ昇格できません。続いてエージェント公開ポリシー編を参照してください。

Worldの半径検索と物理queryの違い

relativeToObjectId／maxDistanceは、projection後の公開済みWorld objectの位置を検索します。colliderへのraycastではありません。物理queryには別途providerを接続し、Testing／Debugの明示的な認可が必要です。local managed adapterはGua.Runtime.GuaRuntimeSpatialClient、外部.NETテストはGua.Testing.GuaWebSocketContext.GetSpatialInfo／QuerySpatialBatch、gui-mcpはget_spatial_info／query_spatial_batchを使います。

検証したproviderはGodot 4.7 GodotPhysics3D／JoltとUnity 6000.5.3f1 desktop Mono／PhysXです。reset、scene／provider変更、認可解除でrequestは無効になります。query数と結果の上限はproviderが示す範囲を守ります。組み込みbrowser WebMCPの権限付きqueryは非対応です。provider設定と上限を参照してください。

TypeScriptからWorld型を使う

gua-world-tools@latestで物体一覧の形式を検証し、検索条件を組み立てます。追加の型付き観測値を比較する場合はgua-value-toolsを使います。Worldのstateは通常の文字列・数値・boolean・nullで、Valueの型付きJSONとは別です。npmパッケージの導入とドア・所持アイテムの例を参照してください。