> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md).

# 使用 AI 进行 vibe coding

借助 Creator Hub 和官方 Decentraland SDK Skills（npx skills add decentraland/sdk-skills），与 AI 助手一起构建 Decentraland 场景。

通过描述你想要的内容来构建 Decentraland 场景。AI 助手会为你处理 SDK7 代码、ECS 架构和项目结构。

无论你是首次创作还是经验丰富的开发者，AI 辅助的“氛围编程”都能让你在几分钟而不是几小时内，从想法直接变成一个可运行的场景。

{% hint style="info" %}
**💡 提示**：你无需懂 TypeScript 也能开始。AI 助手可以根据自然语言描述生成可运行的场景代码。
{% endhint %}

## 什么是氛围编程？

氛围编程是指通过与 AI 助手对话来构建场景，而不是手动编写每一行代码。你描述你想要的东西——“一个有可点击门和背景音乐的中世纪酒馆”——AI 就会编写正确、可部署的 SDK7 代码。

这种方式适用于任何技能水平：

* **初学者和非开发者** — 无需手动写代码，就能从零开始做出一个可运行的场景。
* **经验丰富的开发者** — 跳过样板代码。让 AI 处理多人同步、UI 脚手架和部署配置，而你专注于创意决策。
* **团队与工作室** — 在投入完整开发资源之前，快速为场景概念做原型。

## 在 Creator Hub 中使用 AI 助手

最快的入门方式是 Creator Hub 内置的 [AI 助手](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/ai-assistant.md)。它能看到你打开的场景，为你编辑实体、组件、智能物品和代码，并且可以运行预览来检查自己的工作。它会自动将下面的技能安装到你的项目中，因此除了登录到编码 CLI 之外，无需进行任何设置。

这是一个实验性功能，默认关闭。

## 把代码编辑器与 AI 结合使用

使用通用的 AI 代码编辑器，例如 [Cursor](https://www.cursor.com/) 或带有 GitHub Copilot 或 Claude AI 的 VS Code。Decentraland 提供了一个上下文文件夹，因此这些工具能够理解 SDK。

1. 打开 Creator Hub，并创建或打开一个场景。
2. 点击 **< > 代码** 按钮以打开你的代码编辑器。
3. 使用编辑器内置的 AI 助手（Cursor 的聊天、Copilot 等）来生成或修改代码。

## 为任何 AI Agent 安装技能

技能是一套现成的指令集，用来教你的 AI Agent 如何与 Decentraland SDK 协作。每个技能都涵盖一个特定主题，例如创建场景、添加 3D 模型或设置多人功能，因此 AI 已经知道正确的模式、API 和约束，而无需你逐一解释。安装技能意味着更少的错误，以及从第一条提示开始就能获得更好的结果。

```bash
# 从交互式选择器中选择要安装的 Decentraland 技能
npx skills add decentraland/sdk-skills

# 或安装全部 Decentraland 技能
npx skills add decentraland/sdk-skills --all

# 或选择特定技能
npx skills add decentraland/sdk-skills --skill create-scene

# 全局安装（在所有项目中可用）
npx skills add decentraland/sdk-skills -g
```

这会把技能文件复制到你 Agent 的配置中，让它了解 Decentraland 的模式和约束。

## 更新技能

新的技能会不断加入，现有技能也会持续改进。要获取最新版本，请使用 `--all`:

```bash
# 更新所有已安装技能并下载任何新技能
npx skills add decentraland/sdk-skills --all
```

再次运行 `add` 会重新获取仓库，从而刷新你已有的技能，并安装自首次安装以来新增的技能。如果你是全局安装的技能，还要在这个命令中加上 `-g` 。

{% hint style="warning" %}
**📔 注意**：不要使用 `npx skills update` 来做这件事。它只会刷新你机器上已有的技能，因此在上次安装之后加入仓库的任何技能都会被静默跳过。始终使用 `npx skills add decentraland/sdk-skills --all` 。
{% endhint %}

## 可用的 AI 技能

当你把技能安装到你的 Agent 中后，以下能力就可用了：

| 技能                     | 作用                                     |
| ---------------------- | -------------------------------------- |
| `sdk-scenes`           | Agent 指南和所有主题技能索引的入口点                  |
| `create-scene`         | 从零开始搭建一个新的 SDK7 场景项目脚手架                |
| `migrate-sdk6-to-sdk7` | 将旧版 SDK6 场景迁移到 SDK7                    |
| `add-3d-models`        | 添加 3D 模型（`.glb`/`.gltf`）并进行定位、缩放、碰撞体设置 |
| `add-interactivity`    | 指针事件、触发器、射线投射                          |
| `build-ui`             | 使用 React-ECS 的 2D 屏幕空间 UI——HUD、菜单、对话框  |
| `animations-tweens`    | 使用 Animator、SDK tween 的 GLTF 模型动画      |
| `multiplayer-sync`     | 使用 CRDT 网络的点对点多人同步                     |
| `authoritative-server` | 用于服务器验证场景的无头多人服务器（BETA）                |
| `audio-video`          | 音效、音乐、音频流和视频播放器                        |
| `audio-analysis`       | 用于音频响应场景的实时振幅和频率数据                     |
| `deploy-scene`         | 将场景部署到 Genesis City（基于 LAND）           |
| `deploy-worlds`        | 将场景部署到 Worlds（个人 3D 空间）                |
| `optimize-scene`       | 性能优化、场景限制、最佳实践                         |
| `camera-control`       | 摄像机模式检测、电影镜头、虚拟摄像机                     |
| `composites`           | 用于静态场景内容的复合文件格式参考                      |
| `lighting-environment` | 动态光照、阴影、天空盒、雾效、环境设置                    |
| `particle-system`      | 粒子效果——火焰、烟雾、火花、雪、烟花                    |
| `npcs`                 | 非玩家角色——NPC Toolkit 库和手动实现方式            |
| `player-avatar`        | 玩家位置、资料、头像自定义、附件                       |
| `player-physics`       | 物理力——冲量、击退、持续作用力                       |
| `nft-blockchain`       | NFT 展示和区块链/加密交互                        |
| `advanced-rendering`   | Billboard、TextShape、PBR 材质、视频材质        |
| `advanced-input`       | 系统级输入轮询和玩家移动控制                         |
| `scene-runtime`        | 跨领域运行时 API——异步工作、HTTP、消息传递             |
| `script-components`    | Creator Hub 的脚本组件类                     |
| `game-design`          | 游戏设计模式、场景限制、性能预算                       |
| `unity-explorer-mcp`   | 驱动正在运行的 Explorer，在世界中测试并验证场景           |

注意：这些技能中的一些会涉及从免费资源目录获取 3D 模型或其他资源。AI Agent 在为场景项目下载任何新资源之前，应始终先获得用户确认。

## 让 AI 在世界中看到你的场景

通常 AI 负责写代码，而 *你* 运行预览、查看结果并反馈哪里有问题。Decentraland 桌面客户端可以把这个流程闭环：它附带一个可选的 **MCP 服务器** ，允许 AI Agent 直接查看并控制正在运行的 Explorer。Agent 会自己截图、读取场景的控制台输出、让玩家四处走动、点击物体，并检查场景是否真的实现了要求的内容——然后修复发现的问题，再重新查看。

这会把氛围编程从“描述、等待、审查”变成一个 Agent 大多可以自行运行的循环。

{% hint style="info" %}
**💡 提示**：安装 `unity-explorer-mcp` 在尝试这个之前先安装技能。它会教会 Agent 整个工作流程——如何启动客户端、如何截取有用的截图、如何把看到的内容与场景实际状态交叉核对，以及在场景停止加载时如何恢复。

```bash
npx skills add decentraland/sdk-skills --skill unity-explorer-mcp
```

{% endhint %}

### 你需要的内容

* 该 **Decentraland 桌面客户端** 已安装（Creator Hub 用于预览启动的 همان那个客户端）。
* 一个能通过 HTTP 连接到 MCP 服务器的 AI Agent——Claude Code、Cursor、Cline、带有 MCP 能力扩展的 VS Code 等。
* 场景中已安装最新 SDK：如果下面的 `npm i @dcl/sdk@latest` 若 `--mcp` 标志被拒绝并提示是未知选项，请运行

### 1. 启用 MCP 服务器启动场景

在你的场景文件夹中：

```bash
npm run start -- --mcp
```

这会执行 `npm run start` 一贯会做的事——把你的场景服务到 `http://127.0.0.1:8000` ，并在你保存文件时自动热重载——另外还会启动桌面客户端，并让 MCP 服务器监听在 `http://127.0.0.1:8123/unity-explorer-mcp`.

在客户端打开时登录。只有在你通过登录界面且世界加载完成后，Agent 才能开始工作。

### 2. 将你的 AI Agent 连接到服务器

在 **Claude Code**，只需注册一次：

```bash
claude mcp add --transport http --scope user explorer http://127.0.0.1:8123/unity-explorer-mcp
```

在 **任何其他 MCP 客户端**，按该客户端文档中的方式添加服务器，使用以下信息：

| 设置  | 值                                            |
| --- | -------------------------------------------- |
| 传输  | 可流式 HTTP（不是 stdio——没有要运行的命令，服务器驻留在正在运行的客户端中） |
| URL | `http://127.0.0.1:8123/unity-explorer-mcp`   |
| 认证  | 无                                            |
| 名称  | `explorer`                                   |

许多客户端会使用 JSON 配置文件来设置这个（`.cursor/mcp.json`, `mcp.json`，以及类似文件——请查看你的客户端文档以获取准确的键名）：

```json
{
  "mcpServers": {
    "explorer": {
      "type": "http",
      "url": "http://127.0.0.1:8123/unity-explorer-mcp"
    }
  }
}
```

注册服务器后，重启或重新加载你的 AI 客户端，以便它获取连接。如果 Agent 说 Explorer 工具不可用，通常原因是 Agent 启动时客户端没有在运行——重新连接服务器（在 Claude Code 中，运行 `/mcp`）并打开 Explorer。

{% hint style="info" %}
**这安全吗？** 服务器仅在你使用 `--mcp`启动客户端时运行，只接受来自你自己机器（`127.0.0.1`）的连接，并拒绝来自网页的请求。没有任何内容暴露到互联网，而且在正常启动客户端时它完全是关闭的。
{% endhint %}

### 3. 告诉它你想要什么，然后让它自行验证

服务器连接后，就像平常一样提出工作请求——区别在于 Agent 现在可以检查自己的结果：

> “在地块中心放一个宝箱，点击后会打开，然后走过去点击它，确认盖子会播放动画。”

> “霓虹招牌看起来太暗了。截一张图，调整自发光强度，然后给我看前后对比。”

> “电梯出了点问题。走到平台上，查看日志，告诉我它为什么不动。”

在幕后，Agent 可以：

* **参见** — 截图、读取场景的 `console.log` 输出和错误，检查场景是否已加载或崩溃，列出场景实体并检查其组件，以及读取玩家和摄像机位置。
* **控制** — 移动和传送玩家，通过真实碰撞沿某个方向行走，调整摄像机，为特定镜头放置自由摄像机，切换摄像机模式，点击场景对象，发送聊天消息和 `/commands`，触发表情动作，并重新加载场景。
* **测量** — 读取场景内容的实时计数（三角形、实体、纹理、材质等）并与 Decentraland 的限制对照，按任意视角排列哪些 3D 模型对该负载贡献最大，并在玩家所在的任何位置采样实际帧率。

### 用它来优化你的场景

因为 Agent 既能测量也能看见，所以你可以直接把性能工作交给它。它可以根据 [场景限制](/creator/content-creator-zh/chang-jing-sdk7/you-hua/scene-limitations.md)检查你的场景，找出最重的 3D 模型，测量特定位置的帧率，最重要的是，在做出修改后再次测量，以证明它们确实有效：

> “检查我的场景是否在 Decentraland 的内容限制内，并告诉我哪个预算最接近上限。”

> “喷泉附近的场景感觉卡顿。站在那里，测一下帧率，并告诉我从那个位置看哪些模型的成本最高。”

> “优化这个场景：找出拖慢帧率的原因，修复它，然后给我看前后测量结果。”

为了获得最佳效果，请安装 `optimize-scene` 技能并配合 `unity-explorer-mcp`一起使用，这样 Agent 也能了解 Decentraland 的优化最佳实践。更多关于这个工作流的信息请参见 [性能优化](/creator/content-creator-zh/chang-jing-sdk7/you-hua/performance-optimization.md#optimize-with-ai) ，包括如何配合 Blender MCP 服务器来自动修复 3D 模型本身。

### 提示

* **请求证据，不要只要结论。** “用截图验证”或“从日志确认”正是让这个工作流发挥价值的关键。优秀的 Agent 会交叉核对两者：画面看起来可能对，但底层状态可能已经坏了，反之亦然。
* **截图会消耗 token。** Agent 查看的每一张截图都会占用一部分上下文。如果你想做长时间的视觉扫描——比如随时间变化的动画、走访多个位置——可以让它把帧保存到文件中，只读取真正重要的那些。 `unity-explorer-mcp` 技能附带了一个正好完成这项工作的脚本。
* **保存一次，不要连续保存五次。** 连续快速保存可能会让客户端加载一个半写入的包并彻底丢失场景，这就需要重启客户端来恢复。让 Agent 把修改批量合并到一次保存中。
* **保持客户端开启。** 如果你关闭它，连接就会断开，Agent 也会失去“眼睛”。用同样的命令重新启动即可恢复。
* **在本地场景开发中，传送的行为有所不同。** 使用 `/goto` 在地块之间移动是被禁止的，因此 Agent 应该在场景内重新定位玩家，而不是传送。

## 有效提示词编写技巧

要从 AI 获得最佳结果，关键在于给出清晰、具体的提示。以下是一些技巧：

### 明确说明你想要什么

不要这样：

> “让我的场景更好”

尝试这样：

> “在位置 (8, 0, 8) 添加一扇门，点击后以旋转动画打开，并播放吱呀声效”

### 引用现有物品

> “让桌子上的红色按钮触发电梯上升”

### 一次只请求一件事

把复杂请求拆成步骤：

1. “在右上角添加一个计分板 UI”
2. “添加一个计数器，玩家点击目标时它会增加”
3. “在计分板上显示计数器的数值”

### 迭代并优化

每次修改之后：

1. 预览场景（点击 **播放** 在 Creator Hub 中，或 `npm run start` 在命令行中）
2. 检查哪些有效，哪些无效
3. 告诉 AI 需要调整什么：“把 NPC 向左移动 2 米，并让它面向玩家”

### 示例提示词

在一个全新的 [sdk7-scene-template](https://github.com/decentraland/sdk7-scene-template/).

#### 提示示例 1

```
我想让你删掉当前场景代码，做一个简单的小迷宫游戏，占用 1 个地块，墙体可以用立方体，并且应该带有碰撞。

游戏应该在玩家真正进入 A 点的迷宫时开始，并在他从 B 点离开时结束（迷宫唯一出口）。

我想让你在迷宫里添加 3 扇不同的门，需要用指向输入交互后才能打开并通过。

你应该验证玩家确实能够游玩并获胜
```

#### 提示示例 2

```
我想让你删掉当前场景代码，构建一个简单的平台跳跃游戏。

在认为完成之前，你必须验证游戏确实可以通关。
```

## AI 能帮助什么

* 根据描述搭建新场景脚手架
* 添加并放置 3D 模型
* 编写点击处理器和交互
* 构建 UI（HUD、菜单、对话框）
* 设置多人同步
* 配置用于反作弊的多人服务器
* 添加音频、视频和流媒体
* 创建动画和 tween
* 优化场景性能
* 为部署准备场景
* 调试现有代码中的问题
* 在正在运行的 Explorer 中测试并以可视方式验证场景（见 [让 AI 在世界中看到你的场景](#let-the-ai-see-your-scene-in-world))

## 限制

虽然 AI 工具很强大，但请记住：

* **始终先预览** — AI 生成的代码可能不会完全符合你的预期。运行预览来验证。
* **场景限制依然适用** — AI 无法绕过 Decentraland 的 [场景限制](/creator/content-creator-zh/chang-jing-sdk7/you-hua/scene-limitations.md) （三角形数量、文件大小、地块边界）。
* **复杂的游戏逻辑** — 对于复杂的游戏机制，你可能需要逐步引导 AI，或手动细化它的输出。
* **自定义 3D 模型** — AI 可以引用已有的免费资源，或加载你提供的模型，但它不能从零创建 3D 模型（除非你同时使用 Blender 官方 MCP 服务器等其他工具）。

## 下一步

* [SDK 快速入门](/creator/content-creator-zh/chang-jing-sdk7/ru-men/sdk-101.md) — 学习 SDK7 基础
* [与代码结合](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/overview.md) — 将可视化编辑与代码结合
* [多人服务器](/creator/content-creator-zh/chang-jing-sdk7/lian-wang/authoritative-servers.md) — 服务器权威型多人游戏
* [场景示例](https://studios.decentraland.org/resources?sdk_version=SDK7) — 浏览示例场景获取灵感
* [实用资源](/creator/content-creator-zh/chang-jing-sdk7/ru-men/useful-resources.md) — 更多 AI 工具、资源库和附加组件，加快你的工作流


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.