導入とUI実装 | Gua 日本語リファレンス

配布済みアドオンを入れる

最新GuaのReleaseを開く
AssetsからGodot用ZIPをダウンロードして展開します。

addons/guaをコピー

配置後の構成text

your-game/
├─ project.godot
└─ addons/
   └─ gua/
      ├─ gua.gdextension
      ├─ gua_auto_adapter.gd
      ├─ plugin.cfg
      └─ bin/

各ファイルの役割

ファイル	役割
`project.godot`	Godotプロジェクト本体の設定ファイルです。
`addons/gua/gua.gdextension`	GodotからGuaのnative runtimeを読み込むためのGDExtension定義です。
`addons/gua/gua_auto_adapter.gd`	Controlツリーを収集し、外部操作をGodotへ戻すGDScriptアダプターです。
`addons/gua/plugin.cfg`	Godot Editorへアドオンの名前とエントリーポイントを伝えます。
`addons/gua/bin/`	GuaのGDExtensionが読み込むplatform別native libraryを格納します。

Godotでプロジェクトを開く
GDExtensionが読み込まれたことをGodotの出力で確認します。

GDScriptで導入する

アダプターを明示的にpreloadする

class_nameの登録順に依存しないため、サンプルと同じ明示的なpreloadを使います。

main.gdgdscript

extends Control

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

var ui := GuaAutoAdapterScript.new()

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

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

main.gdの記述を上から読む

記述	意味
`extends Control`	このscriptをUIのルートControlとして動かします。attach(self)へ渡せる型でもあります。
`preload("res://addons/gua/gua_auto_adapter.gd")`	アダプターscriptをscene起動前に明示的に読み込みます。
`var ui := GuaAutoAdapterScript.new()`	GuaAutoAdapterのinstanceを1つ作り、この画面の収集と操作配送に使います。
`func _ready() -> void:`	このControlと子nodeがscene treeへ入った直後に一度だけ実行されます。
`ui.attach(self)`	現在のControlをUI収集のルートに指定します。以後はself以下のControlが走査対象です。
`ui.update("title")`	論理画面名をtitleとして、現在のControl状態をSemantic UI Treeへ公開します。
`ui.start_inspector_bridge(8765)`	Inspector、MCP、外部テストが接続するWebSocket bridgeをport 8765で開始します。
`func _process(_delta: float) -> void:`	Godotの描画frameごとに呼ばれます。未使用の経過時間は_deltaという名前で示しています。
`ui.update("title")`	表示、text、値、focusなどの変化を毎frame再収集し、外部actionも処理します。

識別子を必要な箇所だけ固定する

既定IDはNodePathから得られます。シーン構造を変えても維持したいIDはメタデータで指定します。

安定IDと機密入力gdscript

name_input.set_meta("gua_id", "login-user")
password_input.set_meta("gua_id", "login-password")
password_input.set_meta("gua_sensitive", true)

metadataの意味

記述	意味
`name_input.set_meta("gua_id", "login-user")`	name_inputへ固定ID login-userを付け、NodePath変更後も同じlocatorで検索できるようにします。
`password_input.set_meta("gua_id", "login-password")`	password入力欄にもテストから参照する固定IDを付けます。
`password_input.set_meta("gua_sensitive", true)`	入力値を機密扱いにし、Semantic UI Tree、履歴、diagnosticsへ平文を残さないようにします。スクリーンショット上の表示は別途マスクが必要です。

World Object Treeを公開する

UIではないdoor、enemy、objectiveなどは、対象のNode2DまたはNode3Dをgua_world_object groupへ追加し、意味情報をmetadataで設定します。adapterがui.update()のたびに位置とstateを収集するため、native APIを直接呼ぶ必要はありません。

Doorをゲーム世界のobjectとして公開gdscript

@onready var reactor_door: Node2D = $World/ReactorDoor
var reactor_door_locked := true

func expose_reactor_door() -> void:
  reactor_door.add_to_group(&"gua_world_object")
  reactor_door.set_meta(&"gua_world_id", "reactor-door")
  reactor_door.set_meta(&"gua_world_kind", "door")
  reactor_door.set_meta(&"gua_world_label", "Reactor door")
  reactor_door.set_meta(&"gua_world_visible_to_player", true)
  reactor_door.set_meta(&"gua_world_tags", ["reactor", "mission-critical"])
  update_reactor_door_state()

func update_reactor_door_state() -> void:
  reactor_door.set_meta(&"gua_world_state", {
    "locked": reactor_door_locked,
    "power": "online"
  })

expose_reactor_door()を_ready()から一度呼び、doorの状態が変わったらupdate_reactor_door_state()を呼びます。gua_world_idは必須かつ同じframe内で一意です。位置はnodeのglobal_positionから取得され、公開済みancestorがあれば最も近いobjectをparentとして扱います。stateは入れ子にせず、string、有限number、boolean、nullだけを使います。概念と検索方法はWorld Object Tree編を参照してください。

WebへExportする

同じRelease addonでGodot WebのDebug／Release exportを利用できます。Web export presetでExtension Supportを有効にし、single-thread variantを使います。Godotはgua.gdextensionを読み、対応するweb.wasm32.single.debugまたはweb.wasm32.single.release WASMを自動選択します。

収集される主なControl

入力

LineEdit、TextEdit、CheckBox、OptionButton、ItemList

状態

フォーカス、選択、値、スクロール、範囲、表示・有効状態

UI／Worldに追加の観測値を公開する

標準のtreeにない型付きの値はObserveで明示的に登録します。公開済みUI／World ownerに結び付け、オブジェクトの削除時に登録を解除します。ゲーム側のGuaAutoAdapter.create_observe_ownerから登録できます。Playerへの公開は明示的なopt-inです。エンジンごとの登録例とValue・登録・外部購読の説明を参照してください。