パッケージの選び方
| パッケージ | 責務 | target |
|---|---|---|
com.link1345.gua | Unityプロジェクトへ導入するUPMパッケージ。自動起動、UI収集、操作、screenshotに対応 | Unity 6000.0+ |
Gua.Runtime | 別のengine adapterを実装するときに使う共有runtime API | net10.0 / netstandard2.1 |
Gua.Testing.Unity | 外部.NETテストからUnity Editor/Playerをbuild・起動・接続 | net10.0 / netstandard2.1 |
Gua.Testing | locator、assertion、remote接続、screenshotのengine共通テストAPI | engine非依存 |
Gua.Testing.Visual | Unityを含む任意のGua contextでPNG baseline比較と差分artifactを追加 | net10.0 / netstandard2.1 |
Gua.Testing.Recording | Unityを含む任意のGua contextでSemantic操作を記録・Replay | net10.0 / netstandard2.1 |
Unity公開型
| 型 | 公開契約 |
|---|---|
GuaUnityRuntime | 自動起動するMonoBehaviour。EnsureStarted()と手動frame用RunFrame() |
GuaId | uGUI/TMP GameObjectへ安定したValueを与える任意Component |
GuaScreen | 現在の論理screen名をValueで上書き。無ければactive scene名/path |
IGuaUnityControlAdapter | 独自uGUI系ControlのTryDescribe/TryApply |
GuaUnityAdapterRegistry | Register(adapter)でControlアダプターを追加 |
GuaUnityKeyEvent | protocol key/modifierをUnity Eventへ変換 |
Gua.Runtime公開面
通常のUnity利用ではUPMパッケージがこの層を管理するため、直接呼び出す必要はありません。独自のengine adapterを作る場合、GuaRuntimeがnative runtimeを生成・所有し、Dispose()でbridgeとnative handleを破棄します。主要memberはStartInspectorBridge/StopInspectorBridge、SetAdapterVersion、BeginFrame/EndFrame、RegisterNode、TryConsumeAction/EmitActionResult、TryConsumeScreenshotRequest/CompleteScreenshot、AddLog、GetUiTreeJson、GetVersionJsonです。
テストホスト公開型
| 型 / member | 意味 |
|---|---|
UnityPlayerBuilder.Build | 指定sceneからWindows64 Mono Playerをbatch build |
UnitySceneTestHost.LoadPlayer | headless Playerを起動 |
LoadRenderedPlayer | 描画付きPlayerを起動 |
LoadEditor | StartPlayMode editor commandでsceneを開始 |
BuildAndLoadPlayer | buildと起動を一括実行 |
Context / RemoteContext | 共通IGuaContext / Unity WebSocket context |
CaptureScreenshot | frame sequence以後のon-demand PNGを待機 |
CreateDiagnosticsSession | 共通artifactにUnity log/process metadataを追加 |
UI写像
| role | UI Toolkit | uGUI / TMP | 主なaction |
|---|---|---|---|
| button | Button | Button / TMP label付きButton | click, focus |
| checkbox | Toggle | Toggle | click, focus, set_checked |
| textbox | TextField | InputField / TMP_InputField | focus, set_value, press_key |
| slider | Slider / SliderInt | Slider | focus, set_value |
| combobox | DropdownField | Dropdown / TMP_Dropdown | focus, select |
| list / listitem | ListViewと全itemsSource | 標準自動写像なし | focus, select, scroll |
| tablist / tab | TabView / Tab | 標準自動写像なし | select |
| scrollarea | ScrollView | ScrollRect | scroll |
| text / panel | Label / その他 | Text・TMP_Text / その他 | 観測のみ |
各frameでrole、label、text/value、visible、enabled、focused、checkboxのchecked、ListView itemのselected、slider range、parentId、boundsを再収集します。ListViewはvirtualizeされて画面外のitemもnodeを作りますが、未realize itemはvisible: falseかつbounds 0になります。
操作と完了通知
外部requestは対象roleが宣言するactionだけ消費されます。Unityの同期listenerが戻った後、同じrequestIdの結果eventを返します。coroutine、async void、次frameの完了までは待ちません。不正な数値・選択肢・keyはinvalid_value、実装していない組み合わせはunsupportedです。例外はruntime logとUnity Consoleへ出し、失敗結果へ変換します。
press_key modifier bitは1=Shift、2=Alt、4=Control、8=Commandです。Enter、Esc、Arrow*はUnityのKeyCode名へ正規化されます。global key requestは現在focus中のtextboxへ配送されます。
エンジン共通仕様
version_v1に任意のadapterVersionsmapを追加。UnityはUPM metadataではなく、読み込んだnative runtime versionを{"unity":"<runtime version>"}として報告します。godotPluginVersionは互換性のため残り、Godot以外ではnullです。- 全adapterのbounds座標を「物理viewport pixel、左上原点、右/下が正、NaN/Infinity禁止」と明文化しました。
GuaWebSocketContext、remote tree、captured screenshotはGua.Testingから利用できます。- native C ABIへ
gua_runtime_set_adapter_version(runtime, adapter, version)を追加。既存ABIは削除していません。 - screenshot要求のconsume後にsession resetされた場合は
stale_sessionで完了し、古い画像を新sessionへ公開しません。
ライフサイクルと所有権
BeforeSceneLoadでbootstrap driverとruntimeの2つの永続GameObjectを生成し、driverのLateUpdate()がbegin → UI収集 → end → action配送 → screenshot要求を進めます。runtime破棄時はbridgeを停止してnative handleをdisposeします。UPM artifactはGua.Core.dll、Gua.Runtime.dllと依存assembly、gua.dll、gua_runtime.dllを同梱します。
利用上の注意
- 外部から整数sliderの値を変更する必要がある画面では、現在は
SliderIntではなくSliderを使用してください。SliderIntの状態は観測できます。 - Toggleのclickは値の変更として配送されます。独自処理はpointer eventだけでなくvalue/change listenerでも受け取れるようにしてください。
- 独自Controlを登録する場合は、roleに対応するactionを
TryApplyへ実装してください。観測だけのControlでは操作用actionを持たないroleを選べます。 - Unityを並列起動するテストでは各hostが動的portを使います。同じportを固定利用する別processとの同時実行は避けてください。