> 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 的“vibe coding”都能让你在几分钟内而不是几小时内，从一个想法做到一个可运行的场景。

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

## 什么是 Vibe Coding？

Vibe coding 指的是通过与 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 补间制作 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 会自己截屏、读取场景的控制台输出、操控玩家四处移动、点击对象，并检查场景是否真的完成了它被要求构建的内容——然后修复发现的问题并再次查看。

这把 vibe coding 从“描述、等待、审查”变成了一个代理几乎可以自行运行的循环。

{% 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、菜单、对话框）
* 设置多人同步
* 配置用于反作弊的多人服务器
* 添加音频、视频和流媒体
* 创建动画和补间
* 优化场景性能
* 为部署准备场景
* 调试现有代码中的问题
* 在运行中的 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/wang-luo/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.