Skip to content

Jason-hub-star/unityctl

BranchesTags

Repository files navigation

unityctl

English | 한국어

NuGet NuGet CI License: MIT

The execution layer for AI-driven game development.

Give your AI agent 133 commands to build Unity scenes, write C# scripts, validate builds, and ship games — with automatic rollback when things go wrong.

133 CLI commands · 12 MCP tools · 689 tests · Windows / macOS / Linux

AI agent building a Unity scene via MCP

The Problem

AI agents can write code, but they can't build games — because Unity has no programmatic interface for scene editing, asset management, or project validation.

Existing Unity MCP servers try to fix this, but they create new problems for AI agents:

Pain Point Impact on AI Agent
45 KB+ schemas loaded every turn Wastes tokens on tool definitions instead of reasoning
No validation feedback Agent can't tell if the scene is broken after changes
No rollback One bad command corrupts the project state
WebSocket drops on Play Mode Agent loses connection during Unity's Domain Reload
Editor must be open CI/CD pipelines can't run without a GUI

The Solution

unityctl is a .NET CLI + MCP server that turns Unity Editor into a programmable API.

For AI agents, this means a closed-loop automation cycle — the agent doesn't just execute commands, it can verify results, diagnose failures, and recover from mistakes:

Plan - Execute - Verify - Diagnose Loop

Other tools give agents hands. unityctl gives agents hands, eyes, and a safety net.

What AI Agents Can Build

Scene Construction

"Create a platformer level with a floor, walls, and a player spawn point"

# Agent creates scene structure
unityctl scene create --path "Assets/Scenes/Level01.unity" --project $P
unityctl mesh create-primitive --type Plane --name "Floor" --scale "[10,1,10]" --project $P
unityctl mesh create-primitive --type Cube --name "Wall" --position "[5,1,0]" --scale "[0.5,2,10]" --project $P
unityctl gameobject create --name "PlayerSpawn" --project $P
unityctl component add --id "<PlayerSpawnId>" --type "BoxCollider" --project $P

# Agent verifies the scene
unityctl scene hierarchy --project $P --json      # check structure
unityctl screenshot capture --project $P           # visual verification
unityctl project validate --project $P --json      # camera? lights? errors?

Script Authoring with Compile Verification

"Write a player movement script and make sure it compiles"

# Agent writes code
unityctl script create --path "Assets/Scripts/PlayerMovement.cs" --className "PlayerMovement" --project $P
unityctl script patch --path "Assets/Scripts/PlayerMovement.cs" \
  --startLine 8 --insertContent "public float speed = 5f;" --project $P

# Agent checks compilation — and fixes errors in a loop
unityctl script validate --project $P --wait       # trigger recompile
unityctl script get-errors --project $P --json     # structured CS errors
# if errors: read error, patch fix, validate again

Safe Batch Operations with Rollback

"Set up physics layers for Player, Enemy, and Projectile — roll back if anything fails"

unityctl batch execute --project $P --rollbackOnFailure true --commands '[
  {"command": "layer-set", "parameters": {"index": 8, "name": "Player"}},
  {"command": "layer-set", "parameters": {"index": 9, "name": "Enemy"}},
  {"command": "layer-set", "parameters": {"index": 10, "name": "Projectile"}},
  {"command": "physics-set-collision-matrix", "parameters": {"layer1": 10, "layer2": 10, "ignore": true}}
]'
# If any command fails, all changes are automatically rolled back via Undo

Build Verification Pipeline

"Check if the project is ready to ship"

project-validate output showing 6 checks 

# Agent reads the failure, fixes it, validates again
unityctl gameobject create --name "Main Camera" --project $P
unityctl component add --id "<MainCameraId>" --type "Camera" --project $P
unityctl gameobject set-tag --id "<MainCameraId>" --tag "MainCamera" --project $P
unityctl project validate --project $P --json   # valid: true

What To Build First

If you want to prove unityctl in public, do not start with Minecraft. Start with a showcase ladder that matches the strongest verified loops in the current toolchain:

  1. Zero-to-playable: a small 3D arena microgame built from primitives, scripts, UI, physics, and verification artifacts.
  2. Vertical slice: expand that into a polished top-down survival or base-defense prototype with prefabs, NavMesh, materials, audio, and build validation.
  3. Sandbox step: only then move into chunked worlds, crafting, procedural terrain, and save-heavy systems.

The best first showcase for unityctl is a small 3D survival / base-defense game, not an open-world sandbox. It is easy to understand in screenshots and GIFs, maps cleanly to scene editing + script patching + rollback + visual verification, and can grow into a more complex sandbox later.

See Showcase Roadmap for:

  • the recommended public demo scope
  • the asset checklist to prepare before building
  • the pre-production plan for using unityctl effectively
  • the gaps worth closing before attempting a Minecraft-like demo

Why unityctl for AI Agents?

unityctl Existing Unity MCP
Schema overhead 5 KB per session (9x smaller) 45 KB+ loaded every turn
Validation loop project validate + scene diff + screenshot capture Agent flies blind
Error recovery script get-errors with file/line/column Raw console output or nothing
Safe experimentation batch execute --rollbackOnFailure + undo No rollback — mistakes are permanent
Connection stability Named Pipe — survives Domain Reload WebSocket drops, reconnect needed
CI/CD check / test / build --dry-run work headless Editor must be open
Diagnostics doctor classifies failures + suggests next steps "Connection failed"
Commands 133 (read + write + validate + diagnose) ~34-200 tools
Audit trail NDJSON flight recorder for every command No history
Runtime Native .NET — no Python/TS bridge Bridge overhead
Install dotnet tool install -g unityctl Node.js + npm + port config
License MIT Varies

Token Efficiency

AI agent costs are dominated by tool schemas sent every turn. unityctl uses on-demand schema loading:

Measured token cost: unityctl via Bash = 0 overhead, 6.8x cheaper than CoplayDev MCP

The 12 MCP tools cover the full 131-command surface through unityctl_query (read), unityctl_run (write), and unityctl_schema (lookup).

Measured: Claude Code Token Cost (2026-03-20)

When Claude Code runs 5 read-only QA operations (compile check, scene hierarchy, robot catalog, DH table, build settings), the cumulative token cost differs dramatically:

Stack Schema (once) 5 ops x 1 5 ops x 10
unityctl via Bash 0 tok 1,780 tok 17,800 tok
unityctl MCP (12 tools) 1,256 tok 2,957 tok 18,261 tok
CoplayDev MCP (30 tools) 11,427 tok 12,158 tok 18,742 tok

Key findings:

  • unityctl via Bash has zero schema overhead — the Bash tool is already in Claude Code's system prompt, so no additional tokens are spent on tool definitions
  • CoplayDev MCP loads 45 KB of schemas (30 tools), but only 1 out of 5 QA operations has a matching tool
  • In a typical short session, unityctl via Bash uses 6.8x fewer tokens than CoplayDev MCP
  • Full benchmark methodology and raw data: docs/benchmark/

Selection-aware Routing

# Pin the current Unity project once
unityctl editor select --project /path/to/project

# Or pin a running Unity PID when it maps to a single project
unityctl editor select --pid 55028

# Inspect the current selection
unityctl editor current --json

# See running Unity instances with PID / project / IPC status
unityctl editor instances --json

# These CLI commands can now omit --project
unityctl ping --json
unityctl status --json
unityctl check --json
unityctl doctor --json

# Run a small verification bundle (artifacts-first)
unityctl workflow verify --file verify.json --project /path/to/project --json

Install

# CLI (requires .NET 10 SDK)
dotnet tool install -g unityctl

# MCP server for AI agents
dotnet tool install -g unityctl-mcp

Bootstrap notes:

  • --source accepts a local Unityctl.Plugin folder or a Git URL: https://github.com/kimjuyoung1127/unityctl.git?path=/src/Unityctl.Plugin#v0.3.2
  • GitHub Release CLI archives are framework-dependent (not self-contained) today.

Apple Silicon macOS Validation

Manual validation was completed on an Apple silicon MacBook Air using Homebrew, .NET SDK 10.0.105, Unity Hub, and Unity editors 6000.0.64f1 and 6000.3.11f1.

Validated path:

  • dotnet tool install -g unityctl
  • dotnet tool install -g unityctl-mcp
  • unityctl editor list
  • unityctl init --project <project> --source /path/to/unityctl/src/Unityctl.Plugin
  • unityctl ping --project <project> --json
  • unityctl doctor --project <project> --json
  • unityctl status --project <project> --json
  • unityctl check --project <project> --json

Observed result on a Unity 6000.0.64f1 project: ping returned pong, doctor reported IPC connected, status returned Ready, and check passed on macOS.

Project compatibility note: if a Unity project or third-party package is pinned to Unity 6.0 LTS, opening that same project in 6000.3+ can fail before unityctl is involved. During validation, reopening the project in its pinned 6000.0.64f1 editor resolved the project-side render pipeline error.

Quick Start

# 1. Install the Editor plugin
unityctl init --project /path/to/project \
  --source "https://github.com/kimjuyoung1127/unityctl.git?path=/src/Unityctl.Plugin#v0.3.2"

# 2. Open the project in Unity Editor, then verify connectivity
unityctl ping --project /path/to/project --json
unityctl status --project /path/to/project --json

# 3. Start building
unityctl gameobject create --name "Player" --project /path/to/project
unityctl component add --id "<PlayerId>" --type "Rigidbody" --project /path/to/project
unityctl scene save --project /path/to/project

# 4. Validate
unityctl project validate --project /path/to/project --json

# 5. Build
unityctl build --project /path/to/project --dry-run    # 13 preflight checks

MCP Setup (AI Agents)

Add to your Claude Code / Cursor / VS Code MCP config:

{
  "mcpServers": {
    "unityctl": {
      "command": "unityctl-mcp"
    }
  }
}
12 MCP Tools
Tool Type Description
unityctl_query Read Unified read: asset, gameobject, scene, component, UI, physics, lighting, tags
unityctl_run Write Unified write: create, delete, modify, script, material, prefab, batch
unityctl_schema Meta On-demand parameter lookup (by command or category)
unityctl_build Action Build player with 13 preflight checks
unityctl_check Action Compile verification (headless)
unityctl_test Action EditMode / PlayMode tests
unityctl_exec Action Execute arbitrary C# expression
unityctl_status Read Editor state + connectivity
unityctl_ping Read Fast connectivity check
unityctl_watch Stream Real-time console / hierarchy / compilation events
unityctl_log Read Flight recorder query
unityctl_session_list Read Active session list

Commands (133)

Core (13)

Command Description
ping Check Unity connectivity
status Editor state (with --wait smart polling for Domain Reload)
check Verify script compilation (headless)
build Build player with --dry-run preflight (13 checks)
test Run EditMode / PlayMode tests
doctor Diagnose connectivity + suggest recovery steps
project validate Game readiness check (compile, scenes, camera, lights, console, editor)
init Install plugin to Unity project
editor list Discover installed Unity editors
editor instances List running Unity Editor instances
editor current Show the selected Unity project target
editor select Select a Unity project target, or a unique running PID, for project-less CLI routing
workflow verify Run artifact-first verification steps (projectValidate, capture, imageDiff, consoleWatch, uiAssert, playSmoke)
Scene & GameObject (19)
Command Description
scene snapshot Capture scene state
scene hierarchy Scene hierarchy tree
scene diff Property-level scene diff with epsilon
scene save Save active scene
scene open Open scene by path
scene create Create new scene
gameobject create Create GameObject
gameobject delete Delete GameObject
gameobject rename Rename GameObject
gameobject move Reparent GameObject
gameobject find Find by name/tag/component
gameobject get Get GameObject details
gameobject set-active Toggle active state
gameobject set-tag Set tag
gameobject set-layer Set layer
component add Add component
component remove Remove component
component get Get component properties
component set-property Set component property
Assets & Materials (21)
Command Description
asset find Search by type/label/path
asset get-info Asset metadata
asset get-dependencies Direct dependencies
asset reference-graph Reverse-reference graph
asset create Create asset
asset create-folder Create folder
asset copy Copy asset
asset move Move/rename asset
asset delete Delete asset
asset import Reimport asset
asset refresh Refresh AssetDatabase
asset get-labels Get labels
asset set-labels Set labels
material create Create material
material get Get material properties
material set Set material property
material set-shader Change shader
prefab create Create prefab from GameObject
prefab unpack Unpack prefab instance
prefab apply Apply prefab overrides
prefab edit Enter/exit prefab edit mode
Scripting & Code Analysis (10)
Command Description
script create Create C# script from template
script edit Replace script content (whole-file)
script patch Line-level insert/delete/replace
script delete Delete script file
script validate Trigger compilation and verify
script list List MonoScript assets
script get-errors Structured compile errors (file/line/column/code)
script find-refs Find symbol references across all scripts
script rename-symbol Rename symbol across all scripts (with --dry-run)
exec Execute C# expression in Unity
Editor Control (18)
Command Description
play start/stop/pause Start, stop, or pause play mode
editor pause Toggle editor pause
editor focus-gameview Focus Game View
editor focus-sceneview Focus Scene View
player-settings get/set PlayerSettings read/write
project-settings get/set Project settings read/write
console clear Clear console
console get-count Log/warning/error counts
define-symbols get/set Scripting define symbols
tag list/add Tag management
layer list/set Layer management
undo Undo last operation
redo Redo last undone operation
Build & Deployment (6)
Command Description
build-profile list/get-active/set-active Build profile management
build-target switch Switch build platform
build-settings get-scenes/set-scenes Build scene list
Physics, Lighting & NavMesh (12)
Command Description
physics get-settings/set-settings DynamicsManager
physics get-collision-matrix/set-collision-matrix 32x32 layer collision
lighting bake/cancel/clear Lightmap baking
lighting get-settings/set-settings Lightmap settings
navmesh bake/clear/get-settings NavMesh
UI & Mesh (8)
Command Description
ui canvas-create Create UI Canvas
ui element-create Create Button, Text, Image, etc.
ui set-rect Set RectTransform
ui find Find UI elements
ui get Get UI element details
ui toggle Set Toggle state
ui input Set InputField text
mesh create-primitive Create Cube/Sphere/Plane/Cylinder/Capsule/Quad
Automation & Monitoring (15)
Command Description
batch execute Transaction with rollback
workflow run JSON workflow execution
watch Real-time event streaming
log Flight recorder query
session list/stop/clean Session management
screenshot Scene/Game View capture (base64)
schema / tools Machine-readable metadata
package list/add/remove Package management
animation create-clip/create-controller Animation assets

Architecture

AI Agent (LLM)                unityctl-mcp              unityctl CLI             Unity Editor
Claude / GPT / Gemini         12 MCP tools              133 commands             Plugin (IPC)
        |                          |                          |                       |
        |--- MCP (stdio) -------->|                          |                       |
        |                          |--- CLI invocation ----->|                       |
        |                          |                          |--- IPC (~100ms) ---->|
        |                          |                          |    or Batch (30s+)   |
        |                          |                          |<--- JSON response ---|
        |                          |<--- result -------------|                       |
        |<--- tool result --------|                          |                       |

unityctl.slnx
+-- src/Unityctl.Shared   (netstandard2.1)  Protocol + models
+-- src/Unityctl.Core     (net10.0)         Business logic
+-- src/Unityctl.Cli      (net10.0)         CLI shell
+-- src/Unityctl.Mcp      (net10.0)         MCP server
+-- src/Unityctl.Plugin   (Unity UPM)       Editor bridge (IPC server)
+-- tests/*                                 633 xUnit tests

Platforms

Platform CLI IPC Transport Batch CI
Windows ✅ Named Pipe ✅ ✅
macOS ✅ Unix Domain Socket ✅ ✅
Linux ✅ Unix Domain Socket ✅ ✅

Prerequisites

Terminal Output

unityctl editor list

unityctl log

unityctl tools — 133 commands across 9 categories

Documentation

Changelog

See GitHub Releases for version history.

License

MIT — see LICENSE

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

7 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 5

v0.3.5 Latest
Mar 25, 2026
+ 4 releases

Packages

 
 
 

Contributors

Languages