
unity-cli
Unity development workflow automation: build verification, debug investigation, UI Toolkit inspection
- version
- 0.0.1
- GitHub stars
- 39
Install
/plugin install unity-cli@unity-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add bigdra50/unity-cli.
Contents
Discovered from sourceSkills 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 のフォールバック順に従う:
u -i <instance> api schema --type AssetDatabaseで対応メソッドを検索 (107メソッド)u -i <instance> api callで実行- .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 | 値 |
|---|---|
| Windows | StandaloneWindows64 |
| macOS | StandaloneOSX |
| Android | Android |
| iOS | iOS |
| WebGL | WebGL |
エラー対応
| エラー | 対応 |
|---|---|
| コンパイルエラー | /unity-verify で修正ループ |
| Missing Scene | u -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 |
| NullReferenceException | u -i <instance> scene hierarchy + u -i <instance> component inspect で参照確認 |
| MissingReferenceException | u -i <instance> asset info でアセット存在確認 |
| MissingComponentException | u -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フレーム
分析パターン
| ボトルネック | 確認方法 | 対策 |
|---|---|---|
| CPU | frames の処理時間 | ホットパスの最適化 |
| GPU | frames の描画時間 | バッチング、LOD |
| GC | frames の 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 のフォールバック順に従う:
u -i <instance> api schema --type <Type>で対応メソッドを検索u -i <instance> api callで実行- .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 後に空が返っても以下のいずれかを意味する:
- ソース変更があり再コンパイルが走り、エラー/警告がない (本当のクリーン)
- ソース未変更で再コンパイルがスキップされ、過去の警告が出力されないだけ
直前にソース編集があった文脈なら「クリーン」扱いで 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 Toolkit | uGUI |
|---|---|---|
| ファイル | .uxml, .uss | .prefab に Canvas |
| コンポーネント | UIDocument | Canvas, 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) を直接使う。
手順:
u -i <instance> play+u -i <instance> uitree dumpで構造を把握する- 操作可能な要素(ボタン名、ラベル名)を特定する
- 以下のテンプレートに従い、
tests/integration/にテストファイルを生成する 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 外からの結合テスト
手順:
- Phase 2 の pytest テストから安定したシナリオを選ぶ
- 以下のテンプレートに従い、
Assets/Tests/PlayMode/に C# テストを生成する - asmdef に UI コントローラの参照を追加する(必要に応じて)
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 のフォールバック順に従う:
u api schema --type <Type>で対応メソッドを検索u api callで実行- 該当なしの場合のみ 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 再実行」サイクル。
- 修正前にユーザー確認 (default): 以下のいずれかに該当する場合は自動修正せずユーザーに修正方針を確認する
- ファイル名 prefix が
_(例:_Broken*.cs) または "Test" "Fixture" 等を含む - エラーファイル内コメントに
intentional,TODO,FIXME,tuning等の意図的破壊を示唆する語がある - 1 回の修正で 3 ファイル以上に変更が及ぶ場合
- 既存ロジックの大幅変更が必要な場合 (型変更、API 置換、import 追加以外の構造変更)
- ファイル名 prefix が
- 自動修正可: 単純なタイプミス (セミコロン抜け、スペル間違い、import 不足) で 1 ファイル限定の場合は試行 OK
- ループ運用: 修正 → Quick Verify を最大 3 回繰り返す。3 回で解消しない場合はユーザーに状況を報告し判断を仰ぐ
- 副作用回避: 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 開発に関する公式ドキュメント、ソースコード、パッケージ情報を統合的に提供するエージェント。
ドメイン
- Unity Engine/Editor API: MonoBehaviour、GameObject、Component 等のコア API
- Unity ソースコード: UnityCsReference による実装詳細
- UPM パッケージ: Unity 公式パッケージ(uGUI、TextMeshPro、InputSystem 等)
- Unity YAML: .meta、.asset、.prefab、.unity ファイルの形式
- NuGet パッケージ: 外部 .NET ライブラリ
情報ソース
Unity 公式ドキュメント
Manual (概念説明、ワークフロー):
ScriptReference (API リファレンス):
Package Documentation:
YAML 関連ドキュメント
- https://docs.unity3d.com/Manual/FormatDescription.html
- https://docs.unity3d.com/Manual/ClassIDReference.html
- https://docs.unity3d.com/Manual/UnityYAML.html
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
アプローチ
-
プロジェクトの Unity バージョンを取得
u project infoまたは
ProjectSettings/ProjectVersion.txtを読む -
質問のドメインを判定
- API の使い方 → 公式ドキュメント
- 内部動作・実装詳細 → UnityCsReference
- パッケージ導入・依存関係 → パッケージ情報
- YAML 形式 → Manual の Format 関連ページ
-
適切な情報ソースを選択して WebFetch
- バージョンを URL に埋め込む
- 例:
https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Transform.html
-
情報が不足する場合は WebSearch で補完
-
必要に応じてローカルファイル参照
- パッケージのローカルドキュメント
- プロジェクト内のコード
出力形式
## 回答
[質問への回答]
## 参照元
- [ドキュメント名](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
アプローチ
-
プロジェクトバージョンを確認
u project infoまたは
cat ProjectSettings/ProjectVersion.txt -
要求に応じた情報を取得
- 現在の LTS 一覧 → WebSearch で最新情報
- 特定機能の対応バージョン → リリースノート参照
- アップグレード推奨 → プロジェクトバージョンと比較
-
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.3 | 2022年4月 | 2024年4月 |
| 2022.3 | 2023年5月 | 2025年5月 |
| 2023.3 | 2024年予定 | 2026年予定 |
※ 最新情報は WebSearch で確認すること
注意事項
- LTS サポート期間は変更される可能性がある
- 機能対応バージョンはプラットフォームにより異なる場合がある
- アップグレード推奨は一般的なガイドラインであり、プロジェクト固有の制約を考慮すること
Hooks 1
Sponsors
Details
- Marketplace
- bigdra50/unity-cli
- Source
- bigdra50/unity-cli
- Category
- Community