Metadata-Version: 2.4
Name: dcc-mcp-unity
Version: 0.4.0
Summary: Unity Editor adapter and typed game-authoring skills for DCC-MCP
Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-unity
Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-unity
Project-URL: Issues, https://github.com/dcc-mcp/dcc-mcp-unity/issues
Author-email: loonghao <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Keywords: ai,game-development,mcp,model-context-protocol,unity
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.9
Requires-Dist: dcc-mcp-core<1.0.0,>=0.19.45
Requires-Dist: websockets>=12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# dcc-mcp-unity

![DCC-MCP Unity lockup](https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-unity/main/docs/assets/dcc-mcp-unity.svg)

Unity Editor adapter for the DCC Model Context Protocol ecosystem. It ships a UPM Editor package,
a loopback WebSocket bridge, and typed project and scene tools.

The supported Editor range starts at Unity 2018.4.36f1 with the .NET 4.x Equivalent scripting
runtime. CI pins the final Unity 2018 LTS patch, the 2021.3 baseline, and the current stable Unity 6
release instead of using a drifting `latest` tag.

The first-release boundary and comparison with `unity-cli` and two established Unity MCP projects
are documented in the [architecture benchmark](https://github.com/dcc-mcp/dcc-mcp-unity/blob/main/docs/architecture-benchmark.md).

## Install

```bash
pip install dcc-mcp-unity
dcc-mcp-unity-install /path/to/UnityProject
```

Open or restart the Unity project so Package Manager compiles **DCC-MCP Unity**, then run:

```bash
dcc-mcp-unity
```

See the [installation guide](https://github.com/dcc-mcp/dcc-mcp-unity/blob/main/install.md) for
upgrade, environment, and connection verification details.

The MCP endpoint uses a free loopback port and is registered for gateway discovery. Set
`DCC_MCP_UNITY_PORT=8765` before starting the server only when a fixed direct endpoint is needed.
The Editor package reconnects to the loopback bridge at `ws://127.0.0.1:3852`; set
`DCC_MCP_UNITY_BRIDGE_PORT` before the MCP server and `DCC_MCP_UNITY_BRIDGE_URL` before Unity starts
to override it. `DCC_MCP_UNITY_BRIDGE_TIMEOUT` may increase the 60-second RPC timeout but cannot
lower it; queued Editor work expires first so timed-out mutations are not executed later.

The default bridge targets one Unity Editor. For concurrent Editors, run one adapter per Editor and
assign each pair a unique bridge port and URL before starting either process.

## Standalone sidecar

Hosts without an embedded Python runtime can use the PyOxidizer sidecar released with each version.
The release asset contains the executable, its adjacent `lib/` runtime, and `SHA256SUMS`. Configure
the Unity package to start it on editor load by setting `DCC_MCP_UNITY_SIDECAR_PATH`; optionally set
`DCC_MCP_UNITY_SIDECAR_SHA256` to the published digest. The launcher is loopback-only, passes the
Unity process id to `--watch-pid`, and uses a per-project pid file to avoid duplicate sidecars after
assembly reloads.

For local development, run `dcc-mcp-unity-standalone --bridge-port 3852 --watch-pid <unity-pid>`.

## Agent workflow

1. Load `unity-project` and call `inspect_project` before assuming project or editor state. Stop if
   the returned project is not the intended target or the Editor is compiling, updating, entering
   Play Mode, or playing.
2. Load `unity-scene` and call `inspect_scene` immediately before using an instance ID. Treat IDs
   as opaque values and return them unchanged. Unity 6000.5+ emits decimal strings; older Editors
   retain integer output, and both forms are accepted as input.
3. Create GameObjects or change transforms through typed operations backed by Unity Undo.
4. Verify the hierarchy, then explicitly call `save_scene`.
5. Load `unity-diagnostics` and call `read_console` after failures or as a final verification step.

Do not automatically retry a timed-out scene mutation. Inspect the project and scene first because
the Editor may have completed the original request near the timeout boundary.

No raw C# evaluation, shell command, or arbitrary filesystem write is exposed. The Editor bridge
accepts only the methods implemented in `DccMcpCommands` and executes them on Unity's editor update
loop. Mutations fail closed during compilation, asset updates, and Play Mode. Requests, queued work,
scene snapshots, Console reads, and serialized responses have explicit size or lifetime budgets.

## Validation boundary

Public CI validates Python 3.9 and 3.12 on Windows, macOS, and Linux; validates the bundled skill
contracts; performs static checks for the UPM package and main-thread/Undo contracts; and builds the
PyPI artifacts. Trusted pull requests, `main`, and the weekly schedule also compile the UPM package
and run its command, scene, Undo, and validation tests through GameCI in Unity 2018.4.36f1,
2021.3.45f1, and 6000.5.4f1. Fork pull requests skip the licensed Editor jobs because GitHub does
not expose repository secrets to forks. Licensed runs share one repository-wide queue across pull
requests, `main`, releases, and schedules so a Personal seat is never activated concurrently. Each
Editor also completes a real WebSocket `hello` → `project.inspect` → response smoke against the
Python sidecar and records the reported Editor version as an artifact.

## Development

```bash
uv sync --extra dev
uv run python -m pytest
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run python tools/lint_skills.py
uv run python -m build
uv run python -m twine check dist/*
```

Unity and the Unity cube logo are trademarks of Unity Technologies. This independent adapter is
not affiliated with or endorsed by Unity Technologies.
