入门
首次连接 Unreal MCP，登录 ai-game.dev，配置好 AI 客户端，并在 Unreal Editor 中运行你的第一批 AI 提示词。
本页将带你从已安装插件一路走到在 Unreal Editor 中完成第一次由 AI 驱动的改动。前提是 you 已完成安装。
第 1 步：打开 AI Game Developer 窗口
- 在 Unreal Editor 中打开你的项目（可以从应用中点击 Open Editor、使用
unreal-mcp-cli open ./YourProject，或按你平时的方式打开）。 - 打开 Tools 菜单，选择 AI Game Developer。
这个窗口是插件的主界面。从上到下依次显示：日志级别、打开日志文件夹的按钮和插件版本；Connection 区域；AI agent 区域；Extensions 区域；以及帮助和问题反馈的链接。
第 2 步：连接到服务器
Connection 区域有一个 Custom / Cloud 开关。Cloud 是默认选项，也是大多数人的正确选择：它使用 ai-game.dev 上托管的服务器，因此本地无需运行任何东西。
- 确认已选中 Cloud。
- 点击 Authorize。窗口会显示一个验证链接和一个简短的用户代码。
- 打开该链接（或使用 Open verification page），登录 ai-game.dev，输入代码并批准。
- 窗口会显示 已授权 — 已登录到 AI Game Dev。
如果你已经在这台机器上通过 unreal-mcp-cli login 或 AI Game Dev 应用登录过，编辑器可以直接复用该登录状态。首次批准之后，后续启动编辑器时会自动重连，无需任何点击。
留意状态行。带绿点的 Unreal：已连接 表示插件、桥接和服务器已经连通。Unreal：正在连接… 在桥接启动时持续几秒钟属于正常现象。
**注意：**想把一切留在自己的机器上？那就改选 Custom，并运行本地的 gamedev-mcp-server。连接 AI 客户端介绍了具体做法。
第 3 步：连接你的 AI 客户端
AI agent 区域会替你配置 AI 客户端。
- 从下拉菜单中选择你的 agent，例如 Claude Code、Cursor、Visual Studio Code (Copilot)、Codex 或 Gemini。
- 点击 Configure。插件会向该 agent 的 MCP 配置文件中写入一条 Unreal MCP 条目。
- 如果该 agent 已在运行，请重启或重新加载它，以便它加载新的服务器。
在终端中，你也可以用 CLI 做同样的事。以 Claude Code 为例：
unreal-mcp-cli setup-mcp claude-code --path ./YourProject这会在项目文件夹中写入 .mcp.json。运行 unreal-mcp-cli setup-mcp --list 可以查看所有受支持的 agent 及其配置文件所在位置。所有选项见连接 AI 客户端。
当 agent 连接成功后，它会出现在 Connection 区域的 AI agents 行中。
第 4 步：检查连接
向你的 agent 提一个只有编辑器才能回答的问题：
List the actors in the current level with their class names.agent 应该调用 rql-query，并用你当前打开关卡中的真实 actor 来回答。如果它说自己没有 Unreal 工具，说明客户端没有加载 MCP 服务器；请参阅故障排除。
第 5 步：你的第一批真实提示词
从小处、具体处开始。下面几个提示词展示了不同的工具类别：
Spawn three cubes in a row and a point light above them.Create a new Actor Blueprint called BP_Coin with a static mesh component
using the engine sphere, compile it, and place three of them in the level.Take a screenshot of the viewport and tell me what you see.Create a C++ actor class called AHealthPickup with a float Heal property,
then compile the project and fix any errors.通过 RQL 做的每一次编辑器改动都是一个撤销步骤，因此在编辑器中按 Ctrl+Z 即可还原。编译工具会返回结构化的错误列表，所以"编译它并修复所有错误"是一个很好的后续提示词。
**提示：**截图工具需要真实的、由 GPU 支持的编辑器。当编辑器以 -nullrhi 运行时，它们会返回错误。
在 Unreal Editor 中使用 AI 的良好习惯
- 给事物命名。"改变标记为 KeyLight 的灯光的强度"比"改变灯光"效果更好。
- 让它先查看。"在你修改 BP_Door 之前，先给我看看它的组件"能让 agent 获得所需的事实。
- **让它验证。**改动之后要求它截图或编译。
- **保存你的工作。**在进行较大改动之前，让 agent 保存关卡，或在编辑器中保存。
- **保持会话专注。**每段对话只做一项任务，能让 agent 的上下文更小、更准确。
更多建议见 Unreal 最佳实践。