導入とUI実装

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

1. Latest Releaseを開く

   AssetsからGodot用ZIPをダウンロードして展開します。

2. addons/guaをコピー

   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を格納します。

3. Godotでプロジェクトを開く

   GDExtensionが読み込まれたことをGodotの出力で確認します。

GDScriptで導入する

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

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

   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も処理します。

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

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

   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へ平文を残さないようにします。スクリーンショット上の表示は別途マスクが必要です。

収集される主なControl