From 8aadf4691f8d89730ceec58d15766943aea23ed2 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Wed, 4 Nov 2026 17:35:55 +0200 Subject: [PATCH 1/2] feat(engine-unity): replace unity-mcp with Unity CLI integration - Rewrite /setup-engine Unity guidance around the Unity CLI and the com.unity.pipeline package, with `unity mcp` as the optional stdio fallback for clients without shell access - Replace CoplayDev tool names in the five Unity specialist agents and their module copies - Update setup requirements, quick start, README and module metadata - Point opencode.json at the local `unity mcp` server, still disabled - Keep the community package documented only as an older-Unity fallback Refs: docs/framework/setup-requirements.md --- .../agents/unity-addressables-specialist.md | 6 + .agents/agents/unity-dots-specialist.md | 6 + .agents/agents/unity-shader-specialist.md | 6 + .agents/agents/unity-specialist.md | 7 +- .agents/agents/unity-ui-specialist.md | 6 + .../modules/core/skills/setup-engine/SKILL.md | 126 ++++++++++++++---- .../agents/unity-addressables-specialist.md | 6 +- .../agents/unity-dots-specialist.md | 6 +- .../agents/unity-shader-specialist.md | 6 +- .../engine-unity/agents/unity-specialist.md | 6 +- .../agents/unity-ui-specialist.md | 6 +- .agents/modules/engine-unity/modulefile.yaml | 2 +- .agents/skills/setup-engine/SKILL.md | 126 ++++++++++++++---- .../modules/core/skills/setup-engine/SKILL.md | 126 ++++++++++++++---- .../agents/unity-addressables-specialist.md | 6 +- .../agents/unity-dots-specialist.md | 6 +- .../agents/unity-shader-specialist.md | 6 +- .../engine-unity/agents/unity-specialist.md | 6 +- .../agents/unity-ui-specialist.md | 6 +- .../modules/engine-unity/modulefile.yaml | 2 +- README.md | 2 +- docs/framework/quick-start.md | 22 +-- docs/framework/setup-requirements.md | 108 +++++++++------ opencode.json | 4 +- 24 files changed, 449 insertions(+), 160 deletions(-) diff --git a/.agents/agents/unity-addressables-specialist.md b/.agents/agents/unity-addressables-specialist.md index be988b0..4e9f6f5 100644 --- a/.agents/agents/unity-addressables-specialist.md +++ b/.agents/agents/unity-addressables-specialist.md @@ -162,6 +162,12 @@ handle.Completed += OnAssetLoaded; - Override unity-specialist architecture without discussion - Approve dependency changes without technical-director sign-off +## Unity CLI Integration + +- Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. +- Run `unity test` for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. + ## Delegation Map **Reports to**: `unity-specialist` diff --git a/.agents/agents/unity-dots-specialist.md b/.agents/agents/unity-dots-specialist.md index cc0b9d2..e8380cc 100644 --- a/.agents/agents/unity-dots-specialist.md +++ b/.agents/agents/unity-dots-specialist.md @@ -146,6 +146,12 @@ Before writing any code: - Override unity-specialist architecture without discussion - Implement non-ECS gameplay systems directly (delegate to gameplay-programmer) +## Unity CLI Integration + +- Run `unity recompile` after ECS changes and `unity status` to surface Safe Mode compile errors before running anything. +- Verify ECS code in-editor with `unity command script eval` (for example, create entities and step a system), then `unity command editor.playmode start` to run it and `unity command console get` for Burst/Jobs errors. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`script_eval`, `editor_playmode_start`, `console_get`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. + ## Delegation Map **Reports to**: `unity-specialist` diff --git a/.agents/agents/unity-shader-specialist.md b/.agents/agents/unity-shader-specialist.md index 59b075f..3c9bf68 100644 --- a/.agents/agents/unity-shader-specialist.md +++ b/.agents/agents/unity-shader-specialist.md @@ -175,6 +175,12 @@ Before writing any code: - Override unity-specialist architecture without discussion - Implement non-rendering gameplay systems directly (delegate to gameplay-programmer) +## Unity CLI Integration + +- Edit shader and material files with your own file tools, then run `unity recompile` to catch shader compile errors; read them with `unity command console get`. +- Use `unity command` to discover the project's material and asset commands, and `unity command script eval` for material property changes that need the live Editor. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `script_eval`, and the material/asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. + ## Delegation Map **Reports to**: `unity-specialist` diff --git a/.agents/agents/unity-specialist.md b/.agents/agents/unity-specialist.md index 2131544..12831a5 100644 --- a/.agents/agents/unity-specialist.md +++ b/.agents/agents/unity-specialist.md @@ -133,10 +133,11 @@ Before writing any code: - Using `DontDestroyOnLoad` excessively — prefer a scene management pattern - Ignoring script execution order for init-dependent systems -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server for Unity project inspection and asset management when available -- MCP server provides: scene hierarchy, component inspection, asset database queries +- Use the Unity CLI as the default editor bridge: `unity status` confirms the Editor is connected, then `unity command` lists the commands the project's Pipeline package exposes. +- Audit state and verify behavior with `unity command scene get_hierarchy` and `unity command console get`; use `unity command script eval` for in-editor checks, and `unity recompile` after C# changes. +- MCP is optional and only for clients without shell access: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `console_get`, `script_eval`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. ## Delegation Map diff --git a/.agents/agents/unity-ui-specialist.md b/.agents/agents/unity-ui-specialist.md index 2420368..fd5af93 100644 --- a/.agents/agents/unity-ui-specialist.md +++ b/.agents/agents/unity-ui-specialist.md @@ -214,6 +214,12 @@ Before writing any code: - Override unity-specialist architecture without discussion - Implement non-UI gameplay systems directly (delegate to gameplay-programmer) +## Unity CLI Integration + +- Use `unity command` to discover the project's scene and UI commands, and `unity command scene get_hierarchy` to inspect Canvas/uGUI or UI Toolkit hierarchies. +- Scaffold UI through the Editor's commands where the Pipeline package exposes them; use `unity command script eval` for ad-hoc setup, `unity recompile` after script changes, and `unity command editor.playmode start` to run the scene. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `script_eval`, `editor_playmode_start`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. + ## Delegation Map **Reports to**: `unity-specialist` diff --git a/.agents/modules/core/skills/setup-engine/SKILL.md b/.agents/modules/core/skills/setup-engine/SKILL.md index 45b6e48..e29e8a1 100644 --- a/.agents/modules/core/skills/setup-engine/SKILL.md +++ b/.agents/modules/core/skills/setup-engine/SKILL.md @@ -440,62 +440,132 @@ Optionally set `GODOT_PATH` if the Godot binary is not in PATH: } ``` -### 7.4. Configure unity-mcp (Optional — Unity Only) +### 7.4. Configure Unity agent access (Optional — Unity Only) -> **What it is:** A bridge between AI agents and Unity Editor via MCP, exposing ~50+ tools for scene, script, and asset management. Maintained by CoplayDev, MIT licensed. See [github.com/CoplayDev/unity-mcp](https://github.com/CoplayDev/unity-mcp). +> **What it is:** Unity's official agent integration. The [Unity CLI](https://docs.unity.com/unity-cli) drives a running Unity 6+ Editor through the project's `com.unity.pipeline` package, and its built-in `unity mcp` command exposes the same Editor commands to MCP clients. This replaces the community CoplayDev `unity-mcp` package the framework previously recommended. Unity deprecated the in-Editor MCP server in `com.unity.ai.assistant`; the CLI is its supported replacement, and third-party MCP packages are unaffected. #### Prerequisites (must be installed first) -- **Unity 2021.3 LTS or newer** — [Download Unity](https://unity.com/download) -- **Python 3.10+** with `uv` — install `uv` via `pip install uv` (or `winget install astral-sh.uv` on Windows) -- **MCP for Unity package** installed in your Unity project (see below) +- **Unity 6.0 (6000.0) or newer** — the Pipeline package requires Unity 6.0+ to drive the Editor. +- **Unity CLI** — the Hub installs and updates it by default. Verify with `unity --version`; if missing, install it: + - Windows (PowerShell): `irm https://unity.com/install.ps1 | iex` + - macOS / Linux: `curl -fsSL https://unity.com/install.sh | bash` +- **Pipeline package** in the Unity project — `unity pipeline install --project-path ` (or add `com.unity.pipeline` through Package Manager). -#### Install steps +#### Recommended setup (agents that can run shell commands) -In your Unity project, open **Window → Package Manager**, click the **`+`** button, choose **Add package from git URL...**, and paste: +OCGS agents run shell commands, so use the CLI directly. It exposes more Editor commands than the MCP server and needs no server process. +1. Open the project in Unity 6+ and confirm the Editor is reachable: + + ```bash + unity status --project-path /path/to/MyProject + ``` + + Expect `state: ready` (or a list of running Editors). `unity status` also reports Safe Mode and its compile errors. + +2. Discover the commands this Editor exposes, then drive it: + + ```bash + unity command --project-path /path/to/MyProject + unity command scene get_hierarchy --project-path /path/to/MyProject + unity command console get --project-path /path/to/MyProject + unity command editor.playmode start --project-path /path/to/MyProject + unity recompile --strict --project-path /path/to/MyProject + unity test --project-path /path/to/MyProject + ``` + + Command names come from the project's Pipeline package. Use `unity command` rather than guessing, and `unity commands --grep ` to search the CLI, plugin and Editor command lists. + +3. Optionally install Unity's own agent skills where supported: + + ```bash + unity skill install --list + unity skill install opencode # OpenCode + unity skill install claude-code # Claude Code + ``` + + OpenCode also has `unity setup opencode`, which installs the skills and a session plugin. `unity setup all` configures every detected client and deliberately does **not** register an MCP server for clients that can run shell commands. Pi and omp are not supported by `unity skill install`; use the CLI directly with the Unity specialist agents. + +#### MCP fallback (clients without shell access, or if you prefer MCP tools) + +`unity mcp` (Unity CLI 0.1.0-beta.8 or later) is the CLI's own stdio MCP server, not the deprecated in-Editor server. It starts even when no Editor is running and exposes a `unity-cli-status` tool until one connects. Tool names are the Editor command names with spaces and dots replaced by underscores (`scene_get_hierarchy`, `console_get`, `script_eval`); check `tools/list` for the names your Editor exposes, because an older Pipeline package may use flat names such as `eval` and `run_tests`. + +Register it automatically where supported: + +```bash +unity mcp configure --list # supported clients and config paths +unity mcp configure claude-code # also: cursor, vscode, windsurf, cline, codex, zed, ... ``` -https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main + +`unity mcp configure` supports 16 clients but not OpenCode, Pi, or omp. It can also remove an entry left by the deprecated in-Editor server: + +```bash +unity mcp configure cursor --replace-legacy ``` -> Use `#beta` instead of `#main` for the latest beta features. `#main` is recommended for stability and currently tracks the v9.7.0 release. +Manual config for the harnesses OCGS documents: -After the package imports, MCP for Unity opens a **setup wizard** automatically: +**OpenCode** — add to `mcp.servers` in `opencode.json`: -1. Confirm Python and `uv` are installed — the wizard guides you through both if missing. -2. Click **Done**. Once dependencies are green, a list of detected MCP clients appears. -3. Pick the clients you want to configure and click **Configure Selected**. +```json +"unity": { + "type": "local", + "command": ["unity", "mcp"], + "disabled": true, + "codemode": false +} +``` -> **Note:** The wizard's per-client list (Claude Desktop, Cursor, Claude Code, VS Code, Windsurf, Cline, etc.) does not explicitly mention OpenCode or Pi. The wizard MAY auto-configure `opencode.json` or `pi.json` (verify by checking the file after); if it does not, use the manual config below. +**Pi** — add to the user-level `~/.pi/agent/mcp.json` (Pi ignores a project `.pi/mcp.json` until the project is trusted). `exposure: "direct"` is required; the default `codemode` exposure hides the tools from the model: -#### Manual MCP config (reliable fallback) +```json +{ + "mcpServers": { + "unity": { + "command": "unity", + "args": ["mcp"], + "enabled": false, + "exposure": "direct" + } + } +} +``` -Add this block to `mcp.servers` in your harness config (`opencode.json` for OpenCode, `pi.json` for Pi): +**omp** — add to `.omp/mcp.json` in the project: ```json -"unity": { - "type": "remote", - "url": "http://localhost:8080/mcp", - "disabled": true +{ + "mcpServers": { + "unity": { + "type": "stdio", + "command": "unity", + "args": ["mcp"], + "enabled": false + } + } } ``` -`disabled: true` keeps it off (servers connect automatically otherwise). Set `disabled` to `false` once Unity Editor is running and you want OCGS agents to use unity-mcp tools. +Keep the entry disabled until you want a session to use MCP tools, then restart the client. Pass `--project-path ` in `args` when the client starts outside the Unity project or more than one Editor is open. Add `--cli-tools` for six read-only CLI tools that work with no Editor running, and `--tools` / `--exclude-tools` to keep the tool list small. -> ⚠ **Unity Editor must be running** before OCGS agents can use unity-mcp tools. If the Editor is closed, MCP calls will fail with a connection error. Open your project in Unity, then continue. +> ⚠ **The Unity Editor must be running** for Editor commands to work. With no Editor, `unity status` reports none and MCP sessions expose only `unity-cli-status`; start the Editor and open the project, then retry. #### Verify -In a session where `disabled` is `false`, call any unity-mcp tool (e.g. `list_scenes`) via OCGS. Expect a list of scenes from your open Unity project. +- CLI: `unity status --project-path ` reports `state: ready`, and `unity command --project-path ` lists commands. +- MCP: with the entry enabled and the client restarted, call `unity-cli-status`, then `scene_get_hierarchy`. A connected Editor adds its commands as tools automatically. #### Troubleshooting -- **Bridge not connecting** — Open **Window → MCP for Unity** and check the status panel. Restart Unity if needed. -- **Server not starting** — Verify `uv --version` works in your terminal. Check the MCP for Unity log for errors. -- **Client not connecting** — Confirm the HTTP server is running on `localhost:8080` and the URL in your client config matches. -- **Port 8080 conflict** — Open Unity's MCP for Unity window and change the port; update the `url` in your harness MCP config to match. +- **`unity` not found** — reopen the shell after installing; check `unity --version`. +- **No Editor found** — the project is not open in Unity 6+, the Pipeline package is missing (`unity pipeline install`), or the Editor is still loading. Check `unity status` and the Editor console. +- **Safe Mode** — a compile error stops the Pipeline package from loading. `unity status` lists the errors; fix them, then retry `unity recompile`. +- **MCP client shows only `unity-cli-status`** — no Editor is connected. Start Unity, open the project, then call `unity-cli-status` again; the client picks up the new tools through `tools/list_changed`. +- **Two Unity servers / duplicate tools** — an old `unity-mcp` entry from the deprecated in-Editor server is still present. Run `unity mcp configure --replace-legacy`. +- **Pi shows no tools** — set `exposure: "direct"` in the Pi entry. ---- +> **Unity 2021.3–5.x:** the Unity CLI can only drive Unity 6.0+ Editors. On older projects, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by Unity's deprecation, but it is no longer the framework default. Prefer upgrading to Unity 6 when you can. ### 7.5. Configure Autopilot Playtesting (Optional — Godot 4.7+, OpenCode, Pi or omp) diff --git a/.agents/modules/engine-unity/agents/unity-addressables-specialist.md b/.agents/modules/engine-unity/agents/unity-addressables-specialist.md index fee967f..3bf0336 100644 --- a/.agents/modules/engine-unity/agents/unity-addressables-specialist.md +++ b/.agents/modules/engine-unity/agents/unity-addressables-specialist.md @@ -163,6 +163,8 @@ handle.Completed += OnAssetLoaded; - Work with **level-designer** for scene streaming boundaries - Work with **unity-ui-specialist** for UI asset loading patterns -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`manage_asset` for Addressable groups and assets, `manage_package` for Addressables package management, `read_console`) to verify Addressables groups build and watch for build errors in the Unity console. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. +- Run `unity test` for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/modules/engine-unity/agents/unity-dots-specialist.md b/.agents/modules/engine-unity/agents/unity-dots-specialist.md index 1b86d86..484f098 100644 --- a/.agents/modules/engine-unity/agents/unity-dots-specialist.md +++ b/.agents/modules/engine-unity/agents/unity-dots-specialist.md @@ -146,6 +146,8 @@ Before writing any code: - Work with **engine-programmer** for low-level optimization - Work with **unity-shader-specialist** for Entities Graphics rendering -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`create_script`, `script_apply_edits`, `validate_script`, `manage_scene` with action `load`) to verify ECS code compiles and runs in-editor. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Run `unity recompile` after ECS changes and `unity status` to surface Safe Mode compile errors before running anything. +- Verify ECS code in-editor with `unity command script eval` (for example, create entities and step a system), then `unity command editor.playmode start` to run it and `unity command console get` for Burst/Jobs errors. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`script_eval`, `editor_playmode_start`, `console_get`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/modules/engine-unity/agents/unity-shader-specialist.md b/.agents/modules/engine-unity/agents/unity-shader-specialist.md index c19bd74..61e461e 100644 --- a/.agents/modules/engine-unity/agents/unity-shader-specialist.md +++ b/.agents/modules/engine-unity/agents/unity-shader-specialist.md @@ -176,6 +176,8 @@ Before writing any code: - Work with **unity-dots-specialist** for Entities Graphics rendering - Work with **unity-ui-specialist** for UI shader effects -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`manage_material`, `manage_asset` for shader files, `read_console`) to apply material/shader changes and watch for shader compile errors in the Unity console. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Edit shader and material files with your own file tools, then run `unity recompile` to catch shader compile errors; read them with `unity command console get`. +- Use `unity command` to discover the project's material and asset commands, and `unity command script eval` for material property changes that need the live Editor. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `script_eval`, and the material/asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/modules/engine-unity/agents/unity-specialist.md b/.agents/modules/engine-unity/agents/unity-specialist.md index 051a0df..5d31bfa 100644 --- a/.agents/modules/engine-unity/agents/unity-specialist.md +++ b/.agents/modules/engine-unity/agents/unity-specialist.md @@ -182,6 +182,8 @@ Always involve this agent when: - Building for any platform - Optimizing with Unity-specific tools -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`read_console`, `manage_scene` with actions `get_active` / `get_hierarchy`, resource `mcpforunity://editor/state`) to audit project state and verify in-editor behavior during development sessions. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Use the Unity CLI as the default editor bridge: `unity status` confirms the Editor is connected, then `unity command` lists the commands the project's Pipeline package exposes. +- Audit state and verify behavior with `unity command scene get_hierarchy` and `unity command console get`; use `unity command script eval` for in-editor checks, and `unity recompile` after C# changes. +- MCP is optional and only for clients without shell access: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `console_get`, `script_eval`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/modules/engine-unity/agents/unity-ui-specialist.md b/.agents/modules/engine-unity/agents/unity-ui-specialist.md index a628282..4c2f3e5 100644 --- a/.agents/modules/engine-unity/agents/unity-ui-specialist.md +++ b/.agents/modules/engine-unity/agents/unity-ui-specialist.md @@ -215,6 +215,8 @@ Before writing any code: - Work with **localization-lead** for text fitting and localization - Work with **accessibility-specialist** for compliance -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`manage_ui` for UI Toolkit workflows, `manage_scene` for Canvas/uGUI hierarchies, `create_script` for UI scripts) to scaffold UI hierarchies and run scenes to verify UI behavior. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Use `unity command` to discover the project's scene and UI commands, and `unity command scene get_hierarchy` to inspect Canvas/uGUI or UI Toolkit hierarchies. +- Scaffold UI through the Editor's commands where the Pipeline package exposes them; use `unity command script eval` for ad-hoc setup, `unity recompile` after script changes, and `unity command editor.playmode start` to run the scene. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `script_eval`, `editor_playmode_start`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/modules/engine-unity/modulefile.yaml b/.agents/modules/engine-unity/modulefile.yaml index 68f13a1..2ae2822 100644 --- a/.agents/modules/engine-unity/modulefile.yaml +++ b/.agents/modules/engine-unity/modulefile.yaml @@ -1,6 +1,6 @@ name: engine-unity version: "0.6.0" -description: "Unity engine specialists — DOTS/ECS, shaders, Addressables, UI. Includes unity-mcp integration for interactive AI-assisted dev." +description: "Unity engine specialists — DOTS/ECS, shaders, Addressables, UI. Includes Unity CLI integration for interactive AI-assisted dev." depends: [core] provides: agents: [unity-specialist, unity-dots-specialist, unity-shader-specialist, diff --git a/.agents/skills/setup-engine/SKILL.md b/.agents/skills/setup-engine/SKILL.md index 54c4e5b..0c2ac9e 100644 --- a/.agents/skills/setup-engine/SKILL.md +++ b/.agents/skills/setup-engine/SKILL.md @@ -760,60 +760,132 @@ Optionally set `GODOT_PATH` if the Godot binary is not in PATH: } ``` -### 7.4. Configure unity-mcp (Optional — Unity Only) +### 7.4. Configure Unity agent access (Optional — Unity Only) -> **What it is:** A bridge between AI agents and Unity Editor via MCP, exposing ~50+ tools for scene, script, and asset management. Maintained by CoplayDev, MIT licensed. See [github.com/CoplayDev/unity-mcp](https://github.com/CoplayDev/unity-mcp). +> **What it is:** Unity's official agent integration. The [Unity CLI](https://docs.unity.com/unity-cli) drives a running Unity 6+ Editor through the project's `com.unity.pipeline` package, and its built-in `unity mcp` command exposes the same Editor commands to MCP clients. This replaces the community CoplayDev `unity-mcp` package the framework previously recommended. Unity deprecated the in-Editor MCP server in `com.unity.ai.assistant`; the CLI is its supported replacement, and third-party MCP packages are unaffected. #### Prerequisites (must be installed first) -- **Unity 2021.3 LTS or newer** — [Download Unity](https://unity.com/download) -- **Python 3.10+** with `uv` — install `uv` via `pip install uv` (or `winget install astral-sh.uv` on Windows) -- **MCP for Unity package** installed in your Unity project (see below) +- **Unity 6.0 (6000.0) or newer** — the Pipeline package requires Unity 6.0+ to drive the Editor. +- **Unity CLI** — the Hub installs and updates it by default. Verify with `unity --version`; if missing, install it: + - Windows (PowerShell): `irm https://unity.com/install.ps1 | iex` + - macOS / Linux: `curl -fsSL https://unity.com/install.sh | bash` +- **Pipeline package** in the Unity project — `unity pipeline install --project-path ` (or add `com.unity.pipeline` through Package Manager). -#### Install steps +#### Recommended setup (agents that can run shell commands) -In your Unity project, open **Window → Package Manager**, click the **`+`** button, choose **Add package from git URL...**, and paste: +OCGS agents run shell commands, so use the CLI directly. It exposes more Editor commands than the MCP server and needs no server process. +1. Open the project in Unity 6+ and confirm the Editor is reachable: + + ```bash + unity status --project-path /path/to/MyProject + ``` + + Expect `state: ready` (or a list of running Editors). `unity status` also reports Safe Mode and its compile errors. + +2. Discover the commands this Editor exposes, then drive it: + + ```bash + unity command --project-path /path/to/MyProject + unity command scene get_hierarchy --project-path /path/to/MyProject + unity command console get --project-path /path/to/MyProject + unity command editor.playmode start --project-path /path/to/MyProject + unity recompile --strict --project-path /path/to/MyProject + unity test --project-path /path/to/MyProject + ``` + + Command names come from the project's Pipeline package. Use `unity command` rather than guessing, and `unity commands --grep ` to search the CLI, plugin and Editor command lists. + +3. Optionally install Unity's own agent skills where supported: + + ```bash + unity skill install --list + unity skill install opencode # OpenCode + unity skill install claude-code # Claude Code + ``` + + OpenCode also has `unity setup opencode`, which installs the skills and a session plugin. `unity setup all` configures every detected client and deliberately does **not** register an MCP server for clients that can run shell commands. Pi and omp are not supported by `unity skill install`; use the CLI directly with the Unity specialist agents. + +#### MCP fallback (clients without shell access, or if you prefer MCP tools) + +`unity mcp` (Unity CLI 0.1.0-beta.8 or later) is the CLI's own stdio MCP server, not the deprecated in-Editor server. It starts even when no Editor is running and exposes a `unity-cli-status` tool until one connects. Tool names are the Editor command names with spaces and dots replaced by underscores (`scene_get_hierarchy`, `console_get`, `script_eval`); check `tools/list` for the names your Editor exposes, because an older Pipeline package may use flat names such as `eval` and `run_tests`. + +Register it automatically where supported: + +```bash +unity mcp configure --list # supported clients and config paths +unity mcp configure claude-code # also: cursor, vscode, windsurf, cline, codex, zed, ... ``` -https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main + +`unity mcp configure` supports 16 clients but not OpenCode, Pi, or omp. It can also remove an entry left by the deprecated in-Editor server: + +```bash +unity mcp configure cursor --replace-legacy ``` -> Use `#beta` instead of `#main` for the latest beta features. `#main` is recommended for stability and currently tracks the v9.7.0 release. +Manual config for the harnesses OCGS documents: -After the package imports, MCP for Unity opens a **setup wizard** automatically: +**OpenCode** — add to `mcp.servers` in `opencode.json`: -1. Confirm Python and `uv` are installed — the wizard guides you through both if missing. -2. Click **Done**. Once dependencies are green, a list of detected MCP clients appears. -3. Pick the clients you want to configure and click **Configure Selected**. +```json +"unity": { + "type": "local", + "command": ["unity", "mcp"], + "disabled": true, + "codemode": false +} +``` -> **Note:** The wizard's per-client list (Claude Desktop, Cursor, Claude Code, VS Code, Windsurf, Cline, etc.) does not explicitly mention OpenCode or Pi. The wizard MAY auto-configure `opencode.json` or `pi.json` (verify by checking the file after); if it does not, use the manual config below. +**Pi** — add to the user-level `~/.pi/agent/mcp.json` (Pi ignores a project `.pi/mcp.json` until the project is trusted). `exposure: "direct"` is required; the default `codemode` exposure hides the tools from the model: -#### Manual MCP config (reliable fallback) +```json +{ + "mcpServers": { + "unity": { + "command": "unity", + "args": ["mcp"], + "enabled": false, + "exposure": "direct" + } + } +} +``` -Add this block to `mcp.servers` in your harness config (`opencode.json` for OpenCode, `pi.json` for Pi): +**omp** — add to `.omp/mcp.json` in the project: ```json -"unity": { - "type": "remote", - "url": "http://localhost:8080/mcp", - "disabled": true +{ + "mcpServers": { + "unity": { + "type": "stdio", + "command": "unity", + "args": ["mcp"], + "enabled": false + } + } } ``` -`disabled: true` keeps it off (servers connect automatically otherwise). Set `disabled` to `false` once Unity Editor is running and you want OCGS agents to use unity-mcp tools. +Keep the entry disabled until you want a session to use MCP tools, then restart the client. Pass `--project-path ` in `args` when the client starts outside the Unity project or more than one Editor is open. Add `--cli-tools` for six read-only CLI tools that work with no Editor running, and `--tools` / `--exclude-tools` to keep the tool list small. -> ⚠ **Unity Editor must be running** before OCGS agents can use unity-mcp tools. If the Editor is closed, MCP calls will fail with a connection error. Open your project in Unity, then continue. +> ⚠ **The Unity Editor must be running** for Editor commands to work. With no Editor, `unity status` reports none and MCP sessions expose only `unity-cli-status`; start the Editor and open the project, then retry. #### Verify -In a session where `disabled` is `false`, call any unity-mcp tool (e.g. `list_scenes`) via OCGS. Expect a list of scenes from your open Unity project. +- CLI: `unity status --project-path ` reports `state: ready`, and `unity command --project-path ` lists commands. +- MCP: with the entry enabled and the client restarted, call `unity-cli-status`, then `scene_get_hierarchy`. A connected Editor adds its commands as tools automatically. #### Troubleshooting -- **Bridge not connecting** — Open **Window → MCP for Unity** and check the status panel. Restart Unity if needed. -- **Server not starting** — Verify `uv --version` works in your terminal. Check the MCP for Unity log for errors. -- **Client not connecting** — Confirm the HTTP server is running on `localhost:8080` and the URL in your client config matches. -- **Port 8080 conflict** — Open Unity's MCP for Unity window and change the port; update the `url` in your harness MCP config to match. +- **`unity` not found** — reopen the shell after installing; check `unity --version`. +- **No Editor found** — the project is not open in Unity 6+, the Pipeline package is missing (`unity pipeline install`), or the Editor is still loading. Check `unity status` and the Editor console. +- **Safe Mode** — a compile error stops the Pipeline package from loading. `unity status` lists the errors; fix them, then retry `unity recompile`. +- **MCP client shows only `unity-cli-status`** — no Editor is connected. Start Unity, open the project, then call `unity-cli-status` again; the client picks up the new tools through `tools/list_changed`. +- **Two Unity servers / duplicate tools** — an old `unity-mcp` entry from the deprecated in-Editor server is still present. Run `unity mcp configure --replace-legacy`. +- **Pi shows no tools** — set `exposure: "direct"` in the Pi entry. + +> **Unity 2021.3–5.x:** the Unity CLI can only drive Unity 6.0+ Editors. On older projects, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by Unity's deprecation, but it is no longer the framework default. Prefer upgrading to Unity 6 when you can. ### 7.5. Build & Run Setup (SFML 3 / Raylib — No MCP Available) diff --git a/.opencode/modules/core/skills/setup-engine/SKILL.md b/.opencode/modules/core/skills/setup-engine/SKILL.md index 45b6e48..e29e8a1 100644 --- a/.opencode/modules/core/skills/setup-engine/SKILL.md +++ b/.opencode/modules/core/skills/setup-engine/SKILL.md @@ -440,62 +440,132 @@ Optionally set `GODOT_PATH` if the Godot binary is not in PATH: } ``` -### 7.4. Configure unity-mcp (Optional — Unity Only) +### 7.4. Configure Unity agent access (Optional — Unity Only) -> **What it is:** A bridge between AI agents and Unity Editor via MCP, exposing ~50+ tools for scene, script, and asset management. Maintained by CoplayDev, MIT licensed. See [github.com/CoplayDev/unity-mcp](https://github.com/CoplayDev/unity-mcp). +> **What it is:** Unity's official agent integration. The [Unity CLI](https://docs.unity.com/unity-cli) drives a running Unity 6+ Editor through the project's `com.unity.pipeline` package, and its built-in `unity mcp` command exposes the same Editor commands to MCP clients. This replaces the community CoplayDev `unity-mcp` package the framework previously recommended. Unity deprecated the in-Editor MCP server in `com.unity.ai.assistant`; the CLI is its supported replacement, and third-party MCP packages are unaffected. #### Prerequisites (must be installed first) -- **Unity 2021.3 LTS or newer** — [Download Unity](https://unity.com/download) -- **Python 3.10+** with `uv` — install `uv` via `pip install uv` (or `winget install astral-sh.uv` on Windows) -- **MCP for Unity package** installed in your Unity project (see below) +- **Unity 6.0 (6000.0) or newer** — the Pipeline package requires Unity 6.0+ to drive the Editor. +- **Unity CLI** — the Hub installs and updates it by default. Verify with `unity --version`; if missing, install it: + - Windows (PowerShell): `irm https://unity.com/install.ps1 | iex` + - macOS / Linux: `curl -fsSL https://unity.com/install.sh | bash` +- **Pipeline package** in the Unity project — `unity pipeline install --project-path ` (or add `com.unity.pipeline` through Package Manager). -#### Install steps +#### Recommended setup (agents that can run shell commands) -In your Unity project, open **Window → Package Manager**, click the **`+`** button, choose **Add package from git URL...**, and paste: +OCGS agents run shell commands, so use the CLI directly. It exposes more Editor commands than the MCP server and needs no server process. +1. Open the project in Unity 6+ and confirm the Editor is reachable: + + ```bash + unity status --project-path /path/to/MyProject + ``` + + Expect `state: ready` (or a list of running Editors). `unity status` also reports Safe Mode and its compile errors. + +2. Discover the commands this Editor exposes, then drive it: + + ```bash + unity command --project-path /path/to/MyProject + unity command scene get_hierarchy --project-path /path/to/MyProject + unity command console get --project-path /path/to/MyProject + unity command editor.playmode start --project-path /path/to/MyProject + unity recompile --strict --project-path /path/to/MyProject + unity test --project-path /path/to/MyProject + ``` + + Command names come from the project's Pipeline package. Use `unity command` rather than guessing, and `unity commands --grep ` to search the CLI, plugin and Editor command lists. + +3. Optionally install Unity's own agent skills where supported: + + ```bash + unity skill install --list + unity skill install opencode # OpenCode + unity skill install claude-code # Claude Code + ``` + + OpenCode also has `unity setup opencode`, which installs the skills and a session plugin. `unity setup all` configures every detected client and deliberately does **not** register an MCP server for clients that can run shell commands. Pi and omp are not supported by `unity skill install`; use the CLI directly with the Unity specialist agents. + +#### MCP fallback (clients without shell access, or if you prefer MCP tools) + +`unity mcp` (Unity CLI 0.1.0-beta.8 or later) is the CLI's own stdio MCP server, not the deprecated in-Editor server. It starts even when no Editor is running and exposes a `unity-cli-status` tool until one connects. Tool names are the Editor command names with spaces and dots replaced by underscores (`scene_get_hierarchy`, `console_get`, `script_eval`); check `tools/list` for the names your Editor exposes, because an older Pipeline package may use flat names such as `eval` and `run_tests`. + +Register it automatically where supported: + +```bash +unity mcp configure --list # supported clients and config paths +unity mcp configure claude-code # also: cursor, vscode, windsurf, cline, codex, zed, ... ``` -https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main + +`unity mcp configure` supports 16 clients but not OpenCode, Pi, or omp. It can also remove an entry left by the deprecated in-Editor server: + +```bash +unity mcp configure cursor --replace-legacy ``` -> Use `#beta` instead of `#main` for the latest beta features. `#main` is recommended for stability and currently tracks the v9.7.0 release. +Manual config for the harnesses OCGS documents: -After the package imports, MCP for Unity opens a **setup wizard** automatically: +**OpenCode** — add to `mcp.servers` in `opencode.json`: -1. Confirm Python and `uv` are installed — the wizard guides you through both if missing. -2. Click **Done**. Once dependencies are green, a list of detected MCP clients appears. -3. Pick the clients you want to configure and click **Configure Selected**. +```json +"unity": { + "type": "local", + "command": ["unity", "mcp"], + "disabled": true, + "codemode": false +} +``` -> **Note:** The wizard's per-client list (Claude Desktop, Cursor, Claude Code, VS Code, Windsurf, Cline, etc.) does not explicitly mention OpenCode or Pi. The wizard MAY auto-configure `opencode.json` or `pi.json` (verify by checking the file after); if it does not, use the manual config below. +**Pi** — add to the user-level `~/.pi/agent/mcp.json` (Pi ignores a project `.pi/mcp.json` until the project is trusted). `exposure: "direct"` is required; the default `codemode` exposure hides the tools from the model: -#### Manual MCP config (reliable fallback) +```json +{ + "mcpServers": { + "unity": { + "command": "unity", + "args": ["mcp"], + "enabled": false, + "exposure": "direct" + } + } +} +``` -Add this block to `mcp.servers` in your harness config (`opencode.json` for OpenCode, `pi.json` for Pi): +**omp** — add to `.omp/mcp.json` in the project: ```json -"unity": { - "type": "remote", - "url": "http://localhost:8080/mcp", - "disabled": true +{ + "mcpServers": { + "unity": { + "type": "stdio", + "command": "unity", + "args": ["mcp"], + "enabled": false + } + } } ``` -`disabled: true` keeps it off (servers connect automatically otherwise). Set `disabled` to `false` once Unity Editor is running and you want OCGS agents to use unity-mcp tools. +Keep the entry disabled until you want a session to use MCP tools, then restart the client. Pass `--project-path ` in `args` when the client starts outside the Unity project or more than one Editor is open. Add `--cli-tools` for six read-only CLI tools that work with no Editor running, and `--tools` / `--exclude-tools` to keep the tool list small. -> ⚠ **Unity Editor must be running** before OCGS agents can use unity-mcp tools. If the Editor is closed, MCP calls will fail with a connection error. Open your project in Unity, then continue. +> ⚠ **The Unity Editor must be running** for Editor commands to work. With no Editor, `unity status` reports none and MCP sessions expose only `unity-cli-status`; start the Editor and open the project, then retry. #### Verify -In a session where `disabled` is `false`, call any unity-mcp tool (e.g. `list_scenes`) via OCGS. Expect a list of scenes from your open Unity project. +- CLI: `unity status --project-path ` reports `state: ready`, and `unity command --project-path ` lists commands. +- MCP: with the entry enabled and the client restarted, call `unity-cli-status`, then `scene_get_hierarchy`. A connected Editor adds its commands as tools automatically. #### Troubleshooting -- **Bridge not connecting** — Open **Window → MCP for Unity** and check the status panel. Restart Unity if needed. -- **Server not starting** — Verify `uv --version` works in your terminal. Check the MCP for Unity log for errors. -- **Client not connecting** — Confirm the HTTP server is running on `localhost:8080` and the URL in your client config matches. -- **Port 8080 conflict** — Open Unity's MCP for Unity window and change the port; update the `url` in your harness MCP config to match. +- **`unity` not found** — reopen the shell after installing; check `unity --version`. +- **No Editor found** — the project is not open in Unity 6+, the Pipeline package is missing (`unity pipeline install`), or the Editor is still loading. Check `unity status` and the Editor console. +- **Safe Mode** — a compile error stops the Pipeline package from loading. `unity status` lists the errors; fix them, then retry `unity recompile`. +- **MCP client shows only `unity-cli-status`** — no Editor is connected. Start Unity, open the project, then call `unity-cli-status` again; the client picks up the new tools through `tools/list_changed`. +- **Two Unity servers / duplicate tools** — an old `unity-mcp` entry from the deprecated in-Editor server is still present. Run `unity mcp configure --replace-legacy`. +- **Pi shows no tools** — set `exposure: "direct"` in the Pi entry. ---- +> **Unity 2021.3–5.x:** the Unity CLI can only drive Unity 6.0+ Editors. On older projects, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by Unity's deprecation, but it is no longer the framework default. Prefer upgrading to Unity 6 when you can. ### 7.5. Configure Autopilot Playtesting (Optional — Godot 4.7+, OpenCode, Pi or omp) diff --git a/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md b/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md index 5fcc78b..6e7ca89 100644 --- a/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md +++ b/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md @@ -163,6 +163,8 @@ handle.Completed += OnAssetLoaded; - Work with **level-designer** for scene streaming boundaries - Work with **unity-ui-specialist** for UI asset loading patterns -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`manage_asset` for Addressable groups and assets, `manage_package` for Addressables package management, `read_console`) to verify Addressables groups build and watch for build errors in the Unity console. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. +- Run `unity test` for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.opencode/modules/engine-unity/agents/unity-dots-specialist.md b/.opencode/modules/engine-unity/agents/unity-dots-specialist.md index 478b5af..a1f2d2d 100644 --- a/.opencode/modules/engine-unity/agents/unity-dots-specialist.md +++ b/.opencode/modules/engine-unity/agents/unity-dots-specialist.md @@ -146,6 +146,8 @@ Before writing any code: - Work with **engine-programmer** for low-level optimization - Work with **unity-shader-specialist** for Entities Graphics rendering -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`create_script`, `script_apply_edits`, `validate_script`, `manage_scene` with action `load`) to verify ECS code compiles and runs in-editor. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Run `unity recompile` after ECS changes and `unity status` to surface Safe Mode compile errors before running anything. +- Verify ECS code in-editor with `unity command script eval` (for example, create entities and step a system), then `unity command editor.playmode start` to run it and `unity command console get` for Burst/Jobs errors. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`script_eval`, `editor_playmode_start`, `console_get`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.opencode/modules/engine-unity/agents/unity-shader-specialist.md b/.opencode/modules/engine-unity/agents/unity-shader-specialist.md index 40afe79..3e88cab 100644 --- a/.opencode/modules/engine-unity/agents/unity-shader-specialist.md +++ b/.opencode/modules/engine-unity/agents/unity-shader-specialist.md @@ -176,6 +176,8 @@ Before writing any code: - Work with **unity-dots-specialist** for Entities Graphics rendering - Work with **unity-ui-specialist** for UI shader effects -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`manage_material`, `manage_asset` for shader files, `read_console`) to apply material/shader changes and watch for shader compile errors in the Unity console. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Edit shader and material files with your own file tools, then run `unity recompile` to catch shader compile errors; read them with `unity command console get`. +- Use `unity command` to discover the project's material and asset commands, and `unity command script eval` for material property changes that need the live Editor. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `script_eval`, and the material/asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.opencode/modules/engine-unity/agents/unity-specialist.md b/.opencode/modules/engine-unity/agents/unity-specialist.md index b07a287..5d0bde8 100644 --- a/.opencode/modules/engine-unity/agents/unity-specialist.md +++ b/.opencode/modules/engine-unity/agents/unity-specialist.md @@ -182,6 +182,8 @@ Always involve this agent when: - Building for any platform - Optimizing with Unity-specific tools -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`read_console`, `manage_scene` with actions `get_active` / `get_hierarchy`, resource `mcpforunity://editor/state`) to audit project state and verify in-editor behavior during development sessions. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Use the Unity CLI as the default editor bridge: `unity status` confirms the Editor is connected, then `unity command` lists the commands the project's Pipeline package exposes. +- Audit state and verify behavior with `unity command scene get_hierarchy` and `unity command console get`; use `unity command script eval` for in-editor checks, and `unity recompile` after C# changes. +- MCP is optional and only for clients without shell access: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `console_get`, `script_eval`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.opencode/modules/engine-unity/agents/unity-ui-specialist.md b/.opencode/modules/engine-unity/agents/unity-ui-specialist.md index 41f095b..fc2d3a2 100644 --- a/.opencode/modules/engine-unity/agents/unity-ui-specialist.md +++ b/.opencode/modules/engine-unity/agents/unity-ui-specialist.md @@ -215,6 +215,8 @@ Before writing any code: - Work with **localization-lead** for text fitting and localization - Work with **accessibility-specialist** for compliance -## MCP Integration +## Unity CLI Integration -- Use the unity-mcp server (`manage_ui` for UI Toolkit workflows, `manage_scene` for Canvas/uGUI hierarchies, `create_script` for UI scripts) to scaffold UI hierarchies and run scenes to verify UI behavior. Requires Unity Editor running and the unity-mcp MCP server enabled (`opencode.json` for OpenCode, `pi.json` for Pi). +- Use `unity command` to discover the project's scene and UI commands, and `unity command scene get_hierarchy` to inspect Canvas/uGUI or UI Toolkit hierarchies. +- Scaffold UI through the Editor's commands where the Pipeline package exposes them; use `unity command script eval` for ad-hoc setup, `unity recompile` after script changes, and `unity command editor.playmode start` to run the scene. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `script_eval`, `editor_playmode_start`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.opencode/modules/engine-unity/modulefile.yaml b/.opencode/modules/engine-unity/modulefile.yaml index 68f13a1..2ae2822 100644 --- a/.opencode/modules/engine-unity/modulefile.yaml +++ b/.opencode/modules/engine-unity/modulefile.yaml @@ -1,6 +1,6 @@ name: engine-unity version: "0.6.0" -description: "Unity engine specialists — DOTS/ECS, shaders, Addressables, UI. Includes unity-mcp integration for interactive AI-assisted dev." +description: "Unity engine specialists — DOTS/ECS, shaders, Addressables, UI. Includes Unity CLI integration for interactive AI-assisted dev." depends: [core] provides: agents: [unity-specialist, unity-dots-specialist, unity-shader-specialist, diff --git a/README.md b/README.md index fe939b4..a1c5c8a 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,7 @@ The framework is partitioned into **22 pluggable theme modules**. Only install w | `live-ops` | Post-launch content, community management | | `localization` | i18n, translation pipeline | | `engine-godot` | Godot 4 specialists (GDScript, C#, shaders, GDExtension) | -| `engine-unity` | Unity specialists (DOTS, shaders, Addressables, UI) + unity-mcp | +| `engine-unity` | Unity specialists (DOTS, shaders, Addressables, UI) + Unity CLI | | `engine-unreal` | Unreal Engine 5 specialists (GAS, Blueprint, replication, UMG) | | `engine-sfml3` | SFML 3 specialist (Graphics, Audio, Network, Window, System) | | `engine-raylib` | Raylib specialist (core, rlgl, raudio, raymath, raygui) | diff --git a/docs/framework/quick-start.md b/docs/framework/quick-start.md index 4cd63d1..1616ac1 100644 --- a/docs/framework/quick-start.md +++ b/docs/framework/quick-start.md @@ -233,15 +233,19 @@ If you already know what you need, jump directly to the relevant path: Once configured, run `/automated-smoke-test` to verify the project launches without errors. -4b. **Enhance with unity-mcp (Unity only)** — Install the CoplayDev unity-mcp - package in your Unity project for interactive AI-assisted dev: +4b. **Enhance with the Unity CLI (Unity only) — recommended** — Unity's + official agent integration drives a running Unity 6+ Editor through the + project's `com.unity.pipeline` package: + ```bash + unity status --project-path /path/to/MyProject # state: ready + unity command --project-path /path/to/MyProject # list Editor commands ``` - # In Unity: Window → Package Manager → + → Add package from git URL - # Paste: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main - ``` - Then add the `mcp.servers.unity` block to your MCP config (`opencode.json` for OpenCode, `pi.json` for Pi) and set - `disabled` to `false` once Unity Editor is running. See `/setup-engine` §7.4 - for full details. + If `unity` is missing, install it: `irm https://unity.com/install.ps1 | iex` + (Windows) or `curl -fsSL https://unity.com/install.sh | bash` (macOS/Linux). + For OpenCode, `unity setup opencode` also installs Unity's skills. + Agents that can run shell commands should use the CLI directly; MCP + (`unity mcp`) is only for clients without shell access. See `/setup-engine` + §7.4 for the MCP fallback and harness-specific config. 4c. **Optional: Autopilot playtesting (Godot 4.7+, OpenCode, Pi or omp)** — Autopilot plays your game open in the Godot editor and reports what it finds. Its results are automated evidence, never a human playtest. Set it up in the Autopilot section of `/setup-engine` (OpenCode, Pi or omp; other harnesses are not verified), or follow the Setup section of `/autopilot-playtest`. It needs the Autopilot addon, its agent service, and your own keys. 5. **Validate the concept** — Run `/design-review design/gdd/game-concept.md` 6. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies @@ -326,7 +330,7 @@ Available modules: art, design, architecture, stories, programming, ui, audio, n ``` AGENTS.md -- Master config (read this first) .opencode/ (opencode.json at root) -- OpenCode settings & plugin config -.pi/ (pi.json at root) -- Pi MCP & settings +.pi/ (settings, extensions; MCP at ~/.pi/agent/mcp.json) -- Pi settings extensions/ -- 7 Pi extensions (auto-discovered) agents/ -- Agent definitions (YAML frontmatter) skills/ -- Skill definitions (YAML frontmatter) diff --git a/docs/framework/setup-requirements.md b/docs/framework/setup-requirements.md index dc99d34..29080e3 100644 --- a/docs/framework/setup-requirements.md +++ b/docs/framework/setup-requirements.md @@ -99,49 +99,77 @@ The MCP server is configured via `opencode.json` or editor MCP settings. See `/s - `create_scene`, `add_node`, `save_scene` — scene manipulation - `get_godot_version`, `get_project_info`, `list_projects` — project introspection -### Unity-MCP (Optional — Unity Only) +### Unity CLI (Recommended — Unity Only) -The [unity-mcp](https://github.com/CoplayDev/unity-mcp) server (by CoplayDev) provides runtime tools for AI-assisted interaction with a running Unity Editor. It enables agents to manage assets, control scenes, edit scripts, and read the Editor console during development sessions. +Unity's official agent integration is the [Unity CLI](https://docs.unity.com/unity-cli). When an agent can run shell commands, it drives a running Unity 6+ Editor directly through the project's `com.unity.pipeline` package. Unity deprecated the in-Editor MCP server in `com.unity.ai.assistant`; the CLI is its supported replacement. This replaces the community CoplayDev `unity-mcp` package the framework previously recommended. **Prerequisites:** -- Unity 2021.3 LTS or newer -- Python 3.10+ with `uv` (install via `pip install uv` or `winget install astral-sh.uv`) - -**Installation:** - -The unity-mcp server runs as a package inside Unity Editor (not a standalone CLI). Install via the Unity Package Manager: - -``` -# In Unity: Window → Package Manager → + → Add package from git URL -# Paste: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main -``` - -Then click **Window → MCP for Unity → "Configure All Detected Clients"** to auto-configure detected MCP clients. OpenCode may require manual config — see below. - -**Configuration:** - -Add this block to `mcp.servers` in your `opencode.json` (the wizard may auto-configure, but manual is the reliable fallback): - -```json -"unity": { - "type": "remote", - "url": "http://localhost:8080/mcp", - "disabled": true -} -``` - -Set `disabled` to `false` once Unity Editor is running. - -> ⚠ **Unity Editor must be running** before OCGS agents can use unity-mcp tools. If the Editor is closed, MCP calls will fail with a connection error. Open your project in Unity, then continue. - -**Tools provided (selection):** -- `manage_gameobject`, `manage_scene`, `find_gameobjects` — scene and GameObject management -- `create_script`, `script_apply_edits`, `validate_script` — script creation and editing -- `manage_material`, `manage_asset` — material and asset management -- `manage_ui` — UI Toolkit workflows -- `read_console` — Editor console output (errors, warnings, compile status) -- `run_tests` — async test execution (EditMode / PlayMode) -- `batch_execute` — multiple MCP commands in a single batch (10-100x faster) +- Unity 6.0 (6000.0) or newer for Editor control. +- The Unity CLI — the Hub installs and updates it by default. Verify with `unity --version`; install with `irm https://unity.com/install.ps1 | iex` (Windows PowerShell) or `curl -fsSL https://unity.com/install.sh | bash` (macOS/Linux). +- The `com.unity.pipeline` package in the project — `unity pipeline install --project-path `. + +**Setup:** +1. Open the project in Unity 6+. +2. Run `unity status --project-path ` and confirm `state: ready`. +3. Run `unity command --project-path ` to list the commands the Editor exposes. +4. Optional: install Unity's own skills for supported clients (`unity skill install --list`, then `unity skill install opencode`; OpenCode also has `unity setup opencode`). Pi and omp are not supported by `unity skill install`. + +**Usage:** `unity command scene get_hierarchy`, `unity command console get`, `unity command script eval`, `unity recompile`, `unity test`, `unity command editor.playmode start`. + +### Unity MCP (Optional — Unity Only) + +`unity mcp` (Unity CLI 0.1.0-beta.8 or later) is the CLI's built-in stdio MCP server. Use it only for clients that cannot run shell commands; the CLI itself exposes more commands than the MCP server. It replaces the deprecated in-Editor MCP server and does not use the old relay or port 8080. + +**Configure:** +- `unity mcp configure --list` lists supported clients and config paths; `unity mcp configure ` writes the entry. Add `--replace-legacy` to remove an old relay entry. +- OpenCode (`opencode.json`, `mcp.servers`): + + ```json + "unity": { + "type": "local", + "command": ["unity", "mcp"], + "disabled": true, + "codemode": false + } + ``` + +- Pi (`~/.pi/agent/mcp.json`; `exposure: "direct"` is required): + + ```json + { + "mcpServers": { + "unity": { + "command": "unity", + "args": ["mcp"], + "enabled": false, + "exposure": "direct" + } + } + } + ``` + +- omp (`.omp/mcp.json`): + + ```json + { + "mcpServers": { + "unity": { + "type": "stdio", + "command": "unity", + "args": ["mcp"], + "enabled": false + } + } + } + ``` + +- Pass `--project-path ` in `args` when the client starts outside the project or multiple Editors are open. + +**Tools provided (selection):** `unity-cli-status` (no Editor), `scene_get_hierarchy`, `console_get`, `script_eval`, `editor_playmode_start`, `test_run`, plus the Editor's other commands. Tool names replace spaces and dots with underscores; check `tools/list`, because an older Pipeline package may use flat names. `--cli-tools` adds six read-only CLI tools; `--tools` / `--exclude-tools` trim the list. + +> ⚠ **Unity Editor must be running** for Editor commands. Without one, MCP sessions expose only `unity-cli-status`; start Unity and open the project. + +**Older Unity:** the CLI drives Unity 6.0+ only. On Unity 2021.3–5.x, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by the deprecation, but it is no longer the framework default. ### Autopilot (Optional — Godot 4.7+ Only) diff --git a/opencode.json b/opencode.json index 79afbfd..5e29621 100644 --- a/opencode.json +++ b/opencode.json @@ -39,8 +39,8 @@ } }, "unity": { - "type": "remote", - "url": "http://localhost:8080/mcp", + "type": "local", + "command": ["unity", "mcp"], "disabled": true, "codemode": false } From a6e5177f3f4fccf9517366c6816e57fd8b73b66b Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Wed, 4 Nov 2026 17:57:37 +0200 Subject: [PATCH 2/2] docs(engine-unity): correct Unity CLI setup and migration guidance Refs: #116 --- .agents/agents/unity-addressables-specialist.md | 12 ++++++------ .agents/agents/unity-dots-specialist.md | 12 ++++++------ .agents/agents/unity-shader-specialist.md | 12 ++++++------ .agents/agents/unity-specialist.md | 12 ++++++------ .agents/agents/unity-ui-specialist.md | 12 ++++++------ .agents/modules/core/skills/setup-engine/SKILL.md | 9 ++++++--- .../agents/unity-addressables-specialist.md | 2 +- .agents/skills/automated-smoke-test/SKILL.md | 2 +- .agents/skills/setup-engine/SKILL.md | 9 ++++++--- .opencode/modules/core/skills/setup-engine/SKILL.md | 9 ++++++--- .../agents/unity-addressables-specialist.md | 2 +- .../modules/qa/skills/automated-smoke-test/SKILL.md | 2 +- docs/framework/quick-start.md | 3 ++- docs/framework/setup-requirements.md | 2 +- 14 files changed, 55 insertions(+), 45 deletions(-) diff --git a/.agents/agents/unity-addressables-specialist.md b/.agents/agents/unity-addressables-specialist.md index 4e9f6f5..ad44c37 100644 --- a/.agents/agents/unity-addressables-specialist.md +++ b/.agents/agents/unity-addressables-specialist.md @@ -162,12 +162,6 @@ handle.Completed += OnAssetLoaded; - Override unity-specialist architecture without discussion - Approve dependency changes without technical-director sign-off -## Unity CLI Integration - -- Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. -- Run `unity test` for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. -- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. - ## Delegation Map **Reports to**: `unity-specialist` @@ -178,3 +172,9 @@ handle.Completed += OnAssetLoaded; - Work with **devops-engineer** for CDN and content delivery pipeline - Work with **level-designer** for scene streaming boundaries - Work with **unity-ui-specialist** for UI asset loading patterns + +## Unity CLI Integration + +- Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. +- Run `unity test ` with the Editor closed for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. With the Editor open, use `unity command test.run --project-path ` instead, because `unity test` refuses an open project. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/agents/unity-dots-specialist.md b/.agents/agents/unity-dots-specialist.md index e8380cc..460c6dd 100644 --- a/.agents/agents/unity-dots-specialist.md +++ b/.agents/agents/unity-dots-specialist.md @@ -146,12 +146,6 @@ Before writing any code: - Override unity-specialist architecture without discussion - Implement non-ECS gameplay systems directly (delegate to gameplay-programmer) -## Unity CLI Integration - -- Run `unity recompile` after ECS changes and `unity status` to surface Safe Mode compile errors before running anything. -- Verify ECS code in-editor with `unity command script eval` (for example, create entities and step a system), then `unity command editor.playmode start` to run it and `unity command console get` for Burst/Jobs errors. -- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`script_eval`, `editor_playmode_start`, `console_get`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. - ## Delegation Map **Reports to**: `unity-specialist` @@ -161,3 +155,9 @@ Before writing any code: - Work with **performance-analyst** for profiling DOTS performance - Work with **engine-programmer** for low-level optimization - Work with **unity-shader-specialist** for Entities Graphics rendering + +## Unity CLI Integration + +- Run `unity recompile` after ECS changes and `unity status` to surface Safe Mode compile errors before running anything. +- Verify ECS code in-editor with `unity command script eval` (for example, create entities and step a system), then `unity command editor.playmode start` to run it and `unity command console get` for Burst/Jobs errors. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`script_eval`, `editor_playmode_start`, `console_get`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/agents/unity-shader-specialist.md b/.agents/agents/unity-shader-specialist.md index 3c9bf68..e836feb 100644 --- a/.agents/agents/unity-shader-specialist.md +++ b/.agents/agents/unity-shader-specialist.md @@ -175,12 +175,6 @@ Before writing any code: - Override unity-specialist architecture without discussion - Implement non-rendering gameplay systems directly (delegate to gameplay-programmer) -## Unity CLI Integration - -- Edit shader and material files with your own file tools, then run `unity recompile` to catch shader compile errors; read them with `unity command console get`. -- Use `unity command` to discover the project's material and asset commands, and `unity command script eval` for material property changes that need the live Editor. -- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `script_eval`, and the material/asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. - ## Delegation Map **Reports to**: `unity-specialist` @@ -191,3 +185,9 @@ Before writing any code: - Work with **performance-analyst** for GPU performance profiling - Work with **unity-dots-specialist** for Entities Graphics rendering - Work with **unity-ui-specialist** for UI shader effects + +## Unity CLI Integration + +- Edit shader and material files with your own file tools, then run `unity recompile` to catch shader compile errors; read them with `unity command console get`. +- Use `unity command` to discover the project's material and asset commands, and `unity command script eval` for material property changes that need the live Editor. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `script_eval`, and the material/asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/agents/unity-specialist.md b/.agents/agents/unity-specialist.md index 12831a5..bd3950c 100644 --- a/.agents/agents/unity-specialist.md +++ b/.agents/agents/unity-specialist.md @@ -133,12 +133,6 @@ Before writing any code: - Using `DontDestroyOnLoad` excessively — prefer a scene management pattern - Ignoring script execution order for init-dependent systems -## Unity CLI Integration - -- Use the Unity CLI as the default editor bridge: `unity status` confirms the Editor is connected, then `unity command` lists the commands the project's Pipeline package exposes. -- Audit state and verify behavior with `unity command scene get_hierarchy` and `unity command console get`; use `unity command script eval` for in-editor checks, and `unity recompile` after C# changes. -- MCP is optional and only for clients without shell access: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `console_get`, `script_eval`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. - ## Delegation Map **Reports to**: `technical-director` (via `lead-programmer`) @@ -187,3 +181,9 @@ Always involve this agent when: - Implementing UI with UI Toolkit or UGUI - Building for any platform - Optimizing with Unity-specific tools + +## Unity CLI Integration + +- Use the Unity CLI as the default editor bridge: `unity status` confirms the Editor is connected, then `unity command` lists the commands the project's Pipeline package exposes. +- Audit state and verify behavior with `unity command scene get_hierarchy` and `unity command console get`; use `unity command script eval` for in-editor checks, and `unity recompile` after C# changes. +- MCP is optional and only for clients without shell access: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `console_get`, `script_eval`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/agents/unity-ui-specialist.md b/.agents/agents/unity-ui-specialist.md index fd5af93..1b5f028 100644 --- a/.agents/agents/unity-ui-specialist.md +++ b/.agents/agents/unity-ui-specialist.md @@ -214,12 +214,6 @@ Before writing any code: - Override unity-specialist architecture without discussion - Implement non-UI gameplay systems directly (delegate to gameplay-programmer) -## Unity CLI Integration - -- Use `unity command` to discover the project's scene and UI commands, and `unity command scene get_hierarchy` to inspect Canvas/uGUI or UI Toolkit hierarchies. -- Scaffold UI through the Editor's commands where the Pipeline package exposes them; use `unity command script eval` for ad-hoc setup, `unity recompile` after script changes, and `unity command editor.playmode start` to run the scene. -- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `script_eval`, `editor_playmode_start`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. - ## Delegation Map **Reports to**: `unity-specialist` @@ -230,3 +224,9 @@ Before writing any code: - Work with **unity-addressables-specialist** for UI asset loading - Work with **localization-lead** for text fitting and localization - Work with **accessibility-specialist** for compliance + +## Unity CLI Integration + +- Use `unity command` to discover the project's scene and UI commands, and `unity command scene get_hierarchy` to inspect Canvas/uGUI or UI Toolkit hierarchies. +- Scaffold UI through the Editor's commands where the Pipeline package exposes them; use `unity command script eval` for ad-hoc setup, `unity recompile` after script changes, and `unity command editor.playmode start` to run the scene. +- MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`scene_get_hierarchy`, `script_eval`, `editor_playmode_start`). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/modules/core/skills/setup-engine/SKILL.md b/.agents/modules/core/skills/setup-engine/SKILL.md index e29e8a1..437783d 100644 --- a/.agents/modules/core/skills/setup-engine/SKILL.md +++ b/.agents/modules/core/skills/setup-engine/SKILL.md @@ -414,7 +414,7 @@ npx @coding-solo/godot-mcp@latest ``` **MCP Configuration:** -Add the following to your harness MCP config (`opencode.json` for OpenCode, `pi.json` for Pi): +Add the following to your harness MCP config (`opencode.json` for OpenCode, `~/.pi/agent/mcp.json` for Pi): ```json { "mcpServers": { @@ -472,9 +472,10 @@ OCGS agents run shell commands, so use the CLI directly. It exposes more Editor unity command console get --project-path /path/to/MyProject unity command editor.playmode start --project-path /path/to/MyProject unity recompile --strict --project-path /path/to/MyProject - unity test --project-path /path/to/MyProject ``` + `unity test` starts its own batch Editor and refuses a project that is already open in an Editor. To run EditMode/PlayMode tests, close the Editor and run `unity test /path/to/MyProject`, or run the Pipeline's test command in the open Editor (`unity command test.run --project-path /path/to/MyProject`; `run_tests` on older packages). + Command names come from the project's Pipeline package. Use `unity command` rather than guessing, and `unity commands --grep ` to search the CLI, plugin and Editor command lists. 3. Optionally install Unity's own agent skills where supported: @@ -504,6 +505,8 @@ unity mcp configure claude-code # also: cursor, vscode, windsurf, cline, cod unity mcp configure cursor --replace-legacy ``` +If you are upgrading from the framework's previous CoplayDev `unity-mcp` setup, delete the old `"unity"` entry that points at `http://localhost:8080/mcp` from your harness config — `opencode.json`, Pi's `~/.pi/agent/mcp.json` or `.pi/mcp.json`, or `.omp/mcp.json` — by hand before adding the block below. `--replace-legacy` only removes entries left by Unity's deprecated in-Editor AI Assistant relay, and `unity mcp configure` does not support OpenCode, Pi, or omp. + Manual config for the harnesses OCGS documents: **OpenCode** — add to `mcp.servers` in `opencode.json`: @@ -562,7 +565,7 @@ Keep the entry disabled until you want a session to use MCP tools, then restart - **No Editor found** — the project is not open in Unity 6+, the Pipeline package is missing (`unity pipeline install`), or the Editor is still loading. Check `unity status` and the Editor console. - **Safe Mode** — a compile error stops the Pipeline package from loading. `unity status` lists the errors; fix them, then retry `unity recompile`. - **MCP client shows only `unity-cli-status`** — no Editor is connected. Start Unity, open the project, then call `unity-cli-status` again; the client picks up the new tools through `tools/list_changed`. -- **Two Unity servers / duplicate tools** — an old `unity-mcp` entry from the deprecated in-Editor server is still present. Run `unity mcp configure --replace-legacy`. +- **Two Unity servers / duplicate tools** — an old `unity` entry is still present. `unity mcp configure --replace-legacy` removes a relay entry left by Unity's deprecated in-Editor server in the 16 clients it supports; for OpenCode, Pi, and omp, delete the old entry by hand. - **Pi shows no tools** — set `exposure: "direct"` in the Pi entry. > **Unity 2021.3–5.x:** the Unity CLI can only drive Unity 6.0+ Editors. On older projects, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by Unity's deprecation, but it is no longer the framework default. Prefer upgrading to Unity 6 when you can. diff --git a/.agents/modules/engine-unity/agents/unity-addressables-specialist.md b/.agents/modules/engine-unity/agents/unity-addressables-specialist.md index 3bf0336..4f69ff2 100644 --- a/.agents/modules/engine-unity/agents/unity-addressables-specialist.md +++ b/.agents/modules/engine-unity/agents/unity-addressables-specialist.md @@ -166,5 +166,5 @@ handle.Completed += OnAssetLoaded; ## Unity CLI Integration - Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. -- Run `unity test` for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. +- Run `unity test ` with the Editor closed for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. With the Editor open, use `unity command test.run --project-path ` instead, because `unity test` refuses an open project. - MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.agents/skills/automated-smoke-test/SKILL.md b/.agents/skills/automated-smoke-test/SKILL.md index 13dc7c4..652e0c7 100644 --- a/.agents/skills/automated-smoke-test/SKILL.md +++ b/.agents/skills/automated-smoke-test/SKILL.md @@ -24,7 +24,7 @@ the version string. If it fails, inform the user: > "godot-mcp server is not available. Install it with: > `npx @coding-solo/godot-mcp` -> Then configure the MCP server in `opencode.json` (OpenCode) or `pi.json` (Pi)." +> Then configure the MCP server in `opencode.json` (OpenCode) or `~/.pi/agent/mcp.json` (Pi)." Stop if the server is unavailable. diff --git a/.agents/skills/setup-engine/SKILL.md b/.agents/skills/setup-engine/SKILL.md index 0c2ac9e..d9fd5f3 100644 --- a/.agents/skills/setup-engine/SKILL.md +++ b/.agents/skills/setup-engine/SKILL.md @@ -734,7 +734,7 @@ npx @coding-solo/godot-mcp@latest ``` **MCP Configuration:** -Add the following to your harness MCP config (`opencode.json` for OpenCode, `pi.json` for Pi): +Add the following to your harness MCP config (`opencode.json` for OpenCode, `~/.pi/agent/mcp.json` for Pi): ```json { "mcpServers": { @@ -792,9 +792,10 @@ OCGS agents run shell commands, so use the CLI directly. It exposes more Editor unity command console get --project-path /path/to/MyProject unity command editor.playmode start --project-path /path/to/MyProject unity recompile --strict --project-path /path/to/MyProject - unity test --project-path /path/to/MyProject ``` + `unity test` starts its own batch Editor and refuses a project that is already open in an Editor. To run EditMode/PlayMode tests, close the Editor and run `unity test /path/to/MyProject`, or run the Pipeline's test command in the open Editor (`unity command test.run --project-path /path/to/MyProject`; `run_tests` on older packages). + Command names come from the project's Pipeline package. Use `unity command` rather than guessing, and `unity commands --grep ` to search the CLI, plugin and Editor command lists. 3. Optionally install Unity's own agent skills where supported: @@ -824,6 +825,8 @@ unity mcp configure claude-code # also: cursor, vscode, windsurf, cline, cod unity mcp configure cursor --replace-legacy ``` +If you are upgrading from the framework's previous CoplayDev `unity-mcp` setup, delete the old `"unity"` entry that points at `http://localhost:8080/mcp` from your harness config — `opencode.json`, Pi's `~/.pi/agent/mcp.json` or `.pi/mcp.json`, or `.omp/mcp.json` — by hand before adding the block below. `--replace-legacy` only removes entries left by Unity's deprecated in-Editor AI Assistant relay, and `unity mcp configure` does not support OpenCode, Pi, or omp. + Manual config for the harnesses OCGS documents: **OpenCode** — add to `mcp.servers` in `opencode.json`: @@ -882,7 +885,7 @@ Keep the entry disabled until you want a session to use MCP tools, then restart - **No Editor found** — the project is not open in Unity 6+, the Pipeline package is missing (`unity pipeline install`), or the Editor is still loading. Check `unity status` and the Editor console. - **Safe Mode** — a compile error stops the Pipeline package from loading. `unity status` lists the errors; fix them, then retry `unity recompile`. - **MCP client shows only `unity-cli-status`** — no Editor is connected. Start Unity, open the project, then call `unity-cli-status` again; the client picks up the new tools through `tools/list_changed`. -- **Two Unity servers / duplicate tools** — an old `unity-mcp` entry from the deprecated in-Editor server is still present. Run `unity mcp configure --replace-legacy`. +- **Two Unity servers / duplicate tools** — an old `unity` entry is still present. `unity mcp configure --replace-legacy` removes a relay entry left by Unity's deprecated in-Editor server in the 16 clients it supports; for OpenCode, Pi, and omp, delete the old entry by hand. - **Pi shows no tools** — set `exposure: "direct"` in the Pi entry. > **Unity 2021.3–5.x:** the Unity CLI can only drive Unity 6.0+ Editors. On older projects, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by Unity's deprecation, but it is no longer the framework default. Prefer upgrading to Unity 6 when you can. diff --git a/.opencode/modules/core/skills/setup-engine/SKILL.md b/.opencode/modules/core/skills/setup-engine/SKILL.md index e29e8a1..437783d 100644 --- a/.opencode/modules/core/skills/setup-engine/SKILL.md +++ b/.opencode/modules/core/skills/setup-engine/SKILL.md @@ -414,7 +414,7 @@ npx @coding-solo/godot-mcp@latest ``` **MCP Configuration:** -Add the following to your harness MCP config (`opencode.json` for OpenCode, `pi.json` for Pi): +Add the following to your harness MCP config (`opencode.json` for OpenCode, `~/.pi/agent/mcp.json` for Pi): ```json { "mcpServers": { @@ -472,9 +472,10 @@ OCGS agents run shell commands, so use the CLI directly. It exposes more Editor unity command console get --project-path /path/to/MyProject unity command editor.playmode start --project-path /path/to/MyProject unity recompile --strict --project-path /path/to/MyProject - unity test --project-path /path/to/MyProject ``` + `unity test` starts its own batch Editor and refuses a project that is already open in an Editor. To run EditMode/PlayMode tests, close the Editor and run `unity test /path/to/MyProject`, or run the Pipeline's test command in the open Editor (`unity command test.run --project-path /path/to/MyProject`; `run_tests` on older packages). + Command names come from the project's Pipeline package. Use `unity command` rather than guessing, and `unity commands --grep ` to search the CLI, plugin and Editor command lists. 3. Optionally install Unity's own agent skills where supported: @@ -504,6 +505,8 @@ unity mcp configure claude-code # also: cursor, vscode, windsurf, cline, cod unity mcp configure cursor --replace-legacy ``` +If you are upgrading from the framework's previous CoplayDev `unity-mcp` setup, delete the old `"unity"` entry that points at `http://localhost:8080/mcp` from your harness config — `opencode.json`, Pi's `~/.pi/agent/mcp.json` or `.pi/mcp.json`, or `.omp/mcp.json` — by hand before adding the block below. `--replace-legacy` only removes entries left by Unity's deprecated in-Editor AI Assistant relay, and `unity mcp configure` does not support OpenCode, Pi, or omp. + Manual config for the harnesses OCGS documents: **OpenCode** — add to `mcp.servers` in `opencode.json`: @@ -562,7 +565,7 @@ Keep the entry disabled until you want a session to use MCP tools, then restart - **No Editor found** — the project is not open in Unity 6+, the Pipeline package is missing (`unity pipeline install`), or the Editor is still loading. Check `unity status` and the Editor console. - **Safe Mode** — a compile error stops the Pipeline package from loading. `unity status` lists the errors; fix them, then retry `unity recompile`. - **MCP client shows only `unity-cli-status`** — no Editor is connected. Start Unity, open the project, then call `unity-cli-status` again; the client picks up the new tools through `tools/list_changed`. -- **Two Unity servers / duplicate tools** — an old `unity-mcp` entry from the deprecated in-Editor server is still present. Run `unity mcp configure --replace-legacy`. +- **Two Unity servers / duplicate tools** — an old `unity` entry is still present. `unity mcp configure --replace-legacy` removes a relay entry left by Unity's deprecated in-Editor server in the 16 clients it supports; for OpenCode, Pi, and omp, delete the old entry by hand. - **Pi shows no tools** — set `exposure: "direct"` in the Pi entry. > **Unity 2021.3–5.x:** the Unity CLI can only drive Unity 6.0+ Editors. On older projects, the community [MCP for Unity](https://github.com/CoplayDev/unity-mcp) package still works and is unaffected by Unity's deprecation, but it is no longer the framework default. Prefer upgrading to Unity 6 when you can. diff --git a/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md b/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md index 6e7ca89..da37f06 100644 --- a/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md +++ b/.opencode/modules/engine-unity/agents/unity-addressables-specialist.md @@ -166,5 +166,5 @@ handle.Completed += OnAssetLoaded; ## Unity CLI Integration - Use `unity command` to discover the project's asset and package commands, then drive Addressables groups and assets through them; inspect the result with `unity command console get`. -- Run `unity test` for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. +- Run `unity test ` with the Editor closed for EditMode/PlayMode coverage and to surface Addressables build errors, and `unity recompile` after script changes. With the Editor open, use `unity command test.run --project-path ` instead, because `unity test` refuses an open project. - MCP is optional for shell-less clients: `unity mcp` exposes the same commands as tools (`console_get`, `test_run`, and the asset commands the Editor lists). Requires Unity 6.0+, `com.unity.pipeline`, and a running Editor. diff --git a/.opencode/modules/qa/skills/automated-smoke-test/SKILL.md b/.opencode/modules/qa/skills/automated-smoke-test/SKILL.md index 13dc7c4..652e0c7 100644 --- a/.opencode/modules/qa/skills/automated-smoke-test/SKILL.md +++ b/.opencode/modules/qa/skills/automated-smoke-test/SKILL.md @@ -24,7 +24,7 @@ the version string. If it fails, inform the user: > "godot-mcp server is not available. Install it with: > `npx @coding-solo/godot-mcp` -> Then configure the MCP server in `opencode.json` (OpenCode) or `pi.json` (Pi)." +> Then configure the MCP server in `opencode.json` (OpenCode) or `~/.pi/agent/mcp.json` (Pi)." Stop if the server is unavailable. diff --git a/docs/framework/quick-start.md b/docs/framework/quick-start.md index 1616ac1..76ebb18 100644 --- a/docs/framework/quick-start.md +++ b/docs/framework/quick-start.md @@ -244,7 +244,8 @@ If you already know what you need, jump directly to the relevant path: (Windows) or `curl -fsSL https://unity.com/install.sh | bash` (macOS/Linux). For OpenCode, `unity setup opencode` also installs Unity's skills. Agents that can run shell commands should use the CLI directly; MCP - (`unity mcp`) is only for clients without shell access. See `/setup-engine` + (`unity mcp`) is only needed for clients without shell access, or when you + prefer MCP tools. See `/setup-engine` §7.4 for the MCP fallback and harness-specific config. 4c. **Optional: Autopilot playtesting (Godot 4.7+, OpenCode, Pi or omp)** — Autopilot plays your game open in the Godot editor and reports what it finds. Its results are automated evidence, never a human playtest. Set it up in the Autopilot section of `/setup-engine` (OpenCode, Pi or omp; other harnesses are not verified), or follow the Setup section of `/autopilot-playtest`. It needs the Autopilot addon, its agent service, and your own keys. 5. **Validate the concept** — Run `/design-review design/gdd/game-concept.md` diff --git a/docs/framework/setup-requirements.md b/docs/framework/setup-requirements.md index 29080e3..2fd1b4f 100644 --- a/docs/framework/setup-requirements.md +++ b/docs/framework/setup-requirements.md @@ -121,7 +121,7 @@ Unity's official agent integration is the [Unity CLI](https://docs.unity.com/uni `unity mcp` (Unity CLI 0.1.0-beta.8 or later) is the CLI's built-in stdio MCP server. Use it only for clients that cannot run shell commands; the CLI itself exposes more commands than the MCP server. It replaces the deprecated in-Editor MCP server and does not use the old relay or port 8080. **Configure:** -- `unity mcp configure --list` lists supported clients and config paths; `unity mcp configure ` writes the entry. Add `--replace-legacy` to remove an old relay entry. +- `unity mcp configure --list` lists supported clients and config paths; `unity mcp configure ` writes the entry. Add `--replace-legacy` to remove an old relay entry, but note it only handles Unity's deprecated in-Editor AI Assistant relay and only in the 16 clients it supports. If you followed the framework's previous CoplayDev integration, delete the old `"unity"` entry pointing at `http://localhost:8080/mcp` from each harness config by hand. - OpenCode (`opencode.json`, `mcp.servers`): ```json