Unity development workflow automation: build verification, debug investigation, UI Toolkit inspection

version
0.0.1
GitHub stars
39

Install

/plugin install unity-cli@unity-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add bigdra50/unity-cli.

Contents

Discovered from source

Skills 9

unity-api

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。--offline オプションのみ Relay 不要 = -i 不要。

メソッド検索

u -i <instance> api schema --type AssetDatabase          # 型名でフィルタ
u -i <instance> api schema --namespace UnityEditor       # 名前空間でフィルタ
u -i <instance> api schema --method Refresh              # メソッド名で検索
u api schema --offline --type PlayerSettings              # キャッシュから (Relay 不要なので -i 不要)

メソッド呼び出し

u -i <instance> api call UnityEngine.Application get_unityVersion
u -i <instance> api call UnityEditor.AssetDatabase Refresh
u -i <instance> api call UnityEditor.AssetDatabase ImportAsset --params '["Assets/Prefabs/Player.prefab", 0]'
u -i <instance> api call UnityEditor.EditorApplication ExecuteMenuItem --params '["Window/General/Console"]'

よく使うパターン

用途コマンド
プロジェクト設定u -i <instance> api call UnityEditor.PlayerSettings get_productName
コンパイル状態u -i <instance> api call UnityEditor.EditorApplication get_isCompiling
アセット存在確認u -i <instance> api call UnityEditor.AssetDatabase AssetPathExists --params '["Assets/..."]'
フォルダ作成u -i <instance> api call UnityEditor.AssetDatabase CreateFolder --params '["Assets", "New"]'
メニュー実行u -i <instance> api call UnityEditor.EditorApplication ExecuteMenuItem --params '["Tools/..."]'

制約

  • static メソッドのみ
  • 引数: プリミティブ, string, enum, プリミティブ配列
  • UnityEngine / UnityEditor 名前空間のみ
  • [Obsolete] メソッドは除外済み

既存コマンドとの使い分け

既存コマンド (u scene, u build 等) がある操作はそちらを使う。u api は既存コマンドがカバーしない操作のためのフォールバック。

unity-asset

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

調査フロー

1. アセット情報   u -i <instance> asset info <path>
2. 依存関係      u -i <instance> asset deps <path>
3. 参照元        u -i <instance> asset refs <path>
4. 問題検出 → 修正 → /unity-verify

コマンド

アセット操作

u -i <instance> asset info "Assets/Prefabs/Player.prefab"    # 基本情報
u -i <instance> asset deps "Assets/Prefabs/Player.prefab"    # 依存先一覧
u -i <instance> asset refs "Assets/Prefabs/Player.prefab"    # 参照元一覧
u -i <instance> asset prefab "Assets/Prefabs/X.prefab" --target "X"  # Prefab 化
u -i <instance> asset scriptable-object "Assets/Data/Config.asset" --type "GameConfig"

パッケージ管理

u -i <instance> package list                           # インストール済みパッケージ
u -i <instance> package add com.unity.inputsystem      # 追加
u -i <instance> package remove com.unity.inputsystem   # 削除

CLI 非対応操作

unity-shared のフォールバック順に従う:

  1. u -i <instance> api schema --type AssetDatabase で対応メソッドを検索 (107メソッド)
  2. u -i <instance> api call で実行
  3. .meta インポート設定は YAML 直接編集

unity-build

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

ワークフロー

1. /unity-verify Quick Verify   コンパイルエラーがないことを確認
2. ビルド設定確認              u -i <instance> build settings --json
3. ビルドシーン確認            u -i <instance> build scenes --json
4. ビルド実行                  u -i <instance> build run --target <platform> --output <path>
5. 結果確認                    成功/失敗を報告

コマンド

u -i <instance> build settings --json                                # 現在の設定
u -i <instance> build scenes --json                                  # ビルドシーン一覧
u -i <instance> build run --target StandaloneWindows64 --output ./Build   # ビルド実行

プラットフォーム

target値
WindowsStandaloneWindows64
macOSStandaloneOSX
AndroidAndroid
iOSiOS
WebGLWebGL

エラー対応

エラー対応
コンパイルエラー/unity-verify で修正ループ
Missing Sceneu -i <instance> build scenes で確認、シーンパス修正
プラットフォーム未対応u -i <instance> api call UnityEditor.EditorApplication ExecuteMenuItem --params '["File/Build Settings"]'

unity-debug

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

調査フロー

1. エラー取得      u -i <instance> console get -l E,X | head -20
2. エラー分類      → コンパイルエラー / ランタイムエラー / Missing 系
3. コンテキスト収集  u -i <instance> scene hierarchy / u -i <instance> component inspect / u -i <instance> screenshot
4. 原因特定 → 修正 → /unity-verify で検証

エラー分類と対応

エラー種別対応
CS0XXX (コンパイルエラー)コード修正 → /unity-verify
NullReferenceExceptionu -i <instance> scene hierarchy + u -i <instance> component inspect で参照確認
MissingReferenceExceptionu -i <instance> asset info でアセット存在確認
MissingComponentExceptionu -i <instance> component list で確認 → u -i <instance> component add

コンソール操作

u -i <instance> console get                   # 全ログ
u -i <instance> console get -l E | head -10   # Error のみ、先頭10件
u -i <instance> console get -l E,W            # Error + Warning
u -i <instance> console clear                 # ログクリア

状態確認

u -i <instance> screenshot          # エディタのスクリーンショット
u -i <instance> scene hierarchy     # 現在のシーン構造
u -i <instance> state               # Play/Pause/Compile 状態

コンパイルエラーが解決しない場合は /unity-verify に切り替える。

unity-perf

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

プロファイリングフロー

1. /unity-verify Quick Verify             コンパイルエラーがないことを確認
2. u -i <instance> play                   Play Mode 開始
3. u -i <instance> profiler start         プロファイリング開始
4. 計測 (数秒〜数十秒)
5. u -i <instance> profiler snapshot      スナップショット取得
   u -i <instance> profiler frames --count 10   フレームデータ取得
6. u -i <instance> profiler stop          停止
7. u -i <instance> stop                   Play Mode 終了
8. 分析 → 最適化提案

コマンド

u -i <instance> profiler start                  # 開始
u -i <instance> profiler stop                   # 停止
u -i <instance> profiler snapshot               # 現在のスナップショット
u -i <instance> profiler frames --count 10      # 直近Nフレーム

分析パターン

ボトルネック確認方法対策
CPUframes の処理時間ホットパスの最適化
GPUframes の描画時間バッチング、LOD
GCframes の GC Allocオブジェクトプール、struct 化
メモリsnapshot のメモリ使用量アセット圧縮、参照整理

最適化チェックリスト

  • Update/LateUpdate 内の毎フレーム Alloc
  • GetComponent の繰り返し呼び出し
  • 文字列結合 (+ 演算子)
  • LINQ in Update
  • 不要な SetActive 切り替え

unity-scene

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

ワークフロー

1. 現状把握     u -i <instance> scene active / u -i <instance> scene hierarchy
2. オブジェクト  u -i <instance> gameobject create / find / modify / delete
3. コンポーネント u -i <instance> component add / modify / inspect / list
4. Prefab化     u -i <instance> asset prefab <path> --target <name>
5. シーン保存   u -i <instance> scene save

コマンドリファレンス

Scene

u -i <instance> scene active                    # アクティブシーン情報
u -i <instance> scene hierarchy --depth 2       # 階層表示
u -i <instance> scene load --path "Assets/..."  # シーン読み込み
u -i <instance> scene save                      # 保存

GameObject

u -i <instance> gameobject create "Player"                          # 空オブジェクト
u -i <instance> gameobject create "Cube" --primitive Cube           # プリミティブ
u -i <instance> gameobject find --name "Player"                     # 検索
u -i <instance> gameobject modify -n "Player" --position 0,1,0      # Transform変更
u -i <instance> gameobject delete -n "Player"                       # 削除

Component

u -i <instance> component list -t "Player"                                      # 一覧
u -i <instance> component inspect -t "Player" -T Rigidbody                      # 詳細
u -i <instance> component add -t "Player" -T Rigidbody                          # 追加
u -i <instance> component modify -t "Player" -T Rigidbody --prop mass --value 2 # 変更
u -i <instance> component remove -t "Player" -T Rigidbody                       # 削除

Asset

u -i <instance> asset prefab "Assets/Prefabs/Player.prefab" --target "Player"  # Prefab化
u -i <instance> asset info "Assets/Prefabs/Player.prefab"                       # 情報

CLI 非対応操作

unity-shared のフォールバック順に従う:

  1. u -i <instance> api schema --type <Type> で対応メソッドを検索
  2. u -i <instance> api call で実行
  3. .meta インポート設定等は YAML 直接編集

unity-shared

全 unity-* スキルが従う共通ルール。

インスタンス指定 (必須)

unity-* スキル経由で u コマンドを呼ぶ際は 必ず -i <instance> を付ける。default インスタンスに依存しない。

u -i <instance> refresh    # OK
u refresh                  # NG (skill 経由では使わない)

<instance> はユーザーから渡される or 親セッションが指定する値で置き換える。u instances で接続中 Unity 一覧を確認できる。本ドキュメント以下のサンプルでは <instance> をそのまま使うが、実行時は具体名 (例: TestProject) に置換する。

理由: 複数 Unity 接続環境で誤ったインスタンスへコマンドを送るリスクと、subagent 間の挙動を default 依存にしないため。

接続確認

u instances             # 接続中 Unity 一覧
u -i <instance> state   # 特定エディタの状態

接続不可時: unity-relay --port 6500 で Relay 起動。

Quick Verify

コード変更後に毎回実行する検証シーケンス。順序厳守 (clear は refresh の前に置く。後にすると refresh の診断ログを消してしまう)。

# 1. 既存ログをクリア (refresh の診断を残すため refresh の前)
u -i <instance> console clear

# 2. AssetDatabase リフレッシュ (コンパイルトリガー)
u -i <instance> refresh

# 3. isCompiling が false になるまでポーリング (2秒間隔, 最大30秒)
for _ in $(seq 1 15); do
  u -i <instance> state --json | jq -e '.isCompiling == false' >/dev/null && break
  sleep 2
done

# 4. Error/Warning 取得 (--count は deprecated. head -N を使う)
u -i <instance> console get -l E,W | head -50

u state --json の出力例 (抜粋, キーはトップレベル):

{"isCompiling": false, "isPlaying": false, "isPaused": false}
  • Error あり → 修正して再実行 (最大3回)
  • Warning のみ → 報告して続行

注記: 空 (0 行) は「クリーン」だが「Warning が無い」とは限らない

Unity はインクリメンタルコンパイルのため、ソース未変更で refresh を呼んでも再コンパイルは走らず、過去の Warning は再出力されない。console clear 後に空が返っても以下のいずれかを意味する:

  1. ソース変更があり再コンパイルが走り、エラー/警告がない (本当のクリーン)
  2. ソース未変更で再コンパイルがスキップされ、過去の警告が出力されないだけ

直前にソース編集があった文脈なら「クリーン」扱いで OK。過去の警告を確実に確認したい場合は対象ファイルの touch (touch Assets/.../Foo.cs) で mtime を更新してから refresh するか、Library/ScriptAssemblies/ をクリアする。

フォールバック順

CLI 非対応の操作を行う場合:

1. u -i <instance> <既存コマンド>           最優先
2. u -i <instance> api call Type Method    5,243 メソッド対応
3. YAML 直接編集                            最終手段 (.meta インポート設定等)

セキュリティ

  • u api call は UnityEngine / UnityEditor のみ許可
  • 破壊的操作の実行前にユーザー確認

unity-ui

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

uitree コマンドは Play Mode 中のみ動作する。必ず u -i <instance> play してから実行すること。

UI テストの種別

種別検証内容手法スクショ
Functional操作→状態が正しいかclick → text で値検証不要
Visual Regression外観が変わっていないかscreenshot → 画像比較必要
Structural Snapshotツリー構造が変わっていないかdump --json → diff不要
Smoke最低限動くかclick → console にエラーなし任意
Monkeyランダム操作でクラッシュしないかmonkey → errors 確認不要

UI システム判定

手がかりUI ToolkituGUI
ファイル.uxml, .uss.prefab に Canvas
コンポーネントUIDocumentCanvas, RectTransform

コマンドリファレンス

要素の指定方法は2通り: ref ID (ref_3) または -p <panel> -n <name>。

構造把握

u -i <instance> uitree dump                           # 全パネル一覧 (contextType: Player がゲーム側)
u -i <instance> uitree dump -p "PanelSettings"        # パネルのツリー (各要素の ref/name/type/classes が見える)
u -i <instance> uitree dump -p "PanelSettings" --json # JSON 出力 (snapshot用)
u -i <instance> uitree query -p "PanelSettings" -t Button              # type で検索 (VisualElement ベースのボタンはヒットしない → -c で検索)
u -i <instance> uitree query -p "PanelSettings" -n "BtnStart"          # name で検索
u -i <instance> uitree query -p "PanelSettings" -c "action-btn"        # USS class で検索
u -i <instance> uitree query -p "PanelSettings" -t Button -c "primary" # AND 条件
u -i <instance> uitree inspect -p "PanelSettings" -n "BtnStart"        # 要素詳細
u -i <instance> uitree inspect ref_5_48                                # ref ID で指定
u -i <instance> uitree inspect ref_5_48 --style                        # resolvedStyle 含む
u -i <instance> uitree inspect ref_5_48 --children                     # 子要素情報含む

テキスト取得

u -i <instance> uitree text -p "PanelSettings" -n "ToastMessage"  # name で指定
u -i <instance> uitree text ref_5_12                               # ref ID で指定

操作

u -i <instance> uitree click -p "PanelSettings" -n "BtnContinue"  # name で指定
u -i <instance> uitree click ref_5_48                              # ref ID で指定
u -i <instance> uitree click ref_5_48 --count 2                    # ダブルクリック
u -i <instance> uitree click ref_5_48 --button 1                   # 右クリック
u -i <instance> uitree scroll -p "PanelSettings" -n "ScrollArea" --y 100

モンキーテスト

u -i <instance> uitree monkey -p "PanelSettings" -c "action-btn" --count 50 --seed 42
u -i <instance> uitree monkey -p "PanelSettings" --duration 30 --seed 42
u -i <instance> uitree monkey -p "PanelSettings" -c "action-btn" --stop-on-error --json

query でフィルタした要素をランダムに click し、コンソールエラーを監視する。 -c (USS class) か -t (type) のフィルタが必須(フィルタなしでは要素が見つからない)。 事前に u -i <instance> uitree query -p <panel> -c <class> で有効な class 名を確認してから monkey に渡す。 --seed で操作順を再現可能。

スナップショット

u -i <instance> uitree snapshot save -p "PanelSettings" --name baseline    # 現在のツリーを保存
u -i <instance> uitree snapshot diff -p "PanelSettings" --name baseline    # baseline との差分
u -i <instance> uitree snapshot list                                        # 保存済み一覧
u -i <instance> uitree snapshot delete --name baseline                      # 削除

diff 出力: 要素の追加(+)/削除(-)/classes 変化(~) を検出。

スクリーンショット

u -i <instance> screenshot                          # GameView (-s game がデフォルト)
u -i <instance> screenshot -p "ui-check.png"        # 保存先指定
u -i <instance> screenshot --burst -n 5             # 連続 (アニメーション確認)

UI Toolkit / uGUI (Screen Space) は -s game でのみ映る。-s camera では映らない。

GameView のキャプチャにはエディタのフォーカスが必要。タイムアウトする場合は再試行で解決することが多い。

uGUI の場合

uitree は UI Toolkit 専用。uGUI は scene/component コマンドで操作する。

u -i <instance> scene hierarchy --depth 3
u -i <instance> component list -t "Canvas"
u -i <instance> component inspect -t "MyButton" -T "UnityEngine.UI.Button"

開発→テストフロー

Phase 1: 作成 & 手動確認
  コード変更 → /unity-verify → play → dump → 操作 → screenshot → stop

Phase 2: pytest E2E テスト生成
  dump で構造把握 → pytest テストファイルを生成 → 実行して確認

Phase 3: PlayMode テスト移植
  安定したシナリオを C# に書き直す → CI で回帰テスト

Phase 1: 作成 & 手動確認

u -i <instance> play
u -i <instance> uitree dump -p "PanelSettings"                 # 構造把握
u -i <instance> uitree click -p "PanelSettings" -n "BtnStart"  # 操作
u -i <instance> uitree text -p "PanelSettings" -n "StatusLabel" # 状態確認
u -i <instance> screenshot                                      # 結果キャプチャ
u -i <instance> stop

Phase 2: pytest E2E テスト生成

Phase 1 で確認した操作シナリオを、pytest テストとして永続化する。 unity-cli の Python API (UITreeAPI, ConsoleAPI, EditorAPI) を直接使う。

手順:

  1. u -i <instance> play + u -i <instance> uitree dump で構造を把握する
  2. 操作可能な要素(ボタン名、ラベル名)を特定する
  3. 以下のテンプレートに従い、tests/integration/ にテストファイルを生成する
  4. uv run python -m pytest tests/integration/<file> -v で実行して確認する

テンプレート:

"""E2E tests for <UI名> — pytest + unity-cli API."""
import time
import pytest
from unity_cli.api import ConsoleAPI, EditorAPI, UITreeAPI
from unity_cli.client import RelayConnection

PANEL = "<パネル名>"  # u uitree dump で確認したパネル名


@pytest.fixture(scope="module")
def conn() -> RelayConnection:
    conn = RelayConnection(instance="<プロジェクト名>", timeout=5.0)
    try:
        EditorAPI(conn).get_state()
    except Exception:
        pytest.skip("Relay not available")
    return conn


@pytest.fixture(scope="module")
def uitree(conn: RelayConnection) -> UITreeAPI:
    return UITreeAPI(conn)


@pytest.fixture(scope="module")
def console(conn: RelayConnection) -> ConsoleAPI:
    return ConsoleAPI(conn)


@pytest.fixture(scope="module")
def editor(conn: RelayConnection) -> EditorAPI:
    return EditorAPI(conn)


@pytest.fixture(autouse=True)
def _play_mode(editor: EditorAPI):
    """Play Mode に入る。"""
    state = editor.get_state()
    if not state.get("isPlaying"):
        editor.play()
        deadline = time.time() + 10
        while time.time() < deadline:
            if editor.get_state().get("isPlaying"):
                break
            time.sleep(0.5)
    yield


@pytest.fixture(scope="module", autouse=True)
def _stop_after_all(editor: EditorAPI):
    """全テスト後に Play Mode 終了。"""
    yield
    try:
        editor.stop()
    except Exception:
        pass


# --- Functional テスト ---

class TestMenuButtons:
    def test_continue_shows_toast(self, uitree: UITreeAPI) -> None:
        uitree.click(panel=PANEL, name="<ボタン名>")
        time.sleep(0.3)
        result = uitree.text(panel=PANEL, name="<ラベル名>")
        assert result["text"] == "<期待値>"


# --- Smoke テスト ---

class TestSmoke:
    BUTTONS = ["<ボタン1>", "<ボタン2>", ...]

    def test_all_clickable_without_errors(self, uitree: UITreeAPI, console: ConsoleAPI) -> None:
        console.clear()
        for btn in self.BUTTONS:
            uitree.click(panel=PANEL, name=btn)
            time.sleep(0.2)
        errors = console.get(types=["error"])
        assert errors.get("entries", []) == []


# --- Structural Snapshot ---

class TestStructure:
    def test_tab_switch_changes_tree(self, uitree: UITreeAPI) -> None:
        before = uitree.dump(panel=PANEL)
        uitree.click(panel=PANEL, name="<タブ名>")
        time.sleep(0.3)
        after = uitree.dump(panel=PANEL)
        assert before != after

既存の conftest.py に conn, uitree, editor, console fixture がある場合はテンプレートの fixture 定義を省略し、conftest に委譲する。fixture の scope は conftest に合わせる(conftest が session なら _play_mode 等も同じ scope か互換性のある scope にする)。

動的な値(タイムスタンプ、プログレス%等)を持つラベルは等値比較ではなくフォーマット検証を使う:

assert result["text"].endswith("%")  # "65%" 等

テストの種別に応じてクラスを追加する:

  • TestMenuButtons — Functional (click → text 検証)
  • TestSmoke — 全ボタンクリック + エラーなし
  • TestStructure — ツリー構造の変化検出
  • TestMonkey — ランダム操作でエラーなし
  • TestVisual — screenshot 撮影(画像比較は手動 or 別ツール)

Monkey テスト例:

from unity_cli.api.uitree_monkey import MonkeyRunner

class TestMonkey:
    def test_random_clicks_no_errors(self, uitree: UITreeAPI, console: ConsoleAPI) -> None:
        # MonkeyRunner.run() は MonkeyResult を返す。errors は list[dict]
        runner = MonkeyRunner(uitree, console)
        result = runner.run(panel=PANEL, class_filter="<操作対象class>", count=50, seed=42, interval=0.2)
        assert result.errors == [], f"Monkey errors: {result.errors}"

Snapshot テスト例:

from unity_cli.api.uitree_snapshot import SnapshotStore

class TestSnapshot:
    def test_save_and_diff_no_changes(self, uitree: UITreeAPI, tmp_path) -> None:
        store = SnapshotStore(snapshot_dir=tmp_path / "snapshots")
        data = uitree.dump(panel=PANEL, format="json")
        store.save("baseline", data)
        current = uitree.dump(panel=PANEL, format="json")
        # diff(name, current): name は保存済みスナップショット名、current は比較対象のツリーデータ
        result = store.diff("baseline", current)
        assert result["added"] == []
        assert result["removed"] == []
        assert result["changed"] == []

monkey テストの前にUIを初期状態に戻す(前のテストの副作用で Toast 等のクラスが変わることがある)。time.sleep(2) で Toast の hidden 復帰を待つか、テスト順序に依存しない assertion を使う。

Phase 3: PlayMode テスト移植

Phase 2 の pytest で安定したシナリオを C# PlayMode テストに書き直す。

PlayMode に移植する基準:

  • CI で毎回回す回帰テスト
  • フレーム精度が必要 (アニメーション完了待ち等)
  • Assert で厳密に状態検証
  • InputSystem / EventSystem 経由の操作

pytest E2E のまま残す基準:

  • 探索的テスト (シナリオが毎回変わる)
  • AI エージェントの自律テスト
  • Unity 外からの結合テスト

手順:

  1. Phase 2 の pytest テストから安定したシナリオを選ぶ
  2. 以下のテンプレートに従い、Assets/Tests/PlayMode/ に C# テストを生成する
  3. asmdef に UI コントローラの参照を追加する(必要に応じて)
  4. u -i <instance> tests run play で実行して確認する

テンプレート:

using System.Collections;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;
using UnityEngine.UIElements;

namespace Game.Tests.PlayMode
{
    [TestFixture]
    public class <UI名>Tests
    {
        private GameObject _hudObject;
        private UIDocument _uiDocument;
        private VisualElement _root;

        [UnitySetUp]
        public IEnumerator SetUp()
        {
            // UIDocument を持つ GameObject を生成
            // コントローラが Awake/OnEnable で初期化するのを待つ
            _hudObject = new GameObject("TestHUD");
            _hudObject.AddComponent<<コントローラ名>>();
            _uiDocument = _hudObject.GetComponent<UIDocument>();

            // コルーチン初期化 (StartCoroutine in OnEnable 等) は1フレームでは完了しない
            // 2フレーム以上待つ
            yield return null;
            yield return null;

            _root = _uiDocument.rootVisualElement;
            Assert.IsNotNull(_root, "Root visual element should be initialized");
        }

        [TearDown]
        public void TearDown()
        {
            Object.Destroy(_hudObject);
        }

        // --- Functional テスト ---

        [UnityTest]
        public IEnumerator <ボタン名>_Shows<期待される動作>()
        {
            var btn = _root.Q("<ボタン名>");
            Assert.IsNotNull(btn);

            Click(btn);
            yield return null;

            var label = _root.Q<Label>("<ラベル名>");
            Assert.AreEqual("<期待値>", label.text);
        }

        // --- Smoke テスト ---

        [UnityTest]
        public IEnumerator AllButtons_ClickableWithoutErrors()
        {
            var buttons = new[] { "<ボタン1>", "<ボタン2>", ... };

            foreach (var name in buttons)
            {
                var element = _root.Q(name);
                Assert.IsNotNull(element, $"{name} should exist");
                Click(element);
                yield return null;
            }

            LogAssert.NoUnexpectedReceived();
        }

        // --- ヘルパー ---

        private static void Click(VisualElement element)
        {
            using var evt = ClickEvent.GetPooled();
            evt.target = element;
            element.panel.visualTree.SendEvent(evt);
        }
    }
}

Click ヘルパーの注意:

  • ClickEvent.GetPooled() で座標計算不要のイベントを生成し、panel.visualTree.SendEvent で発火する
  • NavigationSubmitEvent では RegisterCallback<ClickEvent> が反応しないため使わない
  • ホバーやプレスエフェクトも再現したい場合は PointerDownEvent + PointerUpEvent を worldBound.center 座標付きで送る

asmdef の注意:

  • テスト対象クラスが Assembly-CSharp(asmdef なし)にある場合、テスト asmdef からは直接参照できない
  • 対象クラスに専用 asmdef を作成し、テスト asmdef の references に追加する
  • 例: Assets/UI/Game.UI.asmdef を作成 → Game.Tests.PlayMode.asmdef の references に "Game.UI" を追加

Phase 2 の pytest テストの各テストメソッドを1対1で C# に移植する。

移植後は u -i <instance> tests run play で実行。

CLI 非対応操作

unity-shared のフォールバック順に従う:

  1. u api schema --type <Type> で対応メソッドを検索
  2. u api call で実行
  3. 該当なしの場合のみ YAML 直接編集

unity-verify

PREREQUISITE: ../unity-shared/SKILL.md(Relay Server 経由で Unity Editor が起動/アクティブであること)

Quick Verify

コード変更するたびに実行。unity-shared の Quick Verify (#quick-verify) を参照。skill 経由のコマンドは必ず -i <instance> を付ける (unity-shared #インスタンス指定)。

u -i <instance> console clear
→ u -i <instance> refresh
→ isCompiling ポーリング (2s 間隔, 最大 30s)
→ u -i <instance> console get -l E,W | head -50

結果判定

u console get の出力に対して以下のテーブルで判定。出力ゼロ行 = エラー無しとして扱う (空 = OK)。

出力内容判定次のアクション
空 (0 行)クリーン完了。次工程 (Full Verify 等) に進める
[ERROR] 行のみ無し + [WARN] 行ありクリーン (Warning 許容)Warning を 1〜3 行に要約してユーザー報告、続行
[ERROR] 行ありエラー下記「修正ループ」へ

-l E,W は Error + Warning 両方を取得する。Warning だけなら続行可、Error が 1 件でもあれば停止して修正ループに入る。

修正ループ (Error 検出時)

最大 3 回までの「修正 → Quick Verify 再実行」サイクル。

  1. 修正前にユーザー確認 (default): 以下のいずれかに該当する場合は自動修正せずユーザーに修正方針を確認する
    • ファイル名 prefix が _ (例: _Broken*.cs) または "Test" "Fixture" 等を含む
    • エラーファイル内コメントに intentional, TODO, FIXME, tuning 等の意図的破壊を示唆する語がある
    • 1 回の修正で 3 ファイル以上に変更が及ぶ場合
    • 既存ロジックの大幅変更が必要な場合 (型変更、API 置換、import 追加以外の構造変更)
  2. 自動修正可: 単純なタイプミス (セミコロン抜け、スペル間違い、import 不足) で 1 ファイル限定の場合は試行 OK
  3. ループ運用: 修正 → Quick Verify を最大 3 回繰り返す。3 回で解消しない場合はユーザーに状況を報告し判断を仰ぐ
  4. 副作用回避: 1 回の修正は 1 ファイル単位。無関係な変更 (フォーマット整形、リファクタ) を混ぜない

Full Verify

ユーザーが要求した場合のみ。Quick Verify + EditMode テスト。

Quick Verify 実行
→ クリーン (Error 0、Warning は許容) なら u -i <instance> tests run edit → 結果確認
→ Fail あり: 報告、修正して Quick Verify から再実行 (修正ループの規定に従う)

Runtime Check

要求された場合のみ。Play Mode でランタイムエラーを検出。

u -i <instance> console clear
→ u -i <instance> play
→ isPlaying ポーリング
→ 3秒待機
→ u -i <instance> console get -l +E+X
→ u -i <instance> stop

報告のみ。自動修正せずユーザーに判断を委ねる。

Auto-trigger

以下の編集後に Quick Verify を自動実行:

  • .cs / .shader / .compute
  • .asmdef / .asmref
  • Unity パッケージ関連 (package.json / manifest.json)

スキップ: コメントのみの変更、プロジェクト外ファイル、ユーザー指示。

Agents 2

Unity Guide Agent

Unity 開発に関する公式ドキュメント、ソースコード、パッケージ情報を統合的に提供するエージェント。

ドメイン

  1. Unity Engine/Editor API: MonoBehaviour、GameObject、Component 等のコア API
  2. Unity ソースコード: UnityCsReference による実装詳細
  3. UPM パッケージ: Unity 公式パッケージ(uGUI、TextMeshPro、InputSystem 等)
  4. Unity YAML: .meta、.asset、.prefab、.unity ファイルの形式
  5. NuGet パッケージ: 外部 .NET ライブラリ

情報ソース

Unity 公式ドキュメント

Manual (概念説明、ワークフロー):

ScriptReference (API リファレンス):

Package Documentation:

YAML 関連ドキュメント

Unity ソースコード (UnityCsReference)

Base URL: https://github.com/Unity-Technologies/UnityCsReference

よく参照するパス:

  • Runtime/Export/Scripting/{ClassName}.cs (MonoBehaviour, Component)
  • Runtime/Export/Director/{Name}.bindings.cs (PlayableGraph)
  • Editor/Mono/Inspector/{Name}Inspector.cs (カスタムインスペクタ)
  • Editor/Mono/GUI/{Name}.cs (エディタ GUI)
  • Modules/UI/Core/{Component}.cs (uGUI)
  • Modules/UIElements/{Name}.cs (UI Toolkit)

GitHub Search API でファイルパス特定:

https://api.github.com/search/code?q={ClassName}+repo:Unity-Technologies/UnityCsReference+extension:cs

パッケージ情報

ローカル UPM:

  • ./Library/PackageCache/{package}@{version}/README.md
  • ./Library/PackageCache/{package}@{version}/package.json
  • ./Library/PackageCache/{package}@{version}/CHANGELOG.md

レジストリ:

  • Unity Registry: packages.unity.com
  • OpenUPM: openupm.com/packages/
  • NuGet: nuget.org/packages/

ローカル NuGet:

  • ./Assets/packages.config

アプローチ

  1. プロジェクトの Unity バージョンを取得

    u project info
    

    または ProjectSettings/ProjectVersion.txt を読む

  2. 質問のドメインを判定

    • API の使い方 → 公式ドキュメント
    • 内部動作・実装詳細 → UnityCsReference
    • パッケージ導入・依存関係 → パッケージ情報
    • YAML 形式 → Manual の Format 関連ページ
  3. 適切な情報ソースを選択して WebFetch

    • バージョンを URL に埋め込む
    • 例: https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Transform.html
  4. 情報が不足する場合は WebSearch で補完

  5. 必要に応じてローカルファイル参照

    • パッケージのローカルドキュメント
    • プロジェクト内のコード

出力形式

## 回答

[質問への回答]

## 参照元

- [ドキュメント名](URL)
- [ソースファイル](GitHub URL)

## 関連情報

- [追加で参考になる情報]

ガイドライン

  • 公式ドキュメントを優先(推測より事実)
  • ソースコードは「ドキュメントにない詳細」の補完として使用
  • 簡潔でアクション指向の回答
  • 具体例・コードスニペットを含める
  • 参照元 URL を明示
  • 関連機能をプロアクティブに提案

使用例

Q: Transform.SetParent と parent プロパティの違いは?
→ ScriptReference で Transform を確認
→ UnityCsReference で実装を確認
→ worldPositionStays パラメータの挙動を説明

Q: .prefab ファイルの m_Modifications の形式は?
→ Manual の PrefabInstanceModifications を確認
→ 形式と意味を説明

Q: com.unity.inputsystem の使い方は?
→ Package Documentation を確認
→ ローカルの Library/PackageCache も参照

Version Checker Agent

Unity バージョン情報と機能対応表を取得するエージェント。

役割分担

情報取得方法
プロジェクトの Unity バージョンunity-cli (u project info) または ProjectSettings/ProjectVersion.txt
外部バージョン情報このエージェント

情報ソース

Unity リリース情報

リリースアーカイブ:

リリースノート:

LTS 情報:

バージョン命名規則

2022.3.45f1
│    │ │ │
│    │ │ └── パッチタイプ (f=final, p=patch, b=beta, a=alpha)
│    │ └──── パッチ番号
│    └────── マイナーバージョン (1=Tech Stream, 2=Tech Stream, 3=LTS)
└─────────── メジャーバージョン (年)

LTS の判定:

  • マイナーバージョンが .3 なら LTS
  • 例: 2022.3.x は LTS、2022.1.x は Tech Stream

アプローチ

  1. プロジェクトバージョンを確認

    u project info
    

    または

    cat ProjectSettings/ProjectVersion.txt
    
  2. 要求に応じた情報を取得

    • 現在の LTS 一覧 → WebSearch で最新情報
    • 特定機能の対応バージョン → リリースノート参照
    • アップグレード推奨 → プロジェクトバージョンと比較
  3. WebFetch / WebSearch で外部情報を取得

出力形式

バージョン情報

## Unity Version Information

### Current Project
- Version: 2022.3.45f1
- Type: LTS

### Latest Versions
- LTS: 2022.3.50f1
- Tech Stream: 2023.2.15f1

### Recommendation
[アップグレード推奨またはそのまま継続]

機能対応バージョン

## Feature Availability

### [機能名]
- Introduced: 2021.2
- Stable: 2022.1
- Current Project: [対応/非対応]

### Notes
[注意事項があれば]

使用例

Q: 現在の LTS バージョンは?
→ WebSearch で Unity LTS を検索
→ 最新の LTS バージョン一覧を返す

Q: C# 10 はいつから使える?
→ リリースノートを検索
→ 対応バージョンを特定

Q: このプロジェクトをアップグレードすべき?
→ u project info でバージョン確認
→ 最新 LTS と比較
→ セキュリティパッチの有無を確認
→ 推奨を提示

LTS サポートスケジュール参考

バージョンLTS 開始サポート終了予定
2021.32022年4月2024年4月
2022.32023年5月2025年5月
2023.32024年予定2026年予定

※ 最新情報は WebSearch で確認すること

注意事項

  • LTS サポート期間は変更される可能性がある
  • 機能対応バージョンはプラットフォームにより異なる場合がある
  • アップグレード推奨は一般的なガイドラインであり、プロジェクト固有の制約を考慮すること

Sponsors

Details

Marketplace
bigdra50/unity-cli
Source
bigdra50/unity-cli
Category
Community