> 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/sdk-101.md).
# SDK 快速开始
使用 Creator Hub、SDK 和官方 SDK Skills 通过 AI 辅助 vibe coding 创建你的第一个 Decentraland 场景。
本教程将引导你创建第一个场景，并结合你可用的不同工具：Creator Hub 的可视化 Scene Editor、使用 Decentraland SDK 编写的手写代码，以及 AI 辅助 **氛围编程**。你将把三者结合起来使用，并了解各自最擅长的场景。
## 我该如何创建一个 Decentraland 场景？
1. **安装** [**Creator Hub**](https://decentraland.org/download/creator-hub)，这是用于创建、预览和发布场景的官方桌面应用程序。它是面向所有技能水平创作者的推荐工具。
2. **如果你使用 AI 编程助手** （如 Claude Code、Cursor 或 Copilot），请安装官方 [Decentraland SDK 技能](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) ，这样它就知道经过验证的 SDK7 模式： `npx skills add decentraland/sdk-skills`
3. **该** [**CLI**](/creator/content-creator-zh/chang-jing-sdk7/ru-men/using-the-cli.md) 是面向高级用户和自动化工作流的替代方案。
本教程的其余部分将按步骤带你走完这条推荐路径。
## 安装 Creator Hub
Creator Hub 可让你构建、预览并部署 Decentraland 场景。下载 Creator Hub [这里](https://decentraland.org/download/creator-hub).
要编辑场景代码，你还需要一个代码编辑器。 [Visual Studio Code](https://code.visualstudio.com/) 和 [Cursor](https://www.cursor.com/) 这两者都是很好的选择，但任何代码编辑器都可以。
阅读 [安装指南](/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/editor-installation.md) 了解更多详情。
## 创建你的第一个场景
1. 打开 Creator Hub。
2. 选择 **场景** 选项卡，然后点击 **新建场景**.
3. 选择一个起始模板。本练习中，选择 **空场景**.
这一步可能需要几分钟。它会用基础场景的默认文件集填充你的文件夹。完成后，你会看到场景的空白网格。
## 从资源包中添加项目
浏览 **资源包** 在 Scene Editor 底部区域，并将几个项目拖入你的场景中。现在随便放什么项目都可以。
已经放置的项目可以点击并拖动来重新定位。参见 [场景编辑器基础](/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/scene-editor-essentials.md#position-items) 了解更多详情。
{% hint style="info" %}
**💡 提示**：用一个地面项目覆盖整个场景。类型为 **地面** 的项目上会有一个油漆桶图标。如果你把其中一个拖到场景里，它会用该项目的副本覆盖整个场景地面。
{% endhint %}
## 运行预览
点击 **播放** 按钮，在 Decentraland 中加载你的场景。现在你可以作为一个 Decentraland 头像来探索场景。
在工作时你可以保持预览窗口打开：每次你做出更改时它都会更新。更多内容请阅读 [预览场景](/creator/content-creator-zh/chang-jing-sdk7/ru-men/preview-scene.md).
## 自定义 3D 资产
从以下 *glb* 格式下载这个牛油果的 3D 模型 [链接](https://github.com/decentraland-scenes/avocado/raw/main/avocado-glb.zip) ，然后解压。
将 **avocado.glb** 文件从文件管理器拖到 Scene Editor 底部面板（也就是包含 **资源包** 和 **本地资源** 选项卡的那个面板）上，然后点击 **导入**.
现在你可以在 **avocado.glb** 模型 **本地资源** 选项卡中的 **场景** 文件夹里找到它。把该文件拖到你的场景中，就像从资源包中拖入任何项目一样。
## 编辑场景代码
点击 **<> 代码** 按钮，在你的代码编辑器中打开场景项目。
{% hint style="warning" %}
**📔 注意**：如果没有打开，请确保你已安装像 [Visual Studio Code](https://code.visualstudio.com/) 或 [Cursor](https://www.cursor.com/) 这样的代码编辑器。
{% endhint %}
在代码编辑器左侧边栏中，你可以浏览项目的文件和文件夹结构。打开 `index.ts` 文件，位于 `src` 文件夹中。其内容应如下所示：
```ts
import {} from '@dcl/sdk/math'
import { engine } from '@dcl/sdk/ecs'
export function main() {}
```
Decentraland 场景使用 [TypeScript](https://www.typescriptlang.org/)编写，使用 Decentraland SDK：一个包含所有所需功能的库，可用于放置 3D 内容、添加交互，以及控制场景中发生的事情。
此文件定义了一个名为 `main()`的函数，它是场景的入口点：你放在这里的任何代码都会在场景首次加载时运行。
你已经通过可视化方式把一个牛油果拖入了场景。现在让我们添加第二个，这次通过编写代码。将你的 `index.ts` 文件的全部内容替换为以下内容：
```ts
import { Vector3 } from '@dcl/sdk/math'
import { engine, Transform, GltfContainer } from '@dcl/sdk/ecs'
export function main() {
// 创建一个全新的 Entity
let avocado2 = engine.addEntity()
// 给它一个 Transform
Transform.create(avocado2, {
position: Vector3.create(8, 0, 8),
})
// 给它一个 GLTF
GltfContainer.create(avocado2, {
src: 'assets/scene/avocado.glb',
})
}
```
这些行会创建一个新的 [实体](/creator/content-creator-zh/chang-jing-sdk7/jia-gou/entities-components.md)，给它一个 [形状](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/shape-components.md) ，基于你下载的 3D 模型，并 [设置它的位置](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/entity-positioning.md) 通过 **Transform** 组件。
一般来说，你在 `index.ts` 中编写的代码都应该放在 `main()` （或由 main 间接引用的其他函数中）。参见 [场景生命周期](/creator/content-creator-zh/chang-jing-sdk7/ru-men/coding-scenes.md#scene-lifecycle) 了解更多详情。
运行场景预览：现在你应该能看到两个牛油果，一个是你在 Scene Editor 中添加的，一个是你通过代码添加的。
{% hint style="warning" %}
**📔 注意**：第二个牛油果只存在于 **你的代码中**。它会在你运行场景时显示出来，但 Scene Editor 画布和实体树无法显示在 `index.ts`中创建的实体。如果在编辑器里看不到它，不要惊慌。当你将可视化编辑与代码混合使用时，这是一个需要牢记的关键点。
{% endhint %}
这两个牛油果都是由相同的组件构成的。选择 Scene Editor 中的 **第一个** 牛油果：属性面板会显示一个 **Transform** 以及一个 **GltfContainer** 组件，其中包含与你刚刚在代码中编写的相同类型字段。它们只是同一事物的两种视图。
## 通过脚本添加交互
让我们让一个牛油果对玩家作出反应。我们可以通过把代码加到 `index.ts` 里来实现，不过这次我们改用 **Script 组件**：一种将代码直接附加到 Scene Editor 中某个项目上的方式。它让每个项目的行为保持自包含，而且你甚至可以在多个项目上复用同一个脚本。
1. 在 Scene Editor 中，选择第一个牛油果（你拖入的那个；记住，仅靠代码的牛油果在这里不可见）。
2. 点击 **+** 按钮，在属性面板顶部，然后选择 **Script** 以添加一个 Script 组件。
3. 点击 **+ 创建新脚本** 并将其命名为 `AvocadoScript`.
4. 点击 **<> 代码** 按钮，在 Script 组件上打开代码编辑器中的新文件。
该脚本是一个类，包含三个主要部分（为简洁起见，注释已删减）：
```ts
import { engine, Entity } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
export class AvocadoScript {
constructor(
public src: string, // 请勿删除
public entity: Entity, // 请勿删除
// 在下方添加你的自定义输入
) {}
start() {
// 在场景加载时调用一次
}
update(dt: number) {
// 在每一帧调用
}
}
```
* 该 **constructor** 定义了会显示为 Creator Hub 中 Script 组件可编辑字段的参数。不要删除 `src` 或 `实体`.
* **`start()`** 运行 **一次**，当场景加载时。把它用于初始化：创建组件、注册点击处理器等。
* **`update(dt)`** 运行于 **每一帧** 游戏，大约每秒 30 次。把它用于持续行为，比如移动。 `dt` 告诉你自上一帧以来经过了多少秒。
在类内部， `this.entity` 始终指向持有 Script 组件的实体：在本例中就是你的牛油果。这就是脚本可复用的原因：把同一个脚本附加到十个项目上，每个项目都会对自身生效。
### 用氛围编程创建你的第一个交互
你可以手写以下代码，但现在正是尝试 **氛围编程**的绝佳时机：向 AI 助手描述你想要什么，让它来编写代码。大多数代码编辑器都内置了这类工具，比如 Cursor 的聊天、VS Code 中的 GitHub Copilot，或者 [Claude Code](https://claude.com/product/claude-code)。你也可以在代码编辑器之外写提示词，例如使用 Claude Desktop，或在命令行中使用 Claude Code。
在你的第一个提示词之前，请安装 Decentraland SDK skills，这样 AI 就能了解 SDK 的模式，并减少很多错误：
```bash
npx skills add decentraland/sdk-skills
```
这些 skills 是参考文档，AI 在不确定如何使用 SDK 完成某事时会查阅它们，因此它会写出正确的代码，而不是猜测。有关设置选项和提示技巧，参见 [借助 AI 进行氛围编程](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) 。
现在试试这样的提示词：
> 在 AvocadoScript.ts 中，当玩家点击牛油果时，让它向控制台输出一条消息。
你最终应该得到类似下面的结果（或者自己把它粘贴进去）：
```ts
import { engine, Entity, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
export class AvocadoScript {
constructor(
public src: string,
public entity: Entity,
) {}
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: { button: InputAction.IA_POINTER },
},
() => {
console.log('点击了牛油果')
}
)
}
update(dt: number) {}
}
```
它在 `start()` 函数内部添加了一些点击行为。我们只需要定义一次点击行为，它就会在玩家每次点击该项目时响应。 `pointerEventsSystem.onPointerDown()` 语句定义了三件事：
* 什么 `实体` 点击事件作用于哪个对象：这里是 `this.entity`，也就是持有脚本的牛油果。
* 一个 `opts` 对象：使用哪个按钮，以及我们现在没用到的其他可选参数。
* 一个函数，每当实体被点击时都会运行。
要查看记录的消息，运行预览并点击右上角的  图标打开控制台。你也可以按 **\`** 键切换它。每次你点击牛油果时，都会看到一条新行出现：
{% hint style="warning" %}
**📔 注意**：实体要能被点击，就必须有碰撞体几何。这里使用的模型已经包含了一个。对于不包含碰撞体的模型，请参见 [碰撞体](https://github.com/decentraland/docs/tree/main/creator/sdk7/3d-modeling/colliders.md) 中的解决方法。
{% endhint %}
### 让牛油果消失
现在让我们把点击变得更有趣一些！向你的 AI 助手提问：
> 当牛油果被点击时，让它消失。我希望它以缩小并带弹性的动画消失。另外，我还希望当鼠标指向牛油果时看到的提示文字显示为“Collect”。
你最终应该得到类似这样的结果：
```ts
import { engine, Entity, pointerEventsSystem, InputAction, Tween, EasingFunction } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'
export class AvocadoScript {
constructor(
public src: string,
public entity: Entity,
) {}
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: { button: InputAction.IA_POINTER, hoverText: '收集' },
},
() => {
this.collect()
}
)
}
collect() {
Tween.setScale(
this.entity,
Vector3.One(),
Vector3.Zero(),
500,
EasingFunction.EF_EASEINBOUNCE
)
}
update(dt: number) {}
}
```
让我们来拆解一下 AI 做了什么。
* 为了制作弹跳动画，它使用了一个 **补间**。tween 用来描述实体的位置、旋转或缩放随时间逐渐变化的过程。这里 `Tween.setScale()` 会把牛油果从完整大小（`Vector3.One()`）缩小到无（`Vector3.Zero()`），在 500 毫秒内完成，并使用弹性缓动曲线。有关 tweens 的更多信息，请参见 [移动实体](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/move-entities.md).
* 它没有把 tween 直接写在点击函数里，而是创建了一个单独的 `collect()` 方法。这并非必需（如果你的 AI 把 tween 放在点击函数里，也同样可行），但这是个好习惯：方法能让代码更易读，并让你在不同地方重用相同的逻辑。
* 为了在牛油果上显示“Collect”提示，它将其设置为 `hoverText` 值。
运行预览并点击牛油果：它应该会优雅地消失。
{% hint style="warning" %}
**📔 注意**：牛油果会缩小到 0 大小，但实体仍然存在。理想情况下，你应该在 tween 结束后删除该实体，以让场景更轻量。参见 [在 tween 结束时](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/move-entities.md#on-tween-finished).
{% endhint %}
### 每帧运行代码
到目前为止，我们所有的代码都运行在 `start()`中。让我们使用 `update()` 让牛油果持续旋转。将构造函数和 `update()` 替换为：
```ts
constructor(
public src: string,
public entity: Entity,
public speed: number = 45,
) {}
update(dt: number) {
const transform = Transform.getMutable(this.entity)
transform.rotation = Quaternion.multiply(
transform.rotation,
Quaternion.fromAngleAxis(this.speed * dt, Vector3.Up())
)
}
```
你还需要把 `Transform` 和 `Quaternion` 添加到文件顶部的导入中，像这样：
```ts
import { engine, Entity, pointerEventsSystem, InputAction, Tween, EasingFunction, Transform } from '@dcl/sdk/ecs'
import { Vector3, Quaternion } from '@dcl/sdk/math'
```
{% hint style="info" %}
**💡 提示**：与其手动编辑导入，不如点击代码编辑器标出的错误，让它自动添加。
{% endhint %}
在每一帧，这都会让牛油果再转一点。乘以 `dt` 使运动平滑且与帧率无关：无论玩家机器运行多快，牛油果都以每秒 45 度旋转。
因为 `速度` 作为一个构造函数参数，它也会作为 Creator Hub 中 Script 组件上的一个字段显示出来。点击 Script 组件右上角的刷新图标来查看，然后在不改动任何代码的情况下调整这个值。
每个实体都会为 **速度** 字段保存自己的值，因此几个项目可以共享同一个脚本，但表现不同。试试看：用 Ctrl + C 和 Ctrl + V 复制牛油果，把副本移开以免重叠，并为每个牛油果设置不同的速度。现在每个牛油果都会以自己的速度旋转。
脚本还能做更多事情，比如暴露可供其他智能项目触发的操作。参见 [Script 组件](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/script-component.md) 以了解完整情况。
## 从 Scene Editor 引用项目
Script 组件是给单个项目添加行为的最简单方式，但还有另一种方法：你可以在 `index.ts` 中的代码通过名称使用 `engine.getEntityOrNullByName()`获取你可视化添加的任意项目。当某段逻辑涉及多个项目，或你希望把所有内容集中在一处时，这很方便。使用 [实体树](/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/scene-editor-essentials.md#the-entity-tree).
中显示的名称。 **黄色箱子**。你可以使用任何项目，只需准确输入其在实体树中显示的名称。
{% hint style="info" %}
**💡 提示**：你可以通过右键单击并选择 **重命名** 在实体树上来重命名实体。
{% endhint %}
```ts
export function main() {
// 之前的 avocado2 代码
// (...)
const crate = engine.getEntityOrNullByName('黄色箱子')
if (crate) {
pointerEventsSystem.onPointerDown(
{
entity: crate,
opts: { button: InputAction.IA_POINTER, hoverText: '打开' },
},
function () {
console.log('点击了箱子')
}
)
}
}
```
这里 `engine.getEntityOrNullByName()` 获取对名为 *黄色箱子*。 `if (crate)` 检查可确保该实体确实存在于场景中；如果没有这个名称的实体， `crate` 为 `null`。参见 [参考项](https://github.com/decentraland/docs/tree/main/creator/sdk7/code/reference-items.md) 了解更多信息。
{% hint style="info" %}
**💡 提示**：通过 Scene Editor 添加的所有实体，在 `main()` 运行时都已经加载好了，因此在这里或在由 `main()`.
{% endhint %}
## 更多教程
阅读 [场景编码](/creator/content-creator-zh/chang-jing-sdk7/ru-men/coding-scenes.md) 以获得对 Decentraland 场景如何工作的高层理解。
对于使用 SDK7 构建的示例，请查看 [示例页面](https://studios.decentraland.org/resources?sdk_version=SDK7)，其中包含多个小场景。
请参见 **开发指南** 部分，了解更多关于向场景添加内容的说明。
## 与其他开发者互动
访问 [Decentraland Discord](https://dcl.gg/discord) 和 [Decentraland DAO Discord](https://discord.gg/bxHtcMxUs4) ，加入 Discord 的 **创作者** 部分。
要调试任何问题，请查看 [故障排除](/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/troubleshooting.md) 和 [调试](/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/debug-in-preview.md) 部分。拥有已安装 [SDK skills](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) 的 AI 助手也是一个很好的调试伙伴：把控制台中的错误信息贴给它，或者描述哪里没有按预期工作，它通常就能在你的代码中找到问题。如果你找不到解决方案，可以在 [SDK 支持分类](https://forum.decentraland.org/c/support-sdk/11) 中发帖，发布到 Decentraland 论坛。
## 3D 美术资源
一个优秀的体验应当配有出色的 3D 美术。如果你有兴趣自己创建这些 3D 模型，请查看 [3D 建模部分](/creator/content-creator-zh/3d-jian-mo-yu-dong-hua/3d-models.md)。但如果你更想专注于编码或游戏设计方面，你不需要自己创建资产！请参见 [实用资源](/creator/content-creator-zh/chang-jing-sdk7/ru-men/useful-resources.md) 可用的资产库和 AI 工具，用它们为你的场景获取 3D 模型。
## 发布你的场景
如果你拥有 Decentraland NAME、ETH ENS 名称或 LAND，或者由拥有者授予了权限，你可以将你的场景上传到 Decentraland。参见 [发布](/creator/content-creator-zh/chang-jing-sdk7/fa-bu/publishing.md).
## 其他有用信息
* [借助 AI 进行氛围编程](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md)
* [开发工作流](/creator/content-creator-zh/chang-jing-sdk7/ru-men/dev-workflow.md)
* [编辑场景](/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/about-editor.md)
* [场景编辑器基础](/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/scene-editor-essentials.md)
* [游戏设计约束](/creator/content-creator-zh/chang-jing-sdk7/ti-yan-she-ji/design-games.md)
* [3D 建模](/creator/content-creator-zh/3d-jian-mo-yu-dong-hua/3d-models.md)
* [场景限制](/creator/content-creator-zh/chang-jing-sdk7/you-hua/scene-limitations.md)
---
# 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/sdk-101.md?ask=&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.