パッケージの選び方
| パッケージ | 用途 | 配置先 |
|---|---|---|
addons/gua | GodotのControlツリーを自動収集し、外部からの操作を実UIへ配送 | Godotプロジェクト |
Gua.Testing.Godot | Godotプロセスの起動・接続・終了、標準出力、screenshot、診断 | 外部.NETテスト |
Gua.Testing | locator、wait、assertion、remote接続のengine共通API | 外部.NETテスト |
Gua.Testing.Visual | PNG baseline比較と差分artifact。Godot・Unity共通 | 必要な外部.NETテスト |
Gua.Testing.Recording | Semantic操作の記録とrequest相関付きReplay。Godot・Unity共通 | 必要な外部.NETテスト |
Godot公開型
| 型 / 設定 | 公開契約 |
|---|---|
GuaAutoAdapter | attach(root)でルートControlを指定し、update(screen)で最新UIを公開。bridge、screenshot、action、reset APIも提供 |
GuaContext | GDExtensionがClassDBへ登録するnative型。frame、node、action、event、screenshot、Inspector bridgeをGDScriptへ公開 |
gua_id metadata | NodePathに依存しない安定IDをControlへ設定 |
gua_sensitive metadata | 入力値をUI snapshotと診断から除外。描画済みPNGのpixelは自動では隠さない |
GuaGodotRuntime | 共有Gua.Runtimeを使う実験的C# adapter。新規Godot統合ではGDScriptアドオンを推奨 |
Godotランタイム公開面
| ファイル | 役割 |
|---|---|
gua_auto_adapter.gd | Controlの再帰収集、状態反映、action配送、event、screenshotを担当 |
gua.gdextension | Godotへentry pointとplatform別native libraryを宣言 |
gua_godot.windows.debug.x86_64.dll | GuaContextをGodot型として登録するC++ GDExtension |
gua_runtime.dll | Gua core、request/event queue、診断、Inspector WebSocket bridgeを所有する共有runtime |
plugin.cfg / plugin.gd | Godotアドオンとして読み込むためのEditorPlugin shell |
gua_godot...はGodot/GDScript型の変換層、gua_runtime.dllはengine共通runtime層です。前者は後者へlinkするため、Windows版では両方をaddons/gua/binへ配置します。
cmake --preset windows-msvc-debug
cmake --build --preset windows-msvc-debug --target gua-godotテストホスト公開型
| 型 / member | 意味 |
|---|---|
GodotSceneTestHost.Load | 指定projectとsceneでGodotを起動し、bridgeへ接続 |
GodotSceneTestHostOptions | 実行ファイル、project path、headless、port、環境変数、reset policyを設定 |
Context / RemoteContext | locatorとactionから使う共通IGuaContext / WebSocket接続 |
CaptureScreenshot | Godot viewportのon-demand PNGを取得 |
CreateDiagnosticsSession | UI Tree、操作履歴、runtime情報、Godot stdout/stderrをartifactへ保存 |
Dispose | bridge接続を閉じ、Godot processを終了し、strict teardownを適用 |
UI写像
| role | Godot Control | 主なaction |
|---|---|---|
| button | BaseButton / Button | click, focus |
| checkbox | CheckBox | click, focus, set_checked |
| textbox | LineEdit / TextEdit | focus, set_value, press_key |
| slider | Slider / SpinBox | focus, set_value |
| combobox | OptionButton | focus, select |
| list / listitem | ItemListと各item | focus, select, scroll |
| tablist / tab | TabContainerと各tab | select |
| scrollarea | ScrollContainer | scroll |
| text / panel | Label / その他のControl | 観測のみ |
各frameでrole、label、text/value、表示・有効・focus状態、選択、range、scroll、親ID、viewport boundsを再収集します。既定IDはルートからのNodePathで、必要な箇所だけgua_idにより固定できます。
操作と完了通知
外部requestはupdate(screen)中に消費され、通常のGodot property、signal、input eventへ反映されます。処理後は同じrequestIdの結果eventを返します。clickはBaseButtonのpressed、選択はItemListやOptionButtonの選択signal、key入力はfocus中のControlへ配送されます。
press_key modifier bitは1=Shift、2=Alt、4=Control、8=Commandです。表示されていないControl、無効なControl、対応しない値やactionは成功扱いにせず、呼び出し側へ結果を返します。
エンジン共通仕様
- Semantic UI Tree、role、action/request/event、JSON SchemaはUnityを含む全adapterで共有します。
- boundsは物理viewport pixel、左上原点、右/下が正です。
- Inspector、MCP、外部テストは同じWebSocket bridgeへ接続します。既定portは
8765で、GUA_BRIDGE_PORTにより変更できます。 - screenshot要求はframe sequenceとsessionを確認して完了し、headlessやrendering無効も明示的な結果として返します。
他エンジンへ拡張する場合
Gua.Core、Gua.Runtime、Gua.Testingとprotocolは再利用できます。ただしGodotのGDExtension、GDScript、Control走査、signal処理は他engineへそのまま移せません。各engineのUI型を収集し、本来のeventへ操作を戻す専用adapterが必要です。UnityにはUnity専用APIとadapterがあります。
ライフサイクルと所有権
ゲーム側がGuaAutoAdapterを所有します。_ready()で生成してルートControlをattachし、_process()からupdate(screen)を呼びます。adapterはGDExtensionを読み込み、ClassDB.instantiate("GuaContext")でnative contextを生成します。
const GuaAutoAdapterScript := preload(
"res://addons/gua/gua_auto_adapter.gd"
)
var ui := GuaAutoAdapterScript.new()
func _ready() -> void:
ui.attach(self)
ui.start_inspector_bridge(8765)
ui.update("title")
func _process(_delta: float) -> void:
ui.update("title")main.gdサンプルの要点
| 関数 / 設定 | 役割 |
|---|---|
start_inspector_bridge_on_ready | Ready時にゲーム内WebSocket bridgeを開始するか指定 |
inspector_bridge_port | InspectorとMCPの接続port。環境変数で上書き可能 |
_ready() | UI構築、adapter attach、初回update、bridge開始 |
_process(delta) | 毎frame、最新Control状態と論理screen名を反映 |
_build_visual_e2e_controls() | 機密入力、CheckBox、OptionButtonを追加する視覚比較fixture |
_build_v2_e2e_controls() | TextEdit、選択、tab、scrollなどの操作fixture |
_capture_visual_e2e() | 描画frameを待ってviewport PNGを公開 |
利用上の注意
- 新規Godot統合ではGDScriptアドオンを使用します。実験的C# sampleは同等機能の置き換えではありません。
gua_sensitiveはsemantic値を隠しますが、画面へ描画済みの文字をPNGから自動maskしません。- 複数のGodot processを並列実行する場合は、固定portを共有せずテストごとに空きportを割り当てます。
- native DLLが無い、古い、またはplatform/CPU構成が違う場合、
GuaContextを生成できません。