← Tools

Unity Bridge

File-based protocol that lets any AI agent see and control Unity Editor through plain JSON files — 25 commands, lens system, screenshots, and texture catalog with zero server dependencies.

Authorcziberpv
Sourcegithub.com/cziberpv/unity-bridge
Updated
unitygame-developmentfile-based

Overview

Unity Bridge (v1.3.1, 53+ stars) is a lightweight alternative to MCP-based Unity integrations. Instead of WebSockets or HTTP servers, it uses a simple file-polling protocol: the AI agent writes a JSON command to request.json, Unity Editor processes it, and the result appears in response.md. Works with any AI agent that can write files — Claude Code, Cursor, Copilot, or plain shell scripts.

Requires Unity 2021.3+. No external dependencies beyond Newtonsoft.Json (ships with Unity).

Key Features

Feature Description
Lens system Filter inspect output by domain (layout, physics, scripts, visual, all) to minimize token usage
Screenshots Capture Game View by entering Play Mode automatically
Scratch pad Run arbitrary C# scripts inside the Editor via BridgeScratch.cs
Batch commands Send a JSON array, get a combined response
Compilation tracking refresh triggers recompilation and returns errors with file:line
Texture catalog Scan, search, tag, and preview project textures (experimental)

Commands (25 total)

Read: scene, inspect, find, prefab, prefabs, selection, errors, help Write: create, delete, rename, duplicate, add-component, delete-component, set, save-scene, new-scene, open-scene, refresh Media: screenshot, texture-scan, texture-search, texture-preview, texture-tag, texture-tag-batch Script: scratch

Unity Bridge vs MCP Unity

Aspect Unity Bridge MCP Unity
Protocol File I/O (JSON → Markdown) WebSocket / MCP
Dependencies None (ships with Unity) Node.js 18+, MCP server
Setup One git URL in Package Manager Install server + configure ports
Agent support Any agent that can write files Requires MCP client support
Tools 25 commands + lens system 30+ MCP tools + resources

Choose Unity Bridge for simplicity and universal agent compatibility. Choose MCP Unity for richer tool integration and IDE-native MCP support.

Installation

In Unity: Window → Package Manager → + → Add package from git URL:

https://github.com/cziberpv/unity-bridge.git

The package auto-installs and copies unity-cmd.ps1 to your project root.

Usage

# View scene hierarchy
powershell -File unity-cmd.ps1 '{"type": "scene"}'

# Inspect with lens filtering
powershell -File unity-cmd.ps1 '{"type": "inspect", "path": "Player", "lens": "scripts"}'

# Create GameObject with components
powershell -File unity-cmd.ps1 '[{"type": "create", "path": "Enemy", "components": ["Rigidbody2D", "BoxCollider2D"]}]'

# Compile and check errors
powershell -File unity-cmd.ps1 '{"type": "refresh"}' -Timeout 120

Raw content

Copy this into your project — e.g. .instructions.md, .agent.md, or SKILL.md

## Overview

Unity Bridge (v1.3.1, 53+ stars) is a lightweight alternative to MCP-based Unity integrations. Instead of WebSockets or HTTP servers, it uses a simple file-polling protocol: the AI agent writes a JSON command to `request.json`, Unity Editor processes it, and the result appears in `response.md`. Works with any AI agent that can write files — Claude Code, Cursor, Copilot, or plain shell scripts.

Requires **Unity 2021.3+**. No external dependencies beyond Newtonsoft.Json (ships with Unity).

## Key Features

| Feature | Description |
|---|---|
| **Lens system** | Filter inspect output by domain (`layout`, `physics`, `scripts`, `visual`, `all`) to minimize token usage |
| **Screenshots** | Capture Game View by entering Play Mode automatically |
| **Scratch pad** | Run arbitrary C# scripts inside the Editor via `BridgeScratch.cs` |
| **Batch commands** | Send a JSON array, get a combined response |
| **Compilation tracking** | `refresh` triggers recompilation and returns errors with file:line |
| **Texture catalog** | Scan, search, tag, and preview project textures (experimental) |

## Commands (25 total)

**Read:** `scene`, `inspect`, `find`, `prefab`, `prefabs`, `selection`, `errors`, `help`
**Write:** `create`, `delete`, `rename`, `duplicate`, `add-component`, `delete-component`, `set`, `save-scene`, `new-scene`, `open-scene`, `refresh`
**Media:** `screenshot`, `texture-scan`, `texture-search`, `texture-preview`, `texture-tag`, `texture-tag-batch`
**Script:** `scratch`

## Unity Bridge vs MCP Unity

| Aspect | Unity Bridge | MCP Unity |
|---|---|---|
| Protocol | File I/O (JSON → Markdown) | WebSocket / MCP |
| Dependencies | None (ships with Unity) | Node.js 18+, MCP server |
| Setup | One git URL in Package Manager | Install server + configure ports |
| Agent support | Any agent that can write files | Requires MCP client support |
| Tools | 25 commands + lens system | 30+ MCP tools + resources |

Choose **Unity Bridge** for simplicity and universal agent compatibility. Choose **MCP Unity** for richer tool integration and IDE-native MCP support.

## Installation

In Unity: Window → Package Manager → + → Add package from git URL:

```
https://github.com/cziberpv/unity-bridge.git
```

The package auto-installs and copies `unity-cmd.ps1` to your project root.

## Usage

```powershell
# View scene hierarchy
powershell -File unity-cmd.ps1 '{"type": "scene"}'

# Inspect with lens filtering
powershell -File unity-cmd.ps1 '{"type": "inspect", "path": "Player", "lens": "scripts"}'

# Create GameObject with components
powershell -File unity-cmd.ps1 '[{"type": "create", "path": "Enemy", "components": ["Rigidbody2D", "BoxCollider2D"]}]'

# Compile and check errors
powershell -File unity-cmd.ps1 '{"type": "refresh"}' -Timeout 120
```