# 入门 — Unreal Engine · AI Game Developer Wiki

首次连接 Unreal MCP，登录 ai-game.dev，配置好 AI 客户端，并在 Unreal Editor 中运行你的第一批 AI 提示词。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unreal/getting-started)。

本页将带你从已安装插件一路走到在 Unreal Editor 中完成第一次由 AI 驱动的改动。前提是 you 已完成[安装](https://ai-game.dev/zh-hans/docs/wiki/unreal/installation)。

## 第 1 步：打开 AI Game Developer 窗口

1. 在 Unreal Editor 中打开你的项目（可以从应用中点击 **Open Editor**、使用 `unreal-mcp-cli open ./YourProject`，或按你平时的方式打开）。
2. 打开 **Tools** 菜单，选择 **AI Game Developer**。

这个窗口是插件的主界面。从上到下依次显示：日志级别、打开日志文件夹的按钮和插件版本；**Connection** 区域；**AI agent** 区域；**Extensions** 区域；以及帮助和问题反馈的链接。

## 第 2 步：连接到服务器

**Connection** 区域有一个 **Custom / Cloud** 开关。**Cloud** 是默认选项，也是大多数人的正确选择：它使用 ai-game.dev 上托管的服务器，因此本地无需运行任何东西。

1. 确认已选中 **Cloud**。
2. 点击 **Authorize**。窗口会显示一个验证链接和一个简短的用户代码。
3. 打开该链接（或使用 **Open verification page**），登录 ai-game.dev，输入代码并批准。
4. 窗口会显示 **已授权 — 已登录到 AI Game Dev。**

如果你已经在这台机器上通过 `unreal-mcp-cli login` 或 AI Game Dev 应用登录过，编辑器可以直接复用该登录状态。首次批准之后，后续启动编辑器时会自动重连，无需任何点击。

留意状态行。带绿点的 **Unreal：已连接** 表示插件、桥接和服务器已经连通。**Unreal：正在连接…** 在桥接启动时持续几秒钟属于正常现象。

\*\*注意：\*\*想把一切留在自己的机器上？那就改选 **Custom**，并运行本地的 `gamedev-mcp-server`。[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/unreal/connecting-ai-clients#custom)介绍了具体做法。

## 第 3 步：连接你的 AI 客户端

**AI agent** 区域会替你配置 AI 客户端。

1. 从下拉菜单中选择你的 agent，例如 Claude Code、Cursor、Visual Studio Code (Copilot)、Codex 或 Gemini。
2. 点击 **Configure**。插件会向该 agent 的 MCP 配置文件中写入一条 Unreal MCP 条目。
3. 如果该 agent 已在运行，请重启或重新加载它，以便它加载新的服务器。

在终端中，你也可以用 CLI 做同样的事。以 Claude Code 为例：

```bash
unreal-mcp-cli setup-mcp claude-code --path ./YourProject
```

这会在项目文件夹中写入 `.mcp.json`。运行 `unreal-mcp-cli setup-mcp --list` 可以查看所有受支持的 agent 及其配置文件所在位置。所有选项见[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/unreal/connecting-ai-clients)。

当 agent 连接成功后，它会出现在 Connection 区域的 **AI agents** 行中。

## 第 4 步：检查连接

向你的 agent 提一个只有编辑器才能回答的问题：

```text
List the actors in the current level with their class names.
```

agent 应该调用 `rql-query`，并用你当前打开关卡中的真实 actor 来回答。如果它说自己没有 Unreal 工具，说明客户端没有加载 MCP 服务器；请参阅[故障排除](https://ai-game.dev/zh-hans/docs/wiki/unreal/troubleshooting#agent-no-tools)。

## 第 5 步：你的第一批真实提示词

从小处、具体处开始。下面几个提示词展示了不同的工具类别：

```text
Spawn three cubes in a row and a point light above them.
```

```text
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.
```

```text
Take a screenshot of the viewport and tell me what you see.
```

```text
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 最佳实践](https://ai-game.dev/docs/best-practices/unreal)。

## 后续步骤

- 在[工具](https://ai-game.dev/zh-hans/docs/wiki/unreal/tools)中查看 agent 能做的全部事情。
- 通过[扩展](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)添加 Niagara、PCG、Enhanced Input 及更多功能。
- 在[配置](https://ai-game.dev/zh-hans/docs/wiki/unreal/configuration)中微调可见性、超时和日志记录。
- 使用 [CLI 参考](https://ai-game.dev/zh-hans/docs/wiki/unreal/cli)从脚本中驱动编辑器。

---

Source (HTML): https://ai-game.dev/zh-hans/docs/wiki/unreal/getting-started

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/unreal/getting-started