AIBridge

English | 中文

AIBridge is a Unity package that gives AI coding assistants a stable CLI bridge into Unity Editor. It lets agents resolve real Unity asset paths, inspect scenes and prefabs, edit objects through Unity APIs, run Unity compilation, read Console logs, execute batch workflows, run tests, and capture screenshots or GIFs for visual verification.

The package is designed for AI-assisted Unity development where the assistant must validate changes inside the Editor, not only edit files.

Why AIBridge

Many Unity automation tools depend on a live socket or MCP session. AIBridge uses file-based command requests and result files, so work can survive script recompilation, domain reloads, editor focus changes, and restarts.

Requirements

• Unity 2019.4 or later.
• .NET 8.0 Runtime for the bundled CLI.
• Unity Editor must be running for Unity-side commands such as compile unity, asset, scene, inspector, prefab, screenshot, and get_logs.

Installation

Install with Unity Package Manager using this Git URL:

https://github.com/liyingsong99/AIBridge.git

You can also clone this repository into a Unity project's Packages folder.

Configure AI Workflow

1. Open Tools > AIBridge Settings in Unity Editor.
2. Open the Skills Installation section.
3. Select the AI tools you use.
4. Click Install Selected Integrations.
5. Optionally click Install Unity Project AGENTS.md Template to create a root AGENTS.md.

Installed integrations include the fixed CLI path, Skill routing rules, Unity compile checks, Console diagnostics, C# compatibility rules, and workflow checklists. Command references are generated under each installed Skill's references/ directory.

CLI Basics

Run commands from the Unity project root after AIBridge has copied its CLI cache:

$CLI = "./AIBridgeCache/CLI/AIBridgeCLI.exe"

On macOS/Linux, use the bundled platform executable or run the DLL with dotnet according to your project setup.

Most commands use this form:

$CLI <command> <action> [options]

CLI-only helpers differ slightly: focus has no action, and multi uses --cmd or --stdin.

Common Commands

Editor, Compile, Logs, Tests

$CLI focus
$CLI editor log --message "Hello" --logType Warning
$CLI editor get_state
$CLI compile unity
$CLI get_logs --logType Error --count 50
$CLI get_logs --logType Warning --count 50
$CLI test run --mode EditMode
$CLI test status

Use compile unity for Unity validation. compile dotnet is only an extra solution build check and is not a replacement for Unity compilation.

Assets And Scenes

$CLI asset search --mode script --keyword "Player" --format paths
$CLI asset find --filter "t:Prefab" --format paths
$CLI asset get_path --guid "abc123..."
$CLI asset read_text --assetPath "Assets/Configs/GameConfig.asset"

$CLI scene get_hierarchy --depth 3 --includeInactive false
$CLI scene get_active
$CLI scene load --scenePath "Assets/Scenes/Main.unity" --mode single
$CLI scene save

GameObjects And Transforms

$CLI gameobject create --name "MyCube" --primitiveType Cube
$CLI gameobject find --withComponent "Rigidbody" --maxResults 20
$CLI gameobject set_active --path "Player" --active true

$CLI transform get --path "Player"
$CLI transform set_position --path "Player" --x 0 --y 1 --z 0
$CLI transform look_at --path "Player" --targetPath "Enemy"
$CLI transform look_at --path "Player" --targetInstanceId 12345
$CLI transform set_sibling_index --path "Canvas/Button" --first true

Inspector And Prefabs

$CLI inspector get_components --path "Player"
$CLI inspector get_properties --path "Player" --componentName "Transform"
$CLI inspector find_property --path "Player" --componentName "Rigidbody" --keyword "mass"
$CLI inspector set_property --path "Player" --componentName "Rigidbody" --propertyName "mass" --value 10

$CLI prefab get_info --prefabPath "Assets/Prefabs/Player.prefab"
$CLI prefab get_hierarchy --prefabPath "Assets/Prefabs/Player.prefab" --includeComponents true
$CLI prefab patch --prefabPath "Assets/Prefabs/Player.prefab" --ops "AIBridgeCache/patch_ops/player_patch.json" --dryRun true

For simple prefab field edits, use inspector set_property with assetPath + objectPath + componentName. For multi-step prefab edits, use prefab patch --ops <file> and run --dryRun true first.

PowerShell JSON tip:

$values = (@{ 'm_LocalPosition.x' = 0; 'm_LocalPosition.y' = 1 } | ConvertTo-Json -Compress) -replace '"', '\"'
& "./AIBridgeCache/CLI/AIBridgeCLI.exe" inspector set_properties --assetPath 'Assets/Prefabs/Player.prefab' --componentName Transform --values $values

Batch And Multi

$CLI batch from_text --text "call editor log 'Hello'\ndelay 1000"
$CLI batch from_file --file "AIBridgeCache/scripts/setup_scene.txt"
$CLI multi --cmd "editor log --message Step1&get_logs --logType Error --count 1"

Use multi --stdin for long scripts or JSON-heavy commands:

$script = @'
editor log --message "Start"
delay 1000
get_logs --logType Error --count 1
'@
$script | & "./AIBridgeCache/CLI/AIBridgeCLI.exe" multi --stdin

Visual Verification

$CLI gameview get_resolution
$CLI gameview set_resolution --width 1920 --height 1080
$CLI gameview list_resolutions
$CLI screenshot game
$CLI screenshot gif --frameCount 50 --fps 20 --scale 0.5

Game view screenshots and GIF capture require Play Mode.

Recommended AI Work Loop

1. Resolve the real Unity asset or object path.
2. Inspect the scene, prefab, component, or SerializedProperty state.
3. Apply the smallest safe change through Unity-aware commands or source edits.
4. Run compile unity.
5. Read get_logs --logType Error.
6. Use screenshots or GIFs for visual changes.

Repository Layout

Editor/        Unity Editor commands, settings window, integrations, prefab patching
Runtime/       Runtime bridge contracts and lightweight runtime data
Tools~/       AIBridgeCLI source and bundled platform binaries
Templates~/   AI root-rule templates and Unity project AGENTS.md template
Skill~/       AIBridge Skills and workflow references
Tests/        Unity EditMode tests
Images/       README images

License

MIT License. See LICENSE.

Contributing

Issues and pull requests are welcome. When changing Unity-facing behavior, update the relevant CLI examples, Skill references, and validation notes.