> 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 的可视化场景编辑器、使用 Decentraland SDK 手写代码，以及 AI 辅助的 **氛围编程**。你会将三者结合使用，并学习它们各自何时最能发挥作用。
## 我如何创建一个 Decentraland 场景？
1. **安装** [**创作者中心**](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/kai-shi-shi-yong/editor-installation.md) 了解更多详情。
## 创建你的第一个场景
1. 打开 Creator Hub。
2. 选择顶部导航栏上的 **场景** 选项卡，然后点击 **新场景**.
3. 选择一个起始模板。在本练习中，选择 **空场景**.
这一步可能需要几分钟。它会为你的文件夹填充基础场景所需的默认文件集。完成后，你就会看到场景的空白网格。
## 从资源包添加物品
浏览 **资源包** ，在场景编辑器底部区域中，然后将几个物品拖入你的场景。现在任何物品都可以。
已经放置的物品可以点击并拖动来重新定位。参见 [场景编辑器基本要点](/creator/content-creator-zh/chang-jing-bian-ji-qi/kai-shi-shi-yong/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 资产
下载这个牛油果的 3D 模型，格式为 *glb* ，可从以下 [链接](https://github.com/decentraland-scenes/avocado/raw/main/avocado-glb.zip) 下载并解压。
将 **avocado.glb** 文件从文件管理器拖到场景编辑器的底部面板上（也就是包含 **资源包** 和 **本地资源** 选项卡的那个面板），然后点击 **导入**.
现在你可以在 **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() {
// 创建一个新的实体
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) 了解更多详情。
运行场景预览：你现在应该能看到两个牛油果，一个是你在场景编辑器中添加的，另一个是你通过代码添加的。
{% hint style="warning" %}
**📔 注意**：第二个牛油果存在于 **你的代码中**。它会在你运行场景时显示出来，但场景编辑器画布和实体树无法显示在 `index.ts`中创建的实体。如果你在编辑器中看不到它，也不用担心。当你把可视化编辑和代码混合使用时，这一点非常重要。
{% endhint %}
这两个牛油果都是由相同的部件构成的。选择 **第一个** 场景编辑器中的牛油果：属性面板会显示一个 **Transform** 和一个 **GltfContainer** 组件，其中包含你刚刚在代码中编写的那些相同类型的字段。它们只是同一事物的两种视图。
## 使用脚本添加交互
让我们让一个牛油果对玩家作出反应。我们可以把代码加到 `index.ts` 我们刚才正在编辑的文件中，但不如改用 **脚本组件**：一种将代码直接附加到场景编辑器中某个物品上的方式。它能让每个物品的行为保持自包含，你甚至可以在多个物品上重复使用同一个脚本。
1. 在场景编辑器中，选择第一个牛油果（就是你拖进来的那个；记住，仅靠代码添加的牛油果在这里看不到）。
2. 点击 **+** 属性面板顶部的按钮，然后选择 **脚本** 来添加一个 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) {
// 在每一帧调用
}
}
```
* 该 **构造函数** 定义会显示在 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 技能，这样 AI 就能了解 SDK 的模式，减少很多错误：
```bash
npx skills add decentraland/sdk-skills
```
这些技能是参考文档，当 AI 不确定如何使用 SDK 做某事时会查阅它们，因此它能写出正确的代码，而不是瞎猜。参见 [使用 AI 进行 Vibe Coding](/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('CLICKED AVOCADO')
}
)
}
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: 'Collect' },
},
() => {
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 毫秒内完成，并使用弹跳缓动曲线。更多关于 tween 的内容请参见 [移动实体](/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 结束后删除该实体，以保持场景更轻量。参见 [补间完成时](/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 复制牛油果，把副本移开避免两个重叠，并为每个牛油果设置不同的速度。现在每个牛油果都会以自己的速度旋转。
脚本还能做更多事情，比如暴露可供其他智能物品触发的操作。参见 [脚本组件](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/script-component.md) 了解完整内容。
## 从场景编辑器中引用物品
Script 组件是赋予单个物品行为的最简单方式，但还有另一种选择：你在 `index.ts` 中编写的代码可以通过名称使用 `engine.getEntityOrNullByName()`获取你通过可视化添加的任何物品。当一段逻辑涉及多个物品，或者你希望所有内容都集中在一处时，这很方便。请使用显示在 [实体树](/creator/content-creator-zh/chang-jing-bian-ji-qi/kai-shi-shi-yong/scene-editor-essentials.md#the-entity-tree).
在这个示例中，我们使用一个名为 **Yellow Crate**的实体。你可以使用任何物品，只需准确写出它在实体树中显示的名称即可。
{% hint style="info" %}
**💡 提示**：你可以通过右键点击并选择 **重命名** 来重命名实体树中的实体。
{% endhint %}
```ts
export function main() {
// 之前的 avocado2 代码
// (...)
const crate = engine.getEntityOrNullByName('Yellow Crate')
if (crate) {
pointerEventsSystem.onPointerDown(
{
entity: crate,
opts: { button: InputAction.IA_POINTER, hoverText: 'Open' },
},
function () {
console.log('CLICKED CRATE')
}
)
}
}
```
这里 `engine.getEntityOrNullByName()` 获取名为 *Yellow Crate*。 `if (crate)` 检查可确保该实体确实存在于场景中；如果没有这个名称的实体， `crate` 为 `null`。见 [参考项](https://github.com/decentraland/docs/tree/main/creator/sdk7/code/reference-items.md) 。
{% hint style="info" %}
**💡 提示**：通过场景编辑器添加的所有实体在 `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) ，加入 Decentraland Discord 的 **Creators** 部分。
要调试任何问题，请查看 [故障排除](/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 技能](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) 的 AI 助手也是很好的调试伙伴：把控制台中的错误信息粘贴进去，或者描述哪里没有按预期运行，它通常就能找出代码中的问题。如果你找不到解决方案，可以发帖到 [SDK Support 分类](https://forum.decentraland.org/c/support-sdk/11) 在 Decentraland Forum 上。
## 3D 美术资源
一个优秀的体验需要与之匹配的出色 3D 美术。如果你热衷于自己创建这些 3D 模型，请查看 [3D 建模部分](/creator/content-creator-zh/3d-jian-mo-he-dong-hua/3d-models.md)。但如果你更想专注于编程或游戏设计方面，就不需要自己创建资产！参见 [实用资源](/creator/content-creator-zh/chang-jing-sdk7/ru-men/useful-resources.md) 了解可用于为你的场景寻找 3D 模型的资产库和 AI 工具。
## 发布你的场景
如果你拥有 Decentraland NAME、ETH ENS 名称或 LAND，或者获得了拥有这些权限的人的授权，你就可以将你的场景上传到 Decentraland。参见 [发布](/creator/content-creator-zh/chang-jing-sdk7/fa-bu/publishing.md).
## 其他有用信息
* [使用 AI 进行 Vibe Coding](/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/kai-shi-shi-yong/about-editor.md)
* [场景编辑器基本要点](/creator/content-creator-zh/chang-jing-bian-ji-qi/kai-shi-shi-yong/scene-editor-essentials.md)
* [游戏设计约束](/creator/content-creator-zh/chang-jing-sdk7/she-ji-ti-yan/design-games.md)
* [3D 建模](/creator/content-creator-zh/3d-jian-mo-he-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 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/sdk-101.md?ask=&goal=
```
`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.