unity-game-dev · diff
git:20260713.cae357c to git:20261103.53717ea
88 added, 77 removed. Audit A to B.
---
name: unity-game-dev
- description: Use when the user wants to create, set up, or open a Unity project with AI assistance, install the Unity-MCP plugin, or connect Unity to ai-game.dev. Covers project creation, plugin install, login, and opening the editor via unity-mcp-cli.
+ description: Use when the user wants to create, set up, or open a Unity project with AI, install the Unity-MCP plugin or its extensions, sign in to ai-game.dev, connect the editor, or wire Claude Code / Codex to Unity's MCP tools. Drives unity-mcp-cli end to end.
---
# Unity — AI Game Dev runbook
This skill teaches your AI coding assistant (Claude Code or Codex CLI) to drive **Unity** fully
automatically through the `unity-mcp-cli` npm package. The goal: take the user from nothing to a
running Unity Editor that is **connected to [ai-game.dev](https://ai-game.dev)** so the AI can
build the game for them.
Every command runs via `npx` so nothing needs to be installed globally:
```bash
- npx -y unity-mcp-cli@latest <command> [args]
+ npx -y unity-mcp-cli@latest <command> [args] # <command> --help shows every flag
```
## Prerequisites (check first)
- - **Node.js 18+** — `node --version`.
- - **Unity Hub + a Unity Editor** installed (e.g. Unity 6). `create-project` uses **Unity Hub**
- to scaffold and to resolve the editor version; the requested version must be installed.
- - **A free ai-game.dev account** — the `login` step authorizes the project against the cloud.
+ - **Node.js 20.19+ or 22.12+** — `node --version`.
+ - **Unity Hub + a Unity Editor** (e.g. Unity 6). `create-project` and `install-unity` locate Unity
+ Hub and install it if it is missing. No editor yet? See step 0.
+ - **A free ai-game.dev account** — the `login` step signs this machine in.
- **Windows / macOS / Linux** with a real desktop session (the editor opens a window).
## The automatic end-to-end sequence
- Run these **in order**. Do not skip the ordering rule around `close → login → open`.
-
- ### 1. Create the project (fresh start only)
+ Run these **in order**. The one ordering rule: the editor must **start after a successful
+ `login`** (step 4).
- Skip this step if the user already has a project — go straight to step 2 pointing at it.
+ ### 0. Install a Unity Editor (only if none is installed)
```bash
- npx -y unity-mcp-cli@latest create-project "C:/Games/MyGame" --unity 6000.0.0f1
+ npx -y unity-mcp-cli@latest install-unity # latest stable release
+ npx -y unity-mcp-cli@latest install-unity 6000.3.1f1 # or an exact version
```
- - `create-project <path>` scaffolds a new Unity project at `<path>` via Unity Hub.
- - `--unity <version>` selects the installed editor version (must be installed in the Hub).
+ Installs the editor through Unity Hub. This is a large download — confirm with the user first.
- **Verify:** the `<path>` now contains `Assets/`, `Packages/`, and `ProjectSettings/`.
+ ### 1. Create the project (fresh start only)
- ### 2. Install the Unity-MCP plugin
+ Skip this step if the user already has a project — go straight to step 2 pointing at it.
```bash
- npx -y unity-mcp-cli@latest install-plugin "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest create-project "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest create-project "C:/Games/MyGame" --unity 6000.3.1f1 # pin a version
```
- Patches `Packages/manifest.json` to add the Unity-MCP package so the editor can expose its
- tools to the cloud AI. **Verify:** `Packages/manifest.json` now references the AI Game Developer
- package.
+ - Scaffolds a new Unity project at the path with an editor installed in Unity Hub.
+ - Without `--unity` it uses the **highest installed** editor version.
- ### 3. Close the editor before logging in
+ **Verify:** the path now contains `Assets/`, `Packages/`, and `ProjectSettings/`.
+ ### 2. Install the Unity-MCP plugin
+
```bash
- npx -y unity-mcp-cli@latest close "C:/Games/MyGame"
- # add --force if the editor won't exit cleanly
+ npx -y unity-mcp-cli@latest install-plugin "C:/Games/MyGame"
```
- **This ordering is critical.** The editor must **not** be running when you log in, because it
- reads the auth token from the project's `UserSettings` only at startup. If it is already open it
- would run with a stale (or missing) token. Always `close` before `login`. Use `--force` only if
- a normal close fails.
+ Adds the Unity-MCP package to `Packages/manifest.json` (latest version unless
+ `--plugin-version` is given). **Verify:** `Packages/manifest.json` references
+ `com.ivanmurzak.unity.mcp`.
- ### 4. Log in (interactive — device-code OAuth)
+ ### 3. Sign in (interactive, once per machine)
```bash
- npx -y unity-mcp-cli@latest login "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest login
```
- - Starts a **device-code OAuth flow** against ai-game.dev. The command prints a **verification
- URL** and a **user code**.
- - **Tell the user** to open the printed URL in a browser and enter the code to authorize.
- - On success the CLI writes into `<path>/UserSettings/AI-Game-Developer-Config.json`:
- - `cloudToken: <token>`
- - `connectionMode: "Cloud"`
+ - `login` takes **no project path**: it signs in **this machine** and stores the credential in the
+ shared machine store `~/.ai-game-dev/credentials.json`, which every engine plugin, CLI, and the
+ ai-game.dev desktop app read. If the machine is already signed in it prints
+ *Already signed in* and exits — continue.
+ - Otherwise it starts a **device-code OAuth flow** and prints a **verification URL** and a
+ **user code**. **Tell the user** to open the URL in a browser and enter the code.
- **Wait for the command to report success** before continuing.
- ### 5. Open the editor (auto-connects)
+ ### 4. (Re)start the editor (auto-connects)
```bash
- npx -y unity-mcp-cli@latest open "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest close "C:/Games/MyGame" # no-op when it isn't running; --force if it hangs
+ npx -y unity-mcp-cli@latest open "C:/Games/MyGame"
```
- Launches the Unity Editor. Because the project config is now in **Cloud** mode with a token, the
- plugin **auto-connects** to ai-game.dev on startup — no extra flag needed. Run `open` **only
- after a successful `login`.**
+ The plugin reads the machine credential **once, when the editor starts**. An editor that was
+ already running when you signed in keeps running without it — so `close` it, then `open`. Run
+ `open` **only after a successful `login`.** New projects default to **Cloud** mode, so the plugin
+ connects to ai-game.dev on startup with no extra flag. Unity's first launch imports packages and
+ compiles; it can take minutes.
- ### 6. Confirm the connection
+ ### 5. Confirm the connection
```bash
npx -y unity-mcp-cli@latest wait-for-ready "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest status "C:/Games/MyGame"
```
- Blocks until the editor has actually booted **and connected** to the cloud. **Do not tell the
- user the setup succeeded until this passes.** If it times out, see Troubleshooting.
+ `wait-for-ready` polls the project's MCP server (`/api/system-tools/ping`) until it answers;
+ default timeout 2 minutes (`--timeout <ms>`, e.g. `--timeout 600000` on a first launch). `status`
+ then reports whether Unity is running for this project and whether the MCP server is reachable.
+ **Do not tell the user setup succeeded until `wait-for-ready` passes and `status` shows Unity
+ running.**
- ### 7. Wire your AI assistant to the project's MCP tools
+ ### 6. Wire your AI assistant to the project's MCP tools
- Register the project's MCP server with the coding assistant you are running as, so it can call
- the engine's tools directly (create GameObjects, edit scenes, attach components, etc.). Pass the
- target that matches your assistant — **`claude-code`** for Claude Code, **`codex`** for Codex CLI.
- Run **only** the line that matches you:
+ Register the project's MCP server with the assistant you are running as, so it can call the
+ engine's tools directly (create GameObjects, edit scenes, attach components, etc.). Run **only**
+ the line that matches you:
```bash
- # If you are Claude Code:
+ # If you are Claude Code (writes <project>/.mcp.json):
npx -y unity-mcp-cli@latest setup-mcp claude-code "C:/Games/MyGame"
- # If you are Codex CLI:
- npx -y unity-mcp-cli@latest setup-mcp codex "C:/Games/MyGame"
+ # If you are Codex CLI (writes <project>/.codex/config.toml):
+ npx -y unity-mcp-cli@latest setup-mcp codex "C:/Games/MyGame"
```
- The same CLI also exposes `setup-skills <claude-code|codex>` if you want to (re)install this
- runbook into the assistant's own skills directory. After wiring MCP, drive the game build through
- those tools.
+ The config is pinned to this project and, in Cloud mode, carries a project key (`--oauth` writes a
+ URL-only config instead; `--list` shows every agent id). The assistant loads it on its next session
+ start in the project folder. Optional: `setup-skills <claude-code|codex> "<path>"` writes the
+ plugin's tool skills into `.claude/skills` or `.agents/skills` (needs the running editor).
- ### Anytime: check status
+ ## Optional: extensions and `exec`
```bash
- npx -y unity-mcp-cli@latest status "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest install-extension --list # what can be installed
+ npx -y unity-mcp-cli@latest install-extension Tilemap "C:/Games/MyGame" # adds the package + OpenUPM registry
+ npx -y unity-mcp-cli@latest exec --path "C:/Games/MyGame" "UnityEngine.Application.unityVersion"
```
- Reports whether the editor is running, logged in, and connected.
+ - **Extensions** add tool sets (Animation, Cinemachine, InputSystem, ProBuilder, Tilemap, …).
+ Install only what the game needs; Unity resolves the package on its next refresh.
+ - **`exec`** runs a C# snippet in the editor (the last expression is printed) — handy for a quick
+ check or scripted edit. With no editor open it starts a **headless** one and keeps it warm
+ (quits after 300 s idle); `close --owned-only "<path>"` stops only an editor the CLI started.
## One-shot summary
```bash
- # 1. create (fresh only) 2. install 3. close 4. login 5. open 6. verify 7. wire MCP
- npx -y unity-mcp-cli@latest create-project "C:/Games/MyGame" --unity 6000.0.0f1
- npx -y unity-mcp-cli@latest install-plugin "C:/Games/MyGame"
- npx -y unity-mcp-cli@latest close "C:/Games/MyGame"
- npx -y unity-mcp-cli@latest login "C:/Games/MyGame" # interactive: open URL + code
- npx -y unity-mcp-cli@latest open "C:/Games/MyGame"
- npx -y unity-mcp-cli@latest wait-for-ready "C:/Games/MyGame"
- npx -y unity-mcp-cli@latest setup-mcp <your-agent> "C:/Games/MyGame" # <your-agent> = claude-code OR codex
+ # 1. create (fresh only) 2. install 3. login 4. (re)start 5. verify 6. wire MCP
+ npx -y unity-mcp-cli@latest create-project "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest install-plugin "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest login # interactive: URL + code
+ npx -y unity-mcp-cli@latest close "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest open "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest wait-for-ready "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest status "C:/Games/MyGame"
+ npx -y unity-mcp-cli@latest setup-mcp <your-agent> "C:/Games/MyGame" # claude-code OR codex
```
## Troubleshooting
- - **`create-project` fails / version not found** — the requested Unity version isn't installed
- in Unity Hub. Install it in the Hub (or pass a version that is) and retry.
+ - **`create-project` fails: no editors / version not found** — install one with
+ `install-unity [version]`, or pass a `--unity` version that is installed in the Hub.
- **`login` never completes** — the user has not finished the browser step. Re-print the
- verification URL and user code and wait. Ensure the ai-game.dev account is verified.
- - **`open` doesn't connect** — login didn't persist. `close`, re-run `login`, confirm
- `UserSettings/AI-Game-Developer-Config.json` has `cloudToken` and `connectionMode: "Cloud"`,
- then `open` again.
- - **`wait-for-ready` times out** — Unity may still be importing packages/compiling on first
- launch (can take minutes). Wait and re-run. Check `status`.
+ verification URL and code and wait. Ensure the ai-game.dev account is verified.
+ - **Wrong account / need to sign in again** — `login --force` (add `--yes` to confirm switching
+ accounts), then `close` + `open` the editor.
+ - **Editor runs but doesn't connect** — it started before `login`. `close`, then `open` again.
+ - **`wait-for-ready` times out** — Unity may still be importing or compiling on first launch.
+ Re-run with a longer `--timeout`, and check `status`.
- **Editor won't close** — add `--force` to `close`.
- - **Editor opened before login** — `close` it, run `login`, then `open` again so the fresh token
- is picked up at startup.
## Golden rules
- 1. Always **`close` before `login`**, and **`open` only after a successful `login`**.
+ 1. **`login` before the editor starts**; if it was already open, `close` then `open` it.
2. Never declare success until **`wait-for-ready`** passes.
- 3. `login` is **interactive** — always relay the verification URL + code to the user and wait.
- 4. Unity **auto-connects** on `open` when the config is in Cloud mode with a token — no URL flag.
+ 3. `login` is **interactive** — relay the verification URL + code to the user and wait.
+ 4. `login` is machine-wide — never pass it a project path (`--project` is a per-project override).
Learn more at **[ai-game.dev](https://ai-game.dev)**.