Unity AI Bridge

English | 中文

Unity AI Bridge

从任意 AI IDE 远程控制 Unity Editor——无需端口、无需依赖，开箱即用。

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

---

为什么选择 Unity AI Bridge？

大多数 AI 编码助手可以读取和写入文件，但它们对 Unity Editor 一无所知——无法检查场景、调整材质、运行测试或分析性能。Unity AI Bridge 让 AI 能够全面访问编辑器。

主要优势

• 65 个工具，15 个类别——Scene、GameObject、Assets、Prefab、Script、Profiler、LightProbe、Screenshot、Runtime、Tests 等。覆盖完整的编辑器工作流，而不仅仅是文件读写。
• 基于文件的 IPC，而非 WebSocket——无需开放端口，没有防火墙问题，也不会断开连接。可平稳应对重新编译、播放模式切换和编辑器重启。
• 零外部依赖——纯 Python 标准库 CLI/MCP 服务，以及独立的 C# Unity 包。无需 pip install、npm 或 Node.js 运行时。
• 支持所有主流 AI IDE——Claude Code（Skill 模式）、Cursor、GitHub Copilot、Windsurf、Claude Desktop（MCP 模式）。一个 Unity 插件，支持所有 IDE。
• 只需 5 行即可扩展——使用 [BridgeTool] 属性添加自定义工具。自动发现、自动序列化、自动生成文档。无需编写注册代码。
• 经过生产环境验证——专为大型开放世界 Unity 游戏打造，并经过实战检验（50 多名开发者、200 多万行 C# 代码）。

对比 Unity 6 AI Gateway

Unity 6.2 引入了官方 AI Gateway，并支持 MCP。两个项目的目标相同——通过 MCP 让 AI Agent 访问编辑器——但在一些重要方面有所不同：

	Unity AI Bridge	Unity 6 AI Gateway
Unity 版本	2022.3 LTS+	仅支持 6.2+
工具覆盖范围	涵盖 15 个类别的 65 个工具	通用工具（Scene、Assets、Script、Console）
深度工具	Profiler（快照、热点路径、流）、LightProbe、Reflection、Package Manager	尚不可用
IPC 机制	文件轮询（约 100ms）	Unix Socket / Named Pipe
可扩展性	[BridgeTool] 属性——5 行代码	TBD

实际使用中，由于 AI Agent 的思考时间占据了每次往返的大部分时间，约 100ms 的文件轮询延迟几乎无法察觉。基于文件的 IPC 也让跨进程调试变得轻而易举——只需检查磁盘上的 JSON 文件。

---

快速开始

面向 AI 的项目——复制下面的提示词并发送给你的 AI 编码助手。安装指南专为 AI 执行而编写——你无需自行运行任何命令。

请按照以下指南帮助我安装 Unity AI Bridge：
https://github.com/butterlatte-zhang/unity-ai-bridge/blob/main/docs/SETUP.md

如果你更喜欢手动设置：

1. Unity 包——在 Unity 中选择：Window > Package Manager > + > Add package from git URL：

   https://github.com/butterlatte-zhang/unity-ai-bridge.git?path=Packages/com.aibridge.unity
   

   或者将此仓库中的 Packages/com.aibridge.unity 手动复制到项目的 Packages/ 目录中。

2. IDE 集成——将 .claude/ 复制到项目根目录，然后按照 docs/SETUP.md 配置 IDE。

支持：Claude Code（Skill 模式）、Cursor、GitHub Copilot、Windsurf、Claude Desktop（MCP 模式）。

---

工具类别

65 个工具分为 15 个类别：

类别	数量	工具
场景	7	scene-open、scene-save、scene-create、scene-list-opened、scene-get-data、scene-set-active、scene-unload
游戏对象	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
资源	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
预制体	5	assets-prefab-create、assets-prefab-open、assets-prefab-save、assets-prefab-close、assets-prefab-instantiate
脚本	4	script-read、script-update-or-create、script-delete、script-execute
对象	2	object-get-data、object-modify
编辑器	4	editor-application-get-state、editor-application-set-state、editor-selection-get、editor-selection-set
反射	2	reflection-method-find、reflection-method-call
截图	1	screenshot-capture
运行时	2	runtime-query、runtime-invoke
控制台	1	console-get-logs
性能分析器	5	profiler-snapshot、profiler-stream、profiler-frame-hierarchy、profiler-hotpath、profiler-gc-alloc
包	4	package-list、package-search、package-add、package-remove
光照探针	5	lightprobe-generate-grid、lightprobe-analyze、lightprobe-bake、lightprobe-clear、lightprobe-configure-lights
测试	1	tests-run

---

架构

┌──────────────────────────────────────────────────┐
│                   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        │
    └───────────────────────────────┘

双通道设计：同一个 Unity 插件同时支持 Skill 模式（直接 CLI）和 MCP 模式（协议服务端）。两个通道通过同一套基于文件的 IPC 通信，即磁盘上的一对请求／响应文件。无需网络套接字，不会发生端口冲突，也无需配置防火墙规则。

为什么使用文件 IPC？ Unity 的主线程是单线程的，并且会在域重新加载期间阻塞。文件轮询是最可靠的方式，可以在重新编译、播放模式切换和 Editor 重启期间保持通信，不丢失消息。

---

不止于编辑——让 AI 担任游戏测试员

大多数 Unity AI 工具仅止步于文件编辑。Unity AI Bridge 更进一步——它能将 Claude Code（或任何 AI IDE）变成游戏测试平台。

能力	传统 AI	使用 Unity AI Bridge
编写 C# 代码	:white_check_mark:	:white_check_mark:
检查编译错误	:x:	:white_check_mark: console-get-logs
进入／退出播放模式	:x:	:white_check_mark: editor-application-set-state
触发游戏操作	:x:	:white_check_mark: runtime-invoke
读取游戏运行时状态	:x:	:white_check_mark: runtime-query
截取屏幕截图	:x:	:white_check_mark: screenshot-capture
完整闭环：编写 → 测试 → 修复 → 重复	:x:	:white_check_mark:

AI 游戏测试循环

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

该模式为：操作 → 等待 → 观察 → 判断 → 重复

• 操作：runtime-invoke 调用静态方法以触发游戏操作
• 等待：wait_playmode.py / wait_compile.py 负责处理时序
• 观察：runtime-query 读取 MonoBehaviour 字段，screenshot-capture 获取画面
• 判断：AI 分析状态／截图并判定通过／失败

自动游戏测试示例 | AI 闭环指南 | 游戏测试工具参考

---

添加自定义工具

只需添加一个属性，即可向 AI 暴露任何静态方法：

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}!";
    }
}

桥接程序会在 Editor 启动时通过反射发现工具。无需注册代码，也无需配置文件。参数会自动映射为 JSON Schema，供 AI 调用。

---

安全性

Unity AI Bridge 完全在本地计算机上运行。文件 IPC 通道仅限于用户的临时目录，不会开启任何网络监听器。

详情请参阅 SECURITY.md。

---

兼容性

Unity 版本	渲染管线	状态
2022.3 LTS+	内置	支持
2022.3 LTS+	URP	支持
2022.3 LTS+	HDRP	支持
6000.x (Unity 6)	全部	支持

平台：Windows、macOS

---

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

• 通过 GitHub Issues 报告错误和请求功能
• 向 main 分支提交拉取请求
• 按照上文的 [BridgeTool] 模式添加新工具

---

致谢

Unity AI Bridge 衍生自 Ivan Murzak 开发的 Unity-MCP（Apache License 2.0）。详情请参阅 THIRD_PARTY_NOTICES.md。

许可证

Apache License 2.0