unreal-game-dev · diff
git:20260713.cae357c to git:20261103.53717ea
98 added, 74 removed. Audit A to A.
---
name: unreal-game-dev
- description: Use when the user wants to create, set up, or open an Unreal Engine project with AI assistance, install the Unreal-MCP plugin, or connect Unreal to ai-game.dev. Covers project creation, plugin install, login, and opening the editor via unreal-mcp-cli.
+ description: Use when the user wants to create, set up, or open an Unreal Engine project with AI, install the Unreal-MCP plugin or its extensions, sign in to ai-game.dev, connect the editor, or wire Claude Code / Codex to Unreal's MCP tools. Drives unreal-mcp-cli end to end.
---
# Unreal Engine — AI Game Dev runbook
This skill teaches your AI coding assistant (Claude Code or Codex CLI) to drive **Unreal
Engine** fully automatically through the `unreal-mcp-cli` npm package. The goal: take the user
from nothing to a running Unreal 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 unreal-mcp-cli@latest <command> [args]
+ npx -y unreal-mcp-cli@latest <command> [args] # <command> --help shows every flag
```
+ > **Path syntax differs by command:** `create-project`, `install-plugin`, `close`, `open`, and
+ > `install-extension` take the project path as a positional argument; `wait-for-ready`, `status`,
+ > `setup-mcp`, `setup-skills`, and `exec` take it as **`-p <path>`**.
+
## Prerequisites (check first)
- - **Node.js 18+** — `node --version`.
- - **Unreal Engine installed** (e.g. UE 5.7 via the Epic Games Launcher). The CLI drives the
- installed editor; it does not download the engine.
- - **A free ai-game.dev account** — the `login` step authorizes the project against the cloud.
+ - **Node.js 20.19+ or 22.12+** — `node --version`.
+ - **Unreal Engine installed** (e.g. UE 5.7 via the Epic Games Launcher). The CLI drives an installed
+ engine; it cannot install one unattended (see step 0).
+ - **A C++ toolchain** (Visual Studio on Windows, Xcode on macOS) — the scaffold is a C++ project and
+ `open` compiles its modules before launching.
+ - **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).
> **Naming rule:** an Unreal **project/module name cannot contain hyphens** (`-`). The folder
> path may contain hyphens, but pass a hyphen-free `--name` (e.g. `MyGame`, not `My-Game`).
## The automatic end-to-end sequence
- Run these **in order**. Do not skip the ordering rule around `close → login → open`.
+ Run these **in order**. The one ordering rule: the editor must **start after a successful
+ `login`** (step 4).
+ ### 0. Check the installed engines
+
+ ```bash
+ npx -y unreal-mcp-cli@latest install-engine # list installed engines
+ npx -y unreal-mcp-cli@latest install-engine 5.7 # is 5.7 installed? if not, links to the Epic launcher
+ ```
+
+ There is no unattended engine installer: a missing version is installed by the user through the
+ Epic Games Launcher (a multi-GB download — confirm first).
+
### 1. Create the project (fresh start only)
Skip this step if the user already has a project — go straight to step 2 pointing at it.
```bash
npx -y unreal-mcp-cli@latest create-project "C:/Games/MyGame" --name MyGame --engine 5.7
```
- - `create-project <path>` scaffolds a new Unreal project at `<path>`.
- - `--name <Name>` sets the project/module name (**no hyphens**).
- - `--engine <ver>` picks the installed engine version (e.g. `5.7`).
+ - Scaffolds a minimal Unreal C++ project at the path (`--force` allows a non-empty folder).
+ - `--name` sets the project/module name (**no hyphens**; defaults to the folder name).
+ - `--engine` sets the engine version baked into the `.uproject` (an installed version, e.g. `5.7`).
- **Verify:** the `<path>` now contains a `<Name>.uproject` file.
+ **Verify:** the path now contains `MyGame.uproject`.
### 2. Install the Unreal-MCP plugin
```bash
npx -y unreal-mcp-cli@latest install-plugin "C:/Games/MyGame"
```
- Installs the Unreal-MCP editor plugin into the project so the editor can expose its tools to
- the cloud AI. **Verify:** a `Plugins/UnrealMCP` folder now exists in the project.
-
- ### 3. Close the editor before logging in
-
- ```bash
- npx -y unreal-mcp-cli@latest close "C:/Games/MyGame"
- ```
-
- **This ordering is critical.** The editor must **not** be running when you log in, because the
- editor reads the auth token from the project's `.env` only at startup. If it is already open it
- would run with a stale (or missing) token. Always `close` before `login`.
+ Downloads the UnrealMCP plugin release matching the CLI version into the project. **Verify:** a
+ `Plugins/UnrealMCP` folder now exists, and `status -p "<path>"` shows `plugin: installed`.
- ### 4. Log in (interactive — device-code OAuth)
+ ### 3. Sign in (interactive, once per machine)
```bash
- npx -y unreal-mcp-cli@latest login -p "C:/Games/MyGame"
+ npx -y unreal-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>/.env`:
- - `UNREAL_MCP_TOKEN=<token>`
- - `UNREAL_MCP_CONNECTION_MODE=Cloud`
- - **Wait for the command to report success** before continuing. Do not claim you are logged in
- until it does.
+ - Run it **without `-p`**: 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. (`-p <path>` would write a per-project credential into the
+ project's `.env` instead.)
+ - Unreal's `login` always starts a new sign-in. If `~/.ai-game-dev/credentials.json` already exists
+ (this machine signed in through any engine CLI, editor, or the desktop app), skip this step.
+ - 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** ("Logged in.") before continuing.
- ### 5. Open the editor in Cloud mode
+ ### 4. (Re)start the editor in Cloud mode
```bash
- npx -y unreal-mcp-cli@latest open "C:/Games/MyGame" --connection-mode Cloud
+ npx -y unreal-mcp-cli@latest close "C:/Games/MyGame" # terminates it; ask the user to save first
+ npx -y unreal-mcp-cli@latest open "C:/Games/MyGame" --connection-mode Cloud
```
- Launches the Unreal Editor. Because the project's `.env` now has a token and Cloud mode, the
- plugin connects to ai-game.dev on startup. 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 (it reports when none
+ is running), then `open`. Run `open` **only after a successful `login`.** `open` compiles the
+ project's native modules when needed (`--no-build` skips it) and auto-dismisses known startup
+ dialogs; the first launch can take many minutes.
- ### 6. Confirm the connection
+ ### 5. Confirm the connection
```bash
- npx -y unreal-mcp-cli@latest wait-for-ready -p "C:/Games/MyGame"
+ npx -y unreal-mcp-cli@latest wait-for-ready -p "C:/Games/MyGame" --timeout 600000
+ npx -y unreal-mcp-cli@latest status -p "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; the example allows 10 for a first compile). `status` then shows the
+ project, plugin, connection URL, whether a token is present, and `reachable: yes`. **Do not tell
+ the user setup succeeded until `wait-for-ready` passes.**
- ### 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 (spawn actors, edit the level, run Blueprints, 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 (spawn actors, edit the level, run Blueprints, 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 unreal-mcp-cli@latest setup-mcp claude-code -p "C:/Games/MyGame"
- # If you are Codex CLI:
- npx -y unreal-mcp-cli@latest setup-mcp codex -p "C:/Games/MyGame"
+ # If you are Codex CLI (writes <project>/.codex/config.toml):
+ npx -y unreal-mcp-cli@latest setup-mcp codex -p "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; `--dry-run` prints it; `--list` shows every agent id). The assistant loads
+ it on its next session start in the project folder. `setup-skills -p "<path>"` only writes a
+ **Claude Code** skill stub (`.claude/skills/unreal-mcp/SKILL.md`); it has no Codex target.
- ### Anytime: check status
+ ## Optional: extensions and `exec`
```bash
- npx -y unreal-mcp-cli@latest status -p "C:/Games/MyGame"
+ npx -y unreal-mcp-cli@latest install-extension com.ivanmurzak.unreal-ai-niagara "C:/Games/MyGame"
+ npx -y unreal-mcp-cli@latest exec -p "C:/Games/MyGame" "unreal.SystemLibrary.get_engine_version()"
```
- Reports whether the editor is running, logged in, and connected.
+ - **Extensions** add tool sets (Niagara, EnhancedInput, PCG, GAS, Landscape, ControlRig); the id is
+ the extension id, name (e.g. `"Niagara Tools"`), or plugin name. The CLI places the plugin under
+ `Plugins/`, enables it in the `.uproject`, and it compiles on the next `open` (or now with
+ `--build`). Install only what the game needs.
+ - **`exec`** runs a **Python** 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
+ (saves and 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
+ # 1. create (fresh only) 2. install 3. login 4. (re)start 5. verify 6. wire MCP
npx -y unreal-mcp-cli@latest create-project "C:/Games/MyGame" --name MyGame --engine 5.7
- npx -y unreal-mcp-cli@latest install-plugin "C:/Games/MyGame"
- npx -y unreal-mcp-cli@latest close "C:/Games/MyGame"
- npx -y unreal-mcp-cli@latest login -p "C:/Games/MyGame" # interactive: open URL + code
- npx -y unreal-mcp-cli@latest open "C:/Games/MyGame" --connection-mode Cloud
- npx -y unreal-mcp-cli@latest wait-for-ready -p "C:/Games/MyGame"
- npx -y unreal-mcp-cli@latest setup-mcp <your-agent> -p "C:/Games/MyGame" # <your-agent> = claude-code OR codex
+ npx -y unreal-mcp-cli@latest install-plugin "C:/Games/MyGame"
+ npx -y unreal-mcp-cli@latest login # interactive: URL + code
+ npx -y unreal-mcp-cli@latest close "C:/Games/MyGame"
+ npx -y unreal-mcp-cli@latest open "C:/Games/MyGame" --connection-mode Cloud
+ npx -y unreal-mcp-cli@latest wait-for-ready -p "C:/Games/MyGame" --timeout 600000
+ npx -y unreal-mcp-cli@latest setup-mcp <your-agent> -p "C:/Games/MyGame" # claude-code OR codex
```
## Troubleshooting
- **Project name rejected / build fails on module name** — the name contains a hyphen. Use a
hyphen-free `--name`. The folder path may have hyphens; the module name may not.
+ - **Engine not found on `open`** — the `.uproject` engine version isn't installed. Check with
+ `install-engine`; for a source build pass `--engine-root <dir>` to `open`.
+ - **Build fails on `open`** — install the C++ toolchain (Visual Studio / Xcode) and retry.
- **`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` connects locally / not to Cloud** — you skipped or lost the login. `close`, re-run
- `login`, confirm `.env` has `UNREAL_MCP_TOKEN` and `UNREAL_MCP_CONNECTION_MODE=Cloud`, then
- `open --connection-mode Cloud` again.
- - **`wait-for-ready` times out** — the editor may still be compiling the plugin on first launch
- (this can take minutes). Wait and re-run. Check `status` for details.
- - **Editor opened before login** — `close` it, run `login`, then `open` again so the fresh token
- is picked up at startup.
- - **`npx` cannot find the CLI** — confirm Node 18+ and internet access; `@latest` pulls the
- current published version.
+ verification URL and code and wait. Ensure the ai-game.dev account is verified.
+ - **Different account already signed in** — `login` aborts unchanged; re-run with `--yes` to switch
+ this machine to the new account, then `close` + `open`.
+ - **Editor runs but doesn't connect** — it started before `login`, or the project `.env` overrides
+ the connection (`UNREAL_MCP_*` values). `close`, then `open --connection-mode Cloud`.
+ - **`wait-for-ready` times out** — the editor may still be compiling on first launch. Re-run with a
+ longer `--timeout`, and check `status`.
+ - **`npx` cannot find the CLI** — confirm Node 20.19+ / 22.12+ and internet access.
## 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. Unreal **module/project names have no hyphens**.
- 4. `login` is **interactive** — always relay the verification URL + code to the user and wait.
+ 4. `login` is **interactive** and machine-wide — relay the URL + code, and don't pass `-p`.
Learn more at **[ai-game.dev](https://ai-game.dev)**.