**[English](README.md)** | **[中文](README.zh-CN.md)**

# Unity AI Bridge

**Remote-control the Unity Editor from any AI IDE — no ports, no dependencies, just works.**

[![Unity 2022.3+](https://img.shields.io/badge/Unity-2022.3%2B-black?logo=unity)](#)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/butterlatte-zhang/unity-ai-bridge?style=social)](https://github.com/butterlatte-zhang/unity-ai-bridge/stargazers)
[![Release](https://img.shields.io/github/v/release/butterlatte-zhang/unity-ai-bridge)](https://github.com/butterlatte-zhang/unity-ai-bridge/releases)
[![Glama](https://glama.ai/mcp/servers/butterlatte-zhang/unity-ai-bridge/badges/score.svg)](https://glama.ai/mcp/servers/butterlatte-zhang/unity-ai-bridge)

https://github.com/user-attachments/assets/4e8b3f85-b209-406f-a96e-f8b8eddc9160

---

## Why Unity AI Bridge?

Most AI coding assistants can read and write files, but they are **blind to the Unity Editor** — they can't inspect your scene, tweak materials, run tests, or profile performance. Unity AI Bridge gives AI full editor access.

### Key Advantages

- **65 tools, 15 categories** — Scene, GameObject, Assets, Prefab, Script, Profiler, LightProbe, Screenshot, Runtime, Tests, and more. Covers the full editor workflow, not just file I/O.
- **File-based IPC, not WebSocket** — No open ports, no firewall issues, no connection drops. Survives recompilation, play-mode transitions, and editor restarts gracefully.
- **Zero external dependencies** — Pure Python stdlib CLI/MCP server, self-contained C# Unity package. No pip install, no npm, no Node.js runtime.
- **Every major AI IDE** — Claude Code (Skill mode), Cursor, GitHub Copilot, Windsurf, Claude Desktop (MCP mode). One Unity plugin, all IDEs.
- **5-line extensibility** — Add custom tools with `[BridgeTool]` attribute. Auto-discovered, auto-serialized, auto-documented. No registration code needed.
- **Production-tested** — Built for and battle-tested in a large-scale open-world Unity game (50+ developers, 2M+ lines of C#).

### vs Unity 6 AI Gateway

Unity 6.2 introduced an official [AI Gateway](https://docs.unity3d.com/6000.2/Documentation/Manual/ai-gateway.html) with MCP support. Both projects share the same goal — giving AI agents editor access via MCP — but differ in important ways:

| | Unity AI Bridge | Unity 6 AI Gateway |
|---|---|---|
| **Unity version** | 2022.3 LTS+ | 6.2+ only |
| **Tool coverage** | 65 tools across 15 categories | General-purpose (Scene, Assets, Script, Console) |
| **Deep tooling** | Profiler (snapshot, hotpath, stream), LightProbe, Reflection, Package Manager | Not yet available |
| **IPC mechanism** | File polling (~100ms) | Unix Socket / Named Pipe |
| **Extensibility** | `[BridgeTool]` attribute — 5 lines | TBD |

In practice, the ~100ms file-polling latency is imperceptible because AI agent think-time dominates each round trip. File IPC also makes cross-process debugging trivial — just inspect the JSON files on disk.

---

## Quick Start

> **AI-native project** — Copy the prompt below and send it to your AI coding assistant. The [setup guide](docs/SETUP.md) is written for AI to follow — you don't need to run any commands yourself.
>
> ```
> Help me install Unity AI Bridge by following this guide:
> https://github.com/butterlatte-zhang/unity-ai-bridge/blob/main/docs/SETUP.md
> ```

If you prefer manual setup:

1. **Unity Package** — In Unity: *Window > Package Manager > + > Add package from git URL*:
   ```
   https://github.com/butterlatte-zhang/unity-ai-bridge.git?path=Packages/com.aibridge.unity
   ```
   Or manually copy `Packages/com.aibridge.unity` from this repo into your project's `Packages/` directory.

2. **IDE Integration** — Copy `.claude/` to your project root, then configure your IDE per [docs/SETUP.md](docs/SETUP.md).

Supports: Claude Code (Skill mode), Cursor, GitHub Copilot, Windsurf, Claude Desktop (MCP mode).

---

## Tool Categories

65 tools organized into 15 categories:

| Category | Count | Tools |
|----------|:-----:|-------|
| **Scene** | 7 | `scene-open`, `scene-save`, `scene-create`, `scene-list-opened`, `scene-get-data`, `scene-set-active`, `scene-unload` |
| **GameObject** | 11 | `gameobject-find`, `gameobject-create`, `gameobject-destroy`, `gameobject-modify`, `gameobject-duplicate`, `gameobject-set-parent`, `gameobject-component-add`, `gameobject-component-destroy`, `gameobject-component-get`, `gameobject-component-list-all`, `gameobject-component-modify` |
| **Assets** | 11 | `assets-find`, `assets-find-built-in`, `assets-get-data`, `assets-modify`, `assets-move`, `assets-copy`, `assets-delete`, `assets-create-folder`, `assets-refresh`, `assets-material-create`, `assets-shader-list-all` |
| **Prefab** | 5 | `assets-prefab-create`, `assets-prefab-open`, `assets-prefab-save`, `assets-prefab-close`, `assets-prefab-instantiate` |
| **Script** | 4 | `script-read`, `script-update-or-create`, `script-delete`, `script-execute` |
| **Object** | 2 | `object-get-data`, `object-modify` |
| **Editor** | 4 | `editor-application-get-state`, `editor-application-set-state`, `editor-selection-get`, `editor-selection-set` |
| **Reflection** | 2 | `reflection-method-find`, `reflection-method-call` |
| **Screenshot** | 1 | `screenshot-capture` |
| **Runtime** | 2 | `runtime-query`, `runtime-invoke` |
| **Console** | 1 | `console-get-logs` |
| **Profiler** | 5 | `profiler-snapshot`, `profiler-stream`, `profiler-frame-hierarchy`, `profiler-hotpath`, `profiler-gc-alloc` |
| **Package** | 4 | `package-list`, `package-search`, `package-add`, `package-remove` |
| **Light Probe** | 5 | `lightprobe-generate-grid`, `lightprobe-analyze`, `lightprobe-bake`, `lightprobe-clear`, `lightprobe-configure-lights` |
| **Tests** | 1 | `tests-run` |

---

## Architecture

```
┌──────────────────────────────────────────────────┐
│                   AI IDE                         │
│  (Claude Code / Cursor / Copilot / Windsurf)     │
└──────────┬────────────────────┬──────────────────┘
           │                    │
     Skill mode            MCP mode
           │                    │
           ▼                    ▼
    ┌─────────────┐    ┌──────────────┐
    │  bridge.py  │    │ mcp_server.py│
    │  (Python)   │    │  (Python)    │
    └──────┬──────┘    └──────┬───────┘
           │                  │
           └────────┬─────────┘
                    │
              File-based IPC
            (request / response)
                    │
                    ▼
    ┌───────────────────────────────┐
    │     Unity Editor Plugin      │
    │   (com.aibridge.unity)       │
    │                              │
    │  BridgePlugin ← polls files  │
    │  BridgeToolRegistry          │
    │  BridgeToolRunner            │
    │  [BridgeTool] methods        │
    └───────────────────────────────┘
```

**Dual-channel design**: The same Unity plugin serves both Skill mode (direct CLI) and MCP mode (protocol server). Both channels communicate through the same file-based IPC — a pair of request/response files on disk. No network sockets, no port conflicts, no firewall rules.

**Why file IPC?** Unity's main thread is single-threaded and blocks during domain reload. File polling is the most reliable way to survive recompilation, play-mode transitions, and Editor restarts without losing messages.

---

## Beyond Editing — AI as Game Tester

Most Unity AI tools stop at file editing. Unity AI Bridge goes further — it turns **Claude Code (or any AI IDE) into a game testing harness**.

| Capability | Traditional AI | With Unity AI Bridge |
|------------|:-:|:-:|
| Write C# code | :white_check_mark: | :white_check_mark: |
| Check compilation errors | :x: | :white_check_mark: `console-get-logs` |
| Enter / exit Play Mode | :x: | :white_check_mark: `editor-application-set-state` |
| Trigger game actions | :x: | :white_check_mark: `runtime-invoke` |
| Read runtime game state | :x: | :white_check_mark: `runtime-query` |
| Take screenshots | :x: | :white_check_mark: `screenshot-capture` |
| **Full closed loop: Write → Test → Fix → Repeat** | :x: | :white_check_mark: |

### AI Playtest Loop

```
AI writes code → compiles → enters Play Mode → observes state → judges → fixes → repeats
     ↑                                                                         │
     └─────────────────── fully automated loop ────────────────────────────────┘
```

The pattern: **Act → Wait → Observe → Judge → Repeat**

- **Act**: `runtime-invoke` calls static methods to trigger game actions
- **Wait**: `wait_playmode.py` / `wait_compile.py` handle timing
- **Observe**: `runtime-query` reads MonoBehaviour fields + `screenshot-capture` for visuals
- **Judge**: AI analyzes state/screenshots to decide PASS/FAIL

> [Auto-Playtest Example](examples/auto-playtest/README.md) |
> [AI Closed-Loop Guide](docs/AI_CLOSED_LOOP.md) |
> [Playtest Tool Reference](docs/AI_PLAYTEST_GUIDE.md)

---

## Add Your Own Tools

Expose any static method to AI with a single attribute:

```csharp
using UnityAiBridge;

[BridgeToolType]
public static partial class CustomTools
{
    [BridgeTool("custom-greet")]
    [System.ComponentModel.Description("Say hello")]
    public static string Greet(string name = "World")
    {
        return $"Hello, {name}!";
    }
}
```

The bridge discovers tools at Editor startup via reflection. No registration code, no config files. Parameters are automatically mapped to JSON Schema for the AI to call.

---

## Security

Unity AI Bridge runs **entirely on your local machine**. The file IPC channel is scoped to your user's temp directory, and no network listeners are opened.

See [SECURITY.md](SECURITY.md) for details.

---

## Compatibility

| Unity Version | Render Pipeline | Status |
|--------------|-----------------|--------|
| 2022.3 LTS+  | Built-in        | Supported |
| 2022.3 LTS+  | URP             | Supported |
| 2022.3 LTS+  | HDRP            | Supported |
| 6000.x (Unity 6) | All         | Supported |

**Platforms**: Windows, macOS

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

- Report bugs and request features via [GitHub Issues](https://github.com/butterlatte-zhang/unity-ai-bridge/issues)
- Submit pull requests against the `main` branch
- Add new tools by following the `[BridgeTool]` pattern above

---

## Acknowledgments

Unity AI Bridge is derived from [Unity-MCP](https://github.com/IvanMurzak/Unity-MCP) by Ivan Murzak (Apache License 2.0). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for details.

## License

[Apache License 2.0](LICENSE)