# 快速开始 — Unity · AI Game Developer Wiki

使用 Unity MCP 将你的第一个 AI 智能体连接到 Unity 编辑器，检查连接状态，并在 Claude Code、Cursor 或 Copilot 中尝试你的第一批提示词。

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

本页将带你从已安装插件一路走到让 AI 智能体修改你的 Unity 场景。页面使用通过 ai-game.dev 的默认 Cloud 连接，并以 Claude Code 作为示例智能体；其他客户端步骤相同。如果插件尚未安装，请先从[安装](https://ai-game.dev/zh-hans/docs/wiki/unity/installation)开始。

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

在 Unity 中打开你的项目，选择 **Window > AI Game Developer — MCP**（Ctrl+Alt+A，macOS 上为 Cmd+Option+A）。该窗口的标签页名称为 **Game Developer**。你也可以点击 Scene View 工具栏中的 **AI** 按钮。

窗口以从上到下的时间线展示连接关系：先是 **Unity**，然后是 **MCP server**，最后是 **AI agent**。每个节点都有一个状态圆圈。你的目标是让这三个节点都变为绿色。

## 第 2 步：登录（Cloud 模式）

顶部的 **Connection** 开关有两个选项：**Custom** 和 **Cloud**。全新安装默认使用 **Cloud**。

1. 点击 **Cloud Token** 字段旁的 **Authorize**。
2. 浏览器会打开 ai-game.dev 的设备登录页面。窗口中会显示一个短代码（“Code: … — Authorize in browser”）。确认浏览器显示的代码与之一致，然后批准登录。
3. 该字段会变为“Signed in via account”，同时 Unity 状态变为 **Connected**。

登录信息会以整机为单位存储在 `~/.ai-game-dev/credentials.json` 中。如果你已经通过 `unity-mcp-cli login` 或 AI Game Dev 应用登录过，编辑器会自动读取该凭据，你可以跳过这一步。更多细节请参阅[身份验证](https://ai-game.dev/docs/auth)。

**说明**

试用插件无需账号。将连接切换为 **Custom**，即可改为在你的机器上运行本地 MCP server。请参阅[配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration#connection-modes)。

## 第 3 步：配置你的 AI 智能体

1. 在 **AI agent** 区域，从下拉列表中选择你的客户端，例如 **Claude Code**。
2. 在 **Model Context Protocol (MCP)** 下，点击 **Configure**。插件会写入该客户端的 MCP 配置文件（对于 Claude Code，是项目根目录下的 `.mcp.json`），其中包含固定指向此项目的 URL。
3. 在 **Skills** 下，开启 **Auto-generate** 或点击 **Generate**。这会写入技能文件，智能体通过阅读这些文件来学习如何使用 Unity MCP 和 RQL（对于 Claude Code，写入 `.claude/skills`）。支持技能的智能体在使用这些文件后表现会明显更好。
4. 从项目文件夹启动你的 AI 客户端；如果它已经在运行，请重启它，以便加载新配置。

同样的操作也可以在终端中完成：

```bash
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-skills claude-code ./MyUnityProject
```

`setup-skills` 需要编辑器处于打开且已连接的状态。其他客户端和手动配置方式请参阅[连接 AI 客户端](https://ai-game.dev/zh-hans/docs/wiki/unity/connecting-ai-clients)。

## 第 4 步：检查连接

- 在窗口中，Unity 状态显示为 **Connected**，并且 AI agent 节点显示你的客户端已完成配置。
- 在你的 AI 客户端中，列出 MCP server 或工具。在 Claude Code 中运行 `/mcp`；你应该能看到 `ai-game-developer`，其中包含 `rql-query`、`rql-mutate`、`rql-schema`、`script-execute`、`screenshot-isolated`、`tests-run` 和 `unity-tool-list` 等工具。
- 如果你的客户端在 Unity 就绪之前就已连接，请重新连接，以便它重新列出工具。

在终端中运行 `unity-mcp-cli status ./MyUnityProject`，可以查看 Unity 是否正在运行，以及配置的 server 是否可访问。

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

先从一个读取场景的请求开始，然后再尝试一个修改场景的请求：

```text
Explain my scene hierarchy.
```

```text
Create 3 spheres stacked on top of each other, then save the scene.
```

```text
Create a metallic golden material and assign it to a new sphere.
```

观察 Hierarchy 面板：随着智能体执行操作，对象会陆续出现。在背后，智能体发送的是 RQL，例如下面这样的变更操作：

```text
editor | call CreateGameObject({name: "Ground", primitive: "Plane"})
```

每次 RQL 变更都会被记录为一步 Undo，因此 Ctrl+Z（Cmd+Z）可以像手动编辑一样将其撤销。

下面是一个会用到多个工具的更长示例：

```text
Create a new scene called Playground. Add a plane scaled to 10, 1, 10 and a capsule
named Player at 0, 1, 0 with a Rigidbody. Write a PlayerController script that moves
the Player with WASD, attach it, and take a screenshot of the Player.
```

更多可以尝试的想法：

- “读取 Console 并告诉我是否有任何错误。”
- “运行所有 EditMode 测试并总结失败项。”
- “列出打开场景中每个 Rigidbody 及其质量。”
- “启动 Profiler，录制几秒钟 Play 模式并报告帧时间。”

## 获得更好结果的技巧

- 对名称、位置和文件路径要具体明确。请求越精确，需要纠正的地方就越少。
- 在你的客户端中选择一个强大的模型；工具调用密集的工作会因此受益。
- 在 VS Code 中使用 Copilot 时，将聊天切换为 **Agent** 模式，否则不会调用工具。
- 保持智能体的工具列表精简。隐藏的工具在被按名称调用时仍会运行，而可见工具越少，留给推理的上下文就越多。请参阅[配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration#tools-prompts-resources)。

[Unity 最佳实践](https://ai-game.dev/docs/best-practices/unity)页面提供了更多提示词编写建议。

## 后续步骤

- [工具与 RQL](https://ai-game.dev/zh-hans/docs/wiki/unity/tools-and-rql)：了解智能体能做的一切。
- [扩展](https://ai-game.dev/zh-hans/docs/wiki/unity/extensions)：添加 Animation、Cinemachine、ProBuilder、Tilemap 以及其他扩展包。
- [自定义工具](https://ai-game.dev/zh-hans/docs/wiki/unity/custom-tools)：将你自己的 C# 方法暴露给智能体。
- 遇到问题？请参阅[故障排除](https://ai-game.dev/zh-hans/docs/wiki/unity/troubleshooting)。

---

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

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