Unity Cursor Toolkit

A VS Code / Cursor extension and Unity package for live console context, safe MCP automation, debugging, hot reload, and remote Unity workflows. The package declares Unity 2019.4 as its core baseline; Unity 7 is an explicit, evidence-gated readiness target.

Disclaimer

This extension is not affiliated with, endorsed by, or an official product of Unity Technologies. Unity and the Unity logo are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere.

Features

Hot Reload

Save-to-refresh with debounced file watching and compilation feedback in the status bar. IL patching support for play-mode method body swapping without domain reload.

Live Console

Real-time streaming, severity filtering, text search across messages and stack traces, safe clickable Assets/... stack traces, copy/export, send-to-AI-chat, and a ring buffer (10k entries, configurable). Console snapshots can include the current Unity profiler session so agents get logs, frame trends, hot frames, and hot paths together. The native Unity copy button also captures the current main-camera application view to one stable temporary PNG, overwrites it on every click, and appends its absolute path to the copied context.

Connection

TCP state machine with toolkit ping/pong validation, heartbeat, exponential backoff reconnect, and multi-port auto-select (55500-55504). Open ports that do not answer the Unity Cursor Toolkit handshake are ignored so the extension does not attach to unrelated Unity listeners.

Status Bar

Two-part layout: one-click connect toggle plus quick-access dropdown with play mode controls, console snapshot, and project info.

Play Mode Control

Enter, exit, pause, and single-frame step directly from VS Code / Cursor -- no need to switch to the Unity Editor.

MCP Server

AI agents (Cursor, Claude Code, Copilot, Zed, and other MCP clients) can read console output, inspect project state, control play mode, manage scenes/assets, query project info, capture screenshots, inspect profiler snapshots, query a compact Unity context index, run game-authored command sequences, and use read-only or dry-run safeguards before mutating Unity state.

Mono Debugger

Attach to the Unity Editor or a Development Player via the built-in Mono soft debugger (port 56000 default).

Meta File Management

Auto-hide .meta files from explorer and Cmd+P, with workspace-contained on-demand resolve for AI workflows.

Unity Package (C# side)

A companion UPM package (com.rankupgames.unity-cursor-toolkit) provides the Unity-side scripts: console forwarding, hot reload handler, MCP bridge, runtime command registry, debug bridge, and IL patcher. Installable via OpenUPM, Git URL, or scoped registry.

Quick Start

1. Install the extension from the VS Code Marketplace or OpenVSX.
2. Install the Unity package (see Unity Package Installation).
3. Open a Unity project folder in VS Code or Cursor.
4. Click Unity Attach in the status bar to connect.

AI Agent Quick Start

The extension now builds a standalone MCP stdio server for agents that do not run VS Code extensions directly.

cd unity-cursor-toolkit
npm ci
npm run compile
npm run mcp:serve

Use Unity Toolkit: Copy MCP Client Config in VS Code/Cursor to copy setup snippets, or read MCP Client Setup for Cursor, Claude Code, VS Code Copilot Agent mode, and Zed examples.

Agent safety defaults:

• Set UNITY_CURSOR_TOOLKIT_MCP_READ_ONLY=1 to block mutating tools.
• Pass dryRun: true to mutating tools to inspect the normalized Unity command without executing it.
• Start with project_info, read_console, and manage_scene using action: "getHierarchy" before scene or asset edits.
• Use unity_context with action: "scan" to refresh .umetacontext/index.json, then use summary, query, and read to inspect assets, GUIDs, serialized objects, components, and references without broad file reads.
• Use game_command with action: "list" to discover project-authored runtime workflows before scheduling them.

See the documentation index, AI Agent Guide, Runtime Game Commands, Unity 7 Readiness Plan, Feature Roadmap, and llms.txt for agent-facing context.

Requirements

• VS Code or Cursor 1.60+
• Unity 2019.4+ as the declared core package baseline; see the evidence table below

Unity Version Support and Unity 7 Readiness

Editor family	Current position
Unity 2019.4 through 2022 LTS	Declared core package range; preserve the Mono debugger and legacy hot-reload path and add exact-version evidence
Current Unity 6 releases	Unity-Unterm declares Unity 6000.3+ on macOS or Windows; the local sample baseline is Unity 6000.3.9f1 on macOS
CoreCLR transition releases	Capability gates, reload fixes, migration checks, and a debugger replacement are planned and not yet complete
Unity 7	Readiness target only; do not treat this README as a compatibility certification

The plan is one stable agent interface across Editor generations, with an explicit backend and capability set for every operation. See the Unity 7 Readiness Plan, the dated landscape assessment, and the WS1–WS8 task index.

Unity Package Installation

Via OpenUPM (recommended)

openupm add com.rankupgames.unity-cursor-toolkit

Via Git URL

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

https://github.com/rankupgames/unity-cursor-toolkit.git?path=Packages/com.rankupgames.unity-cursor-toolkit

Via Scoped Registry

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

"scopedRegistries": [
  {
    "name": "OpenUPM",
    "url": "https://package.openupm.com",
    "scopes": ["com.rankupgames"]
  }
],
"dependencies": {
  "com.rankupgames.unity-cursor-toolkit": "1.1.0"
}

Runtime Game Commands

Unity projects can register runtime command sequences that agents can call through MCP without driving the UI. Commands are registered from game code through UnityCursorToolkit.AgentCommands.AgentCommandRegistry, run as coroutines during play mode, and are scheduled through the game_command MCP tool.

Typical flow:

{ "action": "list" }

{ "action": "run", "commandName": "auth.select_us_east", "args": {} }

Then poll with:

{ "action": "status", "runId": "<run id returned by run>" }

See Runtime Game Commands for registration patterns and project integration notes.

For non-rendering command discovery and execution in CI or headless automation, pass host: "editorBatchmode". The MCP server launches Unity with UnityCursorToolkit.AgentCommands.BatchCommandEntry.Run, writes structured arguments to a temp file, and returns the Unity log tail plus the command result JSON.

Configuration

Setting	Default	Description
unityCursorToolkit.console.enabled	true	Enable the Unity Console panel in the sidebar
unityCursorToolkit.console.autoStream	true	Auto-stream console output when connected
unityCursorToolkit.console.maxEntries	10000	Max entries in the console ring buffer
unityCursorToolkit.hotReload.preferILPatch	true	Prefer IL patching over full asset refresh in play mode
unityCursorToolkit.hotReload.ilPatchTimeout	5000	Timeout (ms) for IL patch before falling back to full refresh
unityCursorToolkit.workspaceScanPaths	[]	Additional paths to scan for .code-workspace files

Development and Validation

The extension package lives in unity-cursor-toolkit/.

cd unity-cursor-toolkit
npm ci
npm run validate

npm run validate is the canonical local and CI gate. It compiles the extension, runs a strict unused-code type check, executes the runtime test harness, and runs both production and full npm audits.

Dependency updates should use npm 11.14.1 or newer with the repository age gate, for example npm update <package> --package-lock-only --ignore-scripts --min-release-age=7. Prefer lockfile-scoped security fixes for transitive audit findings. If a fixed package is newer than 7 days, leave the advisory pending unless the update is explicitly approved as a security hotfix.

For packaging checks:

npx vsce package --no-dependencies

The VSIX package is intentionally limited to runtime extension assets: compiled out/ files, metadata, icon, and license. Tests, backups, lockfiles, source maps, and generated bundles are excluded through .vscodeignore.

Security Hardening

• Dependency audits run through npm run validate and GitHub Actions.
• Dependency updates follow a 7-day npm release-age gate unless an explicit security hotfix exception is documented.
• TCP attach requires the current Unity package handshake; if Unity exposes an older package server, the extension reports that the package should be updated instead of treating the port as connected.
• Console webviews use nonce-based CSP for scripts and styles.
• Console payloads are normalized before rendering, filtering, copying, or forwarding to chat.
• Clickable stack traces and .meta resolution reject paths that escape the current workspace.

Commands

Command	Description
unity-cursor-toolkit.startConnection	Start/Attach to a Unity project
unity-cursor-toolkit.reloadConnection	Reload the current connection
unity-cursor-toolkit.stopConnection	Stop the connection
unity-cursor-toolkit.console.clear	Clear the console panel
unity-cursor-toolkit.console.sendToChat	Send console output to AI chat
unity-cursor-toolkit.console.copy	Copy console/profiler context to the clipboard
unity-cursor-toolkit.console.snapshot	Take a console/profiler snapshot
unity-cursor-toolkit.console.export	Export console logs to file
unity-cursor-toolkit.resolveMeta	Resolve .meta file for a path (for AI)
unity-cursor-toolkit.openProject	Open Unity project in the editor
unity-cursor-toolkit.generateFolderStructure	Generate folder structure for AI context
unity-cursor-toolkit.quickAccess	Quick Actions menu
unity-cursor-toolkit.debug.attach	Attach Mono debugger to Unity
unity-cursor-toolkit.playMode.enter	Enter Play Mode
unity-cursor-toolkit.playMode.exit	Exit Play Mode
unity-cursor-toolkit.playMode.pause	Pause Play Mode
unity-cursor-toolkit.playMode.step	Step one frame
unity-cursor-toolkit.screenshot	Capture a screenshot from Unity
unity-cursor-toolkit.mcp.showServerPath	Show the standalone MCP server path
unity-cursor-toolkit.mcp.copyClientConfig	Copy MCP client config snippets

Project Structure

unity-cursor-toolkit/
├── unity-cursor-toolkit/           # VS Code / Cursor extension (TypeScript)
│   └── src/
│       ├── extension.ts            # Entry point and composition root
│       ├── core/                   # Connection, transport, types, module loader
│       ├── console/                # Console bridge, panel, and MCP tools
│       ├── hot-reload/             # File watcher with debounce
│       ├── mcp/                    # MCP server, tool router, Unity tools
│       ├── debug/                  # Mono debug adapter
│       └── project/                # Project handler, meta manager, folder templates
├── Packages/
│   └── com.rankupgames.unity-cursor-toolkit/   # Unity UPM package (C#)
│       ├── Runtime/
│       │   └── AgentCommands/         # Runtime command registry and coroutine runner
│       └── Editor/
│           ├── ConsoleToCursor.cs       # Console log forwarding
│           ├── ProfilerSnapshot.cs      # Profiler session snapshots and MCP access
│           ├── HotReloadHandler.cs      # Asset refresh on code changes
│           ├── Core/                    # MCP tool attribute, interfaces
│           ├── Debug/                   # Mono debug bridge
│           ├── HotReload/              # IL patcher
│           └── MCP/                     # MCP bridge, scene/asset/editor tools
├── CursorUnityTool/                # Unity test project
├── zed/                            # Zed editor integration (MCP)
├── docs/                           # Product guides, Unity 7 readiness, research, and workstreams
├── AGENTS.md                       # Coding-agent repo instructions
├── llms.txt                        # AI-readable documentation index
├── .github/workflows/              # CI and release pipelines
├── CONTRIBUTING.md
├── SECURITY.md
└── CODE_OF_CONDUCT.md

Distribution

• VS Code Marketplace -- Primary distribution
• OpenVSX -- Windsurf, VSCodium, Theia
• Cursor -- Native support
• Zed -- Via standalone MCP server (see zed/)

CI and release workflows publish separate VS Code Marketplace and OpenVSX VSIX artifacts. Publishing fails loudly when VSCE_PAT or OVSX_PAT repository secrets are missing, so a green release means both registry uploads were attempted with valid credentials.

Contributing

See CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for repository and extension changes. The Unity package changelog lives at Packages/com.rankupgames.unity-cursor-toolkit/CHANGELOG.md.

Security

See SECURITY.md for vulnerability reporting.

License

MIT License -- Copyright (c) 2025 Rank Up Games LLC. See LICENSE for details.