{
  "markdown": "**[English](README.md)** | **[中文](README.zh-CN.md)**\n\n# Unity AI Bridge\n\n**Remote-control the Unity Editor from any AI IDE — no ports, no dependencies, just works.**\n\n[![Unity 2022.3+](https://img.shields.io/badge/Unity-2022.3%2B-black?logo=unity)](#)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/butterlatte-zhang/unity-ai-bridge?style=social)](https://github.com/butterlatte-zhang/unity-ai-bridge/stargazers)\n[![Release](https://img.shields.io/github/v/release/butterlatte-zhang/unity-ai-bridge)](https://github.com/butterlatte-zhang/unity-ai-bridge/releases)\n[![Glama](https://glama.ai/mcp/servers/butterlatte-zhang/unity-ai-bridge/badges/score.svg)](https://glama.ai/mcp/servers/butterlatte-zhang/unity-ai-bridge)\n\nhttps://github.com/user-attachments/assets/4e8b3f85-b209-406f-a96e-f8b8eddc9160\n\n---\n\n## Why Unity AI Bridge?\n\nMost 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.\n\n### Key Advantages\n\n- **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.\n- **File-based IPC, not WebSocket** — No open ports, no firewall issues, no connection drops. Survives recompilation, play-mode transitions, and editor restarts gracefully.\n- **Zero external dependencies** — Pure Python stdlib CLI/MCP server, self-contained C# Unity package. No pip install, no npm, no Node.js runtime.\n- **Every major AI IDE** — Claude Code (Skill mode), Cursor, GitHub Copilot, Windsurf, Claude Desktop (MCP mode). One Unity plugin, all IDEs.\n- **5-line extensibility** — Add custom tools with `[BridgeTool]` attribute. Auto-discovered, auto-serialized, auto-documented. No registration code needed.\n- **Production-tested** — Built for and battle-tested in a large-scale open-world Unity game (50+ developers, 2M+ lines of C#).\n\n### vs Unity 6 AI Gateway\n\nUnity 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:\n\n| | Unity AI Bridge | Unity 6 AI Gateway |\n|---|---|---|\n| **Unity version** | 2022.3 LTS+ | 6.2+ only |\n| **Tool coverage** | 65 tools across 15 categories | General-purpose (Scene, Assets, Script, Console) |\n| **Deep tooling** | Profiler (snapshot, hotpath, stream), LightProbe, Reflection, Package Manager | Not yet available |\n| **IPC mechanism** | File polling (~100ms) | Unix Socket / Named Pipe |\n| **Extensibility** | `[BridgeTool]` attribute — 5 lines | TBD |\n\nIn 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.\n\n---\n\n## Quick Start\n\n> **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.\n>\n> ```\n> Help me install Unity AI Bridge by following this guide:\n> https://github.com/butterlatte-zhang/unity-ai-bridge/blob/main/docs/SETUP.md\n> ```\n\nIf you prefer manual setup:\n\n1. **Unity Package** — In Unity: *Window > Package Manager > + > Add package from git URL*:\n   ```\n   https://github.com/butterlatte-zhang/unity-ai-bridge.git?path=Packages/com.aibridge.unity\n   ```\n   Or manually copy `Packages/com.aibridge.unity` from this repo into your project's `Packages/` directory.\n\n2. **IDE Integration** — Copy `.claude/` to your project root, then configure your IDE per [docs/SETUP.md](docs/SETUP.md).\n\nSupports: Claude Code (Skill mode), Cursor, GitHub Copilot, Windsurf, Claude Desktop (MCP mode).\n\n---\n\n## Tool Categories\n\n65 tools organized into 15 categories:\n\n| Category | Count | Tools |\n|----------|:-----:|-------|\n| **Scene** | 7 | `scene-open`, `scene-save`, `scene-create`, `scene-list-opened`, `scene-get-data`, `scene-set-active`, `scene-unload` |\n| **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` |\n| **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` |\n| **Prefab** | 5 | `assets-prefab-create`, `assets-prefab-open`, `assets-prefab-save`, `assets-prefab-close`, `assets-prefab-instantiate` |\n| **Script** | 4 | `script-read`, `script-update-or-create`, `script-delete`, `script-execute` |\n| **Object** | 2 | `object-get-data`, `object-modify` |\n| **Editor** | 4 | `editor-application-get-state`, `editor-application-set-state`, `editor-selection-get`, `editor-selection-set` |\n| **Reflection** | 2 | `reflection-method-find`, `reflection-method-call` |\n| **Screenshot** | 1 | `screenshot-capture` |\n| **Runtime** | 2 | `runtime-query`, `runtime-invoke` |\n| **Console** | 1 | `console-get-logs` |\n| **Profiler** | 5 | `profiler-snapshot`, `profiler-stream`, `profiler-frame-hierarchy`, `profiler-hotpath`, `profiler-gc-alloc` |\n| **Package** | 4 | `package-list`, `package-search`, `package-add`, `package-remove` |\n| **Light Probe** | 5 | `lightprobe-generate-grid`, `lightprobe-analyze`, `lightprobe-bake`, `lightprobe-clear`, `lightprobe-configure-lights` |\n| **Tests** | 1 | `tests-run` |\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────┐\n│                   AI IDE                         │\n│  (Claude Code / Cursor / Copilot / Windsurf)     │\n└──────────┬────────────────────┬──────────────────┘\n           │                    │\n     Skill mode            MCP mode\n           │                    │\n           ▼                    ▼\n    ┌─────────────┐    ┌──────────────┐\n    │  bridge.py  │    │ mcp_server.py│\n    │  (Python)   │    │  (Python)    │\n    └──────┬──────┘    └──────┬───────┘\n           │                  │\n           └────────┬─────────┘\n                    │\n              File-based IPC\n            (request / response)\n                    │\n                    ▼\n    ┌───────────────────────────────┐\n    │     Unity Editor Plugin      │\n    │   (com.aibridge.unity)       │\n    │                              │\n    │  BridgePlugin ← polls files  │\n    │  BridgeToolRegistry          │\n    │  BridgeToolRunner            │\n    │  [BridgeTool] methods        │\n    └───────────────────────────────┘\n```\n\n**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.\n\n**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.\n\n---\n\n## Beyond Editing — AI as Game Tester\n\nMost 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**.\n\n| Capability | Traditional AI | With Unity AI Bridge |\n|------------|:-:|:-:|\n| Write C# code | :white_check_mark: | :white_check_mark: |\n| Check compilation errors | :x: | :white_check_mark: `console-get-logs` |\n| Enter / exit Play Mode | :x: | :white_check_mark: `editor-application-set-state` |\n| Trigger game actions | :x: | :white_check_mark: `runtime-invoke` |\n| Read runtime game state | :x: | :white_check_mark: `runtime-query` |\n| Take screenshots | :x: | :white_check_mark: `screenshot-capture` |\n| **Full closed loop: Write → Test → Fix → Repeat** | :x: | :white_check_mark: |\n\n### AI Playtest Loop\n\n```\nAI writes code → compiles → enters Play Mode → observes state → judges → fixes → repeats\n     ↑                                                                         │\n     └─────────────────── fully automated loop ────────────────────────────────┘\n```\n\nThe pattern: **Act → Wait → Observe → Judge → Repeat**\n\n- **Act**: `runtime-invoke` calls static methods to trigger game actions\n- **Wait**: `wait_playmode.py` / `wait_compile.py` handle timing\n- **Observe**: `runtime-query` reads MonoBehaviour fields + `screenshot-capture` for visuals\n- **Judge**: AI analyzes state/screenshots to decide PASS/FAIL\n\n> [Auto-Playtest Example](examples/auto-playtest/README.md) |\n> [AI Closed-Loop Guide](docs/AI_CLOSED_LOOP.md) |\n> [Playtest Tool Reference](docs/AI_PLAYTEST_GUIDE.md)\n\n---\n\n## Add Your Own Tools\n\nExpose any static method to AI with a single attribute:\n\n```csharp\nusing UnityAiBridge;\n\n[BridgeToolType]\npublic static partial class CustomTools\n{\n    [BridgeTool(\"custom-greet\")]\n    [System.ComponentModel.Description(\"Say hello\")]\n    public static string Greet(string name = \"World\")\n    {\n        return $\"Hello, {name}!\";\n    }\n}\n```\n\nThe 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.\n\n---\n\n## Security\n\nUnity 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.\n\nSee [SECURITY.md](SECURITY.md) for details.\n\n---\n\n## Compatibility\n\n| Unity Version | Render Pipeline | Status |\n|--------------|-----------------|--------|\n| 2022.3 LTS+  | Built-in        | Supported |\n| 2022.3 LTS+  | URP             | Supported |\n| 2022.3 LTS+  | HDRP            | Supported |\n| 6000.x (Unity 6) | All         | Supported |\n\n**Platforms**: Windows, macOS\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- Report bugs and request features via [GitHub Issues](https://github.com/butterlatte-zhang/unity-ai-bridge/issues)\n- Submit pull requests against the `main` branch\n- Add new tools by following the `[BridgeTool]` pattern above\n\n---\n\n## Acknowledgments\n\nUnity 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.\n\n## License\n\n[Apache License 2.0](LICENSE)\n",
  "bytes": 10674,
  "sha": "0bb739970a8790dd984e61c28fe4a2dadb55b6963b2c123d476d908b12e873e6",
  "repo_slug": "butterlatte-zhang/unity-ai-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_butterlatte_zhang_unity_ai_bri_7499e08e/readme"
}