UnityCtl.Protocol 0.1.1

UnityCtl

Remote control system for Unity Editor via CLI. Control a running Unity Editor without batch mode or interruption.

Overview

UnityCtl consists of three components:

1. unityctl (CLI) - Command-line tool for sending commands
2. unityctl-bridge (Daemon) - Bridge daemon that coordinates between CLI and Unity
3. Unity Editor Plugin (UPM Package) - Editor plugin that receives commands

┌─────────┐        ┌────────┐        ┌──────────────┐
│ unityctl│──HTTP──│ bridge │──WS────│ Unity Editor │
│  (CLI)  │        │(daemon)│        │   (plugin)   │
└─────────┘        └────────┘        └──────────────┘

Installation

1. Install CLI and Bridge

Install from NuGet (requires .NET 10.0+):

dotnet tool install -g UnityCtl.Cli
dotnet tool install -g UnityCtl.Bridge

To update existing installation:

dotnet tool update -g UnityCtl.Cli
dotnet tool update -g UnityCtl.Bridge

For development installation from source, see CONTRIBUTING.md

2. Add Unity Package

Add to your Unity project's Packages/manifest.json:

{
  "dependencies": {
    "com.dirtybit.unityctl": "https://github.com/DirtybitGames/unityctl.git?path=UnityCtl.UnityPackage#v0.1.1"
  }
}

Quick Start

1. Start the Bridge

From your Unity project directory:

cd unity-project
unityctl bridge start

Or specify the project path:

unityctl bridge start --project ./unity-project

Expected output:

Starting bridge for project: C:\Users\...\unity-project
Bridge started successfully (PID: 12345, Port: 49521)

2. Open Unity Editor

Open the Unity project in Unity Editor. The plugin will automatically connect to the bridge.

Look for Unity console logs:

[UnityCtl] Connected to bridge at port 49521
[UnityCtl] Handshake complete

3. Use the CLI

Check bridge status:

unityctl bridge status

Enter play mode:

unityctl play enter

Load a scene:

unityctl scene load Assets/Scenes/SampleScene.unity

Capture a screenshot:

unityctl screenshot capture

View console logs:

unityctl console tail --lines 20

Essential Commands

Bridge Management

# Check bridge status
unityctl bridge status

# Start bridge daemon
unityctl bridge start [--project <path>]

# Stop bridge daemon
unityctl bridge stop

Play Mode

# Enter play mode
unityctl play enter

# Exit play mode
unityctl play exit

# Toggle play mode
unityctl play toggle

Scene Management

# List scenes in build settings
unityctl scene list

# Load a scene (single mode)
unityctl scene load Assets/Scenes/Main.unity

# Load a scene (additive mode)
unityctl scene load Assets/Scenes/Level1.unity --mode additive

Console Logs

# Show recent console logs
unityctl console tail --lines 50

# Clear the console log buffer
unityctl console clear

Compilation

# Trigger script compilation
unityctl compile scripts

Asset Management

# Import a specific asset
unityctl asset import Assets/Textures/logo.png

Menu Management

# List all Unity menu items
unityctl menu list

# Execute a Unity menu item
unityctl menu execute Assets/Refresh

Test Runner

# Run tests (default: editmode)
unityctl test run

# Run tests in specific mode
unityctl test run --mode editmode
unityctl test run --mode playmode

# Run tests with filter pattern
unityctl test run --filter MyTest

Screenshots

# Capture screenshot with auto-generated filename
unityctl screenshot capture

# Capture with custom filename
unityctl screenshot capture mytest.png

# Capture with custom resolution
unityctl screenshot capture --width 1920 --height 1080

# Capture with custom filename and resolution
unityctl screenshot capture high-res.png --width 3840 --height 2160

Screenshots are saved to Screenshots/ folder in your project root (outside Assets).

Global Options

# Specify project path
unityctl --project ./my-unity-project play enter

# Get JSON output (for scripting)
unityctl --json scene list

For complete command reference with all options, run unityctl --help or see any command's help with unityctl <command> --help.

Key Concepts

Project Isolation

Each Unity project has its own bridge instance. The bridge creates .unityctl/bridge.json in your project root containing connection details:

{
  "projectId": "proj-a1b2c3d4",
  "port": 49521,
  "pid": 12345
}

The CLI auto-detects your project by walking up from the current directory to find ProjectSettings/ProjectVersion.txt.

Domain Reload Resilience

Unity's domain reload (triggered by script compilation) normally destroys all Editor objects. UnityCtl's bridge daemon survives these reloads and automatically reconnects, so your workflow isn't interrupted.

For detailed architecture information, see ARCHITECTURE.md

Common Issues

Bridge not starting?

• Check if port is already in use
• Verify you're in a Unity project directory

Unity not connecting?

• Check unityctl bridge status
• Ensure .unityctl/bridge.json exists in project root
• Restart Unity Editor

Commands timing out?

• Ensure Unity Editor window has focus (some operations require it)
• Check if Unity is responsive (not frozen)

For detailed troubleshooting, see TROUBLESHOOTING.md

Documentation

• ARCHITECTURE.md - Technical details and architecture
• CONTRIBUTING.md - Development setup and guidelines
• TROUBLESHOOTING.md - Extended debugging guide

License

MIT License - See LICENSE file for details