| name | aibridge |
| description | Unity Editor and Player Runtime CLI integration for AIBridge. Use when Codex needs to compile Unity, inspect Console logs, search/read assets, manipulate GameObjects, Transforms, components, SerializedProperty values, scenes, screenshots/GIFs, connect to built Player runtime targets, simulate Play Mode runtime input, editor focus/menu items/game view, or look up AIBridgeCLI command syntax. For batch/multi scripts use aibridge-batch-script. For complex prefab asset edits use aibridge-prefab-patch. For unsupported direct Unity YAML serialized asset edits use unity-yaml-editing. |
AI Bridge Unity Skill
Invocation
Run commands from the Unity project root.
CLI Path: ./.aibridge/cli/AIBridgeCLI.exe
Example Alias: $CLI is a shorthand for the platform-appropriate AIBridge CLI invocation. Examples use $CLI for consistency; replace it with the matching invocation form when running commands directly.
Invocation Forms:
- Windows executable:
./.aibridge/cli/AIBridgeCLI.exe <command> [action] [options]
- macOS/Linux DLL:
dotnet ./.aibridge/cli/AIBridgeCLI.dll <command> [action] [options]
- PowerShell call operator:
& "./.aibridge/cli/AIBridgeCLI.exe" <command> [action] [options]
Most Unity-side commands require an action such as asset search or inspector set_property. CLI-only commands and helpers can differ: focus has no action, dialog uses status/click/wait, and multi uses --cmd or --stdin. Use --help or the generated command reference for the exact form.
Global Options:
--timeout <ms> - Timeout (default: 5000)--on-dialog <mode> - When a Unity command is blocked by a modal dialog, optionally wait or click: none, wait, cancel, save, discard, ok, yes, no, delete, replace--raw / --pretty - JSON output (default: raw)--json <json> / --stdin - Complex parameters--help - Show help
Cache Directory: .aibridge/ (Editor commands/results/screenshots and Runtime targets under .aibridge/runtime/targets/)
Dialog Output Rule: dialog status omits blockedByDialog and dialogs when no blocking Unity modal dialog is detected. Missing fields mean no dialog.
Operating Rules
- Use
compile unity for Unity validation. compile dotnet is an explicit extra solution-build check, not a fallback.
- For Unity assets, prefer
asset search/find --format paths; use host file reads for file contents, and asset read_text only when host reads are unavailable.
- Resource edit order: use
inspector set_property/set_properties for single or batched fields, aibridge-prefab-patch for complex Prefab structure edits it supports, Unity Editor scripts for high-level generated assets, and unity-yaml-editing only for unsupported serialized-file structure work.
- For scene objects, Prefabs, and serialized Unity assets, discover targets with
inspector get_components/get_properties/find_property, then write with AIBridge/Unity APIs when possible; avoid raw YAML unless no supported API can express the operation.
- Direct YAML edits are acceptable only after loading
unity-yaml-editing, including unsupported Scene/Prefab/ScriptableObjectTable/custom .asset operations. Preserve m_Script, fileID/guid/type references, YAML indentation, and paired .meta GUIDs; validate afterward with import, targeted inspection, compile unity, and Error logs.
- For prefab asset edits, use
assetPath + objectPath + componentName or componentIndex; componentInstanceId is scene-only.
- For complex prefab asset edits, use the
aibridge-prefab-patch skill and prefer prefab patch --ops <file> with dry-run first.
- In PowerShell, avoid inline complex
--json; build JSON in a variable, escape embedded quotes for native EXE argument passing, and pass command parameters directly, especially inspector set_properties --values $values.
focus is Windows CLI-only. dialog is CLI-only, uses Windows window APIs or macOS Accessibility permission, and omits dialog fields when no modal dialog is detected. screenshot game and screenshot gif require Play Mode; screenshot scene_view works in Edit mode when a Scene view is open.input requires Play Mode and an active EventSystem; use it with gameview, screenshot, and get_logs for UI interaction checks.
Related Resources
aibridge-prefab-patch: specialized Skill for complex prefab asset edits.aibridge-batch-script: specialized Skill for batch / multi script automation.aibridge-code-index: optional Skill for read-only semantic code lookup when Code Index is enabled.unity-yaml-editing: fallback Skill for direct UnityYAML edits when AIBridge/Unity APIs cannot express the operation.references/command-reference.md: generated CLI command syntax for common commands.references/inspector-property-reference.md: generated Inspector and SerializedProperty syntax.
Essential Commands
focus - Bring Unity to Foreground
CLI-only, Windows-only. Triggers Unity refresh/compile via Windows API.
$CLI focus
dialog - Inspect Or Click Unity Modal Dialogs
CLI-only. Use when a save/confirm modal may be blocking the Editor. Unity commands report detected dialog details instead of blindly waiting; choose an explicit dialog click or use --on-dialog for unattended handling.
$CLI dialog status
$CLI dialog click --choice cancel
$CLI dialog click --button "Don't Save"
$CLI dialog wait --timeout 5000 --click cancel
$CLI scene load --scenePath Assets/Main.unity --on-dialog cancel
multi - Execute Multiple Commands (Recommended)
Use aibridge-batch-script before writing long scripts or JSON-heavy multi --stdin commands.
$CLI multi --cmd 'editor log --message Step1&gameobject create --name Cube --primitiveType Cube'
$CLI multi --stdin
In batch/multi scripts, dialog click ok | yes | Save declares persistent dialog auto-click choices for subsequent steps; a later dialog click replaces the previous strategy. Keep the CLI invocation waiting, because --no-wait exits before it can continue clicking.
input - Runtime Input Simulation
Play Mode only. Use the generated command reference for all actions and parameters.
$CLI input click --path "Canvas/StartButton"
$CLI input drag --path "Canvas/Item" --toPath "Canvas/Slot" --frames 12
runtime - Built Player Runtime Bridge
Requires an AIBridgeRuntime component in the running Player or Play Mode scene. HTTP is the default Runtime transport; if the default HTTP port is occupied, Runtime auto-increments and writes the actual URL to the live heartbeat. LAN discovery also auto-increments from the default UDP port, and CLI defaults scan the local HTTP/discovery port ranges so multiple local Editors or built Players can be discovered. File transport remains available for Editor/local compatibility. Configure defaults in AIBridge/Settings > Runtime, and inspect live targets plus discovery cache in AIBridge/Players.
$CLI runtime list_targets
$CLI runtime status --target latest
$CLI runtime discover
$CLI runtime diagnose --target latest
$CLI runtime logs --target latest --logType Error --count 100
$CLI runtime perf --target latest --duration 5s --interval 100ms
$CLI runtime screenshot --target latest
$CLI runtime handlers --target latest
$CLI runtime call --target latest --action qa.open_panel --json "{\"panel\":\"Inventory\"}"
For multiple local Players, run $CLI runtime list_targets first and pass a specific target id such as $CLI runtime status --target AIBridgeDev_12345. $CLI runtime diagnose --target <id> diagnoses that target's resolved HTTP URL.
For remote phones, run $CLI runtime discover on the LAN first, then target the discovered id or URL. On Android USB, run adb reverse tcp:27182 tcp:27182 first, then call --transport http --url http://127.0.0.1:27182; adb is not a runtime transport mode.
Skill Version: 1.0
Package: cn.lys.aibridge
