unity-control-protocol

Unity Control Protocol

CLI-first automation for the Unity Editor.

SVG logo | Discord | Releases | Docs | npm

UCP is a cross-platform CLI plus Unity Editor bridge for programmatic control of Unity projects. It is built for local automation, AI agents, CI/CD, and repeatable editor workflows across scenes, objects, assets, importer settings, packages, tests, builds, and profiler inspection.

What UCP is

UCP is split into two parts:

• ucp: a Rust CLI for operators, agents, and scripts
• com.ucp.bridge: a Unity Editor package that exposes editor operations over localhost WebSocket JSON-RPC

The bridge writes .ucp/bridge.lock in the Unity project root. The CLI reads that lock file, authenticates with a per-session token, and then talks to the editor through the bridge.

Most bridge-backed commands can now auto-start Unity when the project and editor path can be resolved.

What ships in this repo

• cli/: Rust CLI exposed as ucp
• unity-package/com.ucp.bridge/: Unity bridge package
• npm/: npm wrapper that downloads the matching released binary and bundles the bridge payload
• docs/: markdown docs source
• website/: Vite/React docs site built from docs/ and skills/
• skills/unity-control-protocol/SKILL.md: canonical agent skill file

Recommended workflow

This is the current happy-path workflow for real project use:

cd /path/to/MyUnityProject
ucp install
ucp open
ucp connect
ucp scene snapshot
ucp scene focus --id 46894 --axis 1 0 0

# edit files locally in your workspace
ucp compile

ucp play
ucp screenshot --view scene --output capture.png
ucp stop
ucp run-tests --mode edit
ucp close

Recommended usage notes:

• Prefer normal workspace file edits plus ucp compile for script iteration.
• Use ucp files read|write|patch when you intentionally want bridge-mediated project file I/O.
• ucp files write|patch automatically reimport edited Unity assets and .meta files under Assets/ and Packages/ unless you pass --no-reimport.
• For imported assets such as textures, FBX models, and audio, prefer ucp asset import-settings ... over hand-editing .meta files.
• Use ucp asset reimport <path> when you intentionally deferred apply work or changed an imported asset on disk outside Unity's importer workflow.
• Use ucp packages ... for Unity Package Manager workflows and ucp packages unitypackage ... for selective .unitypackage inspection/import.
• Use ucp open when you want an explicit lifecycle step.
• Use ucp connect when you want "make sure Unity is running and verify the bridge is healthy" in one command.
• Use ucp scene snapshot to discover instance IDs, then ucp scene focus and ucp screenshot for visual iteration loops.

Install

npm

npm install -g @mflrevan/ucp

pnpm

pnpm add -g @mflrevan/ucp
pnpm approve-builds

from source

git clone https://github.com/mflRevan/unity-control-protocol.git
cd unity-control-protocol/cli
cargo build --release

Claude Code plugin / marketplace

This repository is also Claude Code marketplace-compatible.

For local development or one-off testing:

claude --plugin-dir .

For marketplace-style installation from GitHub:

/plugin marketplace add mflRevan/unity-control-protocol
/plugin install ucp@unity-control-protocol

The default Claude Code marketplace install exposes only the base Unity automation skill:

• /ucp:unity-control-protocol

Repository support files for Claude Code users:

• .claude-plugin/plugin.json: plugin manifest
• .claude-plugin/marketplace.json: root marketplace catalog
• skills/unity-control-protocol/SKILL.md: base skill shipped to Claude Code

Install the Unity bridge

From a Unity project root:

ucp install

Default behavior:

• writes a tracked com.ucp.bridge dependency into Packages/manifest.json
• pins that dependency to the matching CLI tag
• stays non-interactive unless you pass --confirm
• does not inject a local file: dependency

Explicit local bridge development modes:

• ucp install --dev
• ucp install --embedded
• ucp install --bridge-path <path>

Lifecycle and bridge behavior

ucp open

• explicit editor bootstrap
• launches Unity for the target project
• waits for .ucp/bridge.lock
• waits for handshake success
• will not incorrectly treat a half-closed editor as healthy

ucp connect