# Unreal Engine — Effective AI Requests

Unreal-MCP (branded "AI Game Developer — Unreal") is a C++ editor plugin for the Unreal Editor. It exposes Unreal Editor operations — spawning actors and components, editing levels and maps, authoring and compiling Blueprints, managing Content-Browser assets, reading/scaffolding/editing/compiling C++, and capturing viewport screenshots — as AI Tools, so an MCP-compatible AI client can drive the Unreal Editor through natural language. Because Unreal’s editor is C++, the .NET MCP host runs as an auto-managed sidecar process (unreal-mcp-bridge) the plugin spawns and talks to over localhost IPC.

_Last updated: 2026-06-17_

Unreal Engine 5.5+ (tested on 5.7), a C++ Unreal project. Install via unreal-mcp-cli (npm).

## Tool-family map

| Family | Tools | Purpose |
| --- | --- | --- |
| Actor & Component | 13 | Spawn/destroy/duplicate/find/modify actors; set-parent; add/get/modify/destroy/list components; get/modify any UObject by path. |
| Blueprint | 11 | Create Blueprint classes; add components; add/modify variables; set CDO defaults; add functions & events; compile (structured error/warning loop); spawn into level. |
| Asset & Content | 11 | AssetRegistry find/get-data; create-folder, copy, move, delete, refresh; Material Instance create/modify/get-data; FBX/texture import. |
| Editor & Reflection | 9 | Play-In-Editor get/set; selection get/set; console get/clear logs; run console command/CVar; UFunction find + call. |
| Level / Map | 7 | Create, open, save, get-data; list loaded sublevels (World-Partition aware); set-current; unload streaming sublevel. |
| Source / C++ | 6 | Read (sliced), create-class (header+cpp), update, delete, list module files, compile (Live Coding or UBT, structured error report). Jailed to <Project>/Source/. |
| Screenshot | 4 | Viewport, game view, camera (SceneCapture2D), isolated-actor renders. |
| Ping | 1 | Liveness probe — round-trips plugin ⇄ sidecar ⇄ server. |

Unreal-MCP’s core plugin exposes 62 tools across the 8 families listed here. On top of that, 6 Unreal-AI-* extension packages (via the IUnrealMcpToolProvider contract) now add a further 28 tools — Control Rig, Enhanced Input, GAS, Landscape, Niagara, and PCG — each gated on its wrapped UE engine plugin. See /docs/extensions/unreal.

## Example prompts

1. Create a new Actor blueprint with a static mesh cube and place three of them in the level.
2. Spawn a `StaticMeshActor` named `Crate` at the player start, then move it up by 200 units and rotate it 45 degrees.
3. Create a new level called `Arena`, open it, and list every actor in it.
4. Take a screenshot of the editor viewport so I can see the layout.
5. Create a new C++ Actor class called `Pickup`, add a Tick override, then compile the C++ and report any build errors.
6. Create a Blueprint named `BP_Door` that extends Actor, add a `StaticMeshComponent` called `Body`, then add a `BeginPlay` event.
7. Add a `TakeDamage` function to `BP_Player`, then compile `BP_Player` and tell me about any errors or warnings.

## Your first request

1. Open the AI Game Developer window from the editor Tools menu, choose Cloud, click Authorize, and wait for the connection to go green.
2. Ask your client: "Ping the Unreal plugin to check the connection."
3. Ask: "Spawn a StaticMeshActor named `Crate` at the world origin, then take a viewport screenshot."
4. Confirm the actor appears in the level and read back the screenshot.
5. Move into Blueprints — "Create a Blueprint named `BP_Door` that extends Actor, add a StaticMeshComponent, then compile it and report any errors."

## Discover what the agent can do

1. Ping the Unreal plugin to check the connection. (ping)
2. List every tool you can call, grouped by the 8 families.
3. What can you do with Blueprints specifically? (surfaces the 11-tool Blueprint family)
4. List every actor in the current level. (level-get-data)
5. Is the editor currently in Play-In-Editor? (editor-application-get-state)
6. Pick one family (e.g. Blueprint) and ask for a tiny concrete action plus a viewport screenshot.

## Common pitfalls

- C++ project required. The plugin builds an Editor module, so the host project must compile C++. A Blueprint-only project will not load it.
- The sidecar is auto-managed but real. If the connection will not go green, it is usually the unreal-mcp-bridge sidecar / IPC or auth, not the tools. ping round-trips the whole chain.
- Compiles block and can be slow. blueprint-compile and source-compile run inline on the game thread; expect a pause. The payoff is a structured error/warning list — "compile and fix the errors" is the intended loop.
- C++ source edits are jailed to <Project>/Source/ — the Source/C++ tools never touch engine source.

---

Source (HTML): https://ai-game.dev/docs/best-practices/unreal