sdk-scenes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Decentraland SDK7 Scene Development

Decentraland SDK7 场景开发

Runtime constraint: Decentraland runs in a QuickJS sandbox. No Node.js APIs (
fs
,
http
,
path
,
process
). Use
executeTask()
+
fetch()
for async work.

运行时约束： Decentraland 运行在 QuickJS sandbox 中。不可使用 Node.js APIs（
fs
、
http
、
path
、
process
）。异步工作请使用
executeTask()
+
fetch()
。

Agent Behavioral Guidelines

Agent 行为准则

Before taking any significant action, check whether it falls into one of the three categories below and confirm with the user first.

How to ask: Phrase the question in plain, non-technical language that describes what will happen to the scene, not the underlying command.

Good: "Should I download this tree model into your scene assets?" Bad: "Run
curl https://… -o assets/Models/tree.glb
?"

在执行任何重要操作之前，先检查其是否属于以下三类之一，并先向用户确认。

询问方式： 使用通俗、非技术化的语言描述_将会对场景执行什么操作_，而不是底层命令。

好：“是否需要把这个树木模型下载到你的场景资源中？” 差：“运行
curl https://… -o assets/Models/tree.glb
？”

1. Changing parcel count or layout

1. 更改 parcel 数量或布局

Any modification to

scene.parcels

in scene.json changes the scene's coordinate space. Entities near the current boundary may end up outside (invisible) or inside the wrong parcel. The user may also have a deployment slot in mind and parcel count needs to match it. Describe the change and its effect before acting:

"To fit the scene you described, I'd need to expand from 1 parcel (16×16 m) to a 2×1 layout (32×16 m). This changes the coordinate bounds for every entity. Should I go ahead?"

对 scene.json 中

scene.parcels

的任何修改都会改变场景的坐标空间。当前边界附近的实体可能会被移到外部（不可见），或者落入错误的 parcel。用户可能还预留了部署槽位，因此 parcel 数量需要与其匹配。执行前应说明更改及其影响：

“为了适配你描述的场景，我需要将其从 1 个 parcel（16×16 m）扩展为 2×1 布局（32×16 m）。这会改变所有实体的坐标边界。是否继续？”

2. Fetching assets from external sources

2. 从外部来源获取资源

Downloading any file not already in the project — 3D models (.glb), images, audio, video. The user may have their own assets in mind, may not want new files added, or may be targeting a specific visual style. Confirm before downloading:

"I'd like to download a [description] model from [source] and add it to your scene. Should I go ahead?"

For streaming references (

AudioStream

VideoPlayer

): these don't download files but do add an external URL dependency. Confirm if the URL wasn't provided by the user:

"I'd set up a video stream from [source]. Is that the one you want to use?"

下载项目中尚不存在的任何文件，包括 3D 模型（.glb）、图像、音频和视频。用户可能已有自己的资源、不希望添加新文件，或者正在追求特定的视觉风格。下载前必须确认：

“我想从 [来源] 下载一个 [描述] 模型，并将其添加到你的场景中。是否继续？”

对于流式引用（

AudioStream

、

VideoPlayer

）：这些操作不会下载文件，但会引入对外部 URL 的依赖。如果 URL 不是由用户提供的，应先确认：

“我想使用来自 [来源] 的视频流进行设置。是否就是你希望使用的内容？”

3. Adding a Multiplayer Server

3. 添加 Multiplayer Server

Introduces

isServer()

registerMessages()

Storage

EnvVar

, or switches to

@dcl/sdk@auth-server

. This feature requires switching to an alternative SDK branch (

@dcl/sdk@auth-server

). Many users who want "multiplayer" only need the simpler

multiplayer-sync

skill (no server). Confirm before implementing:

"To handle multiplayer this way I'd need to add the Multiplayer Server — that requires switching to the
@dcl/sdk@auth-server
SDK branch instead of the standard one. Is that what you're after, or would simpler peer-to-peer sync work for your use case?"

这会引入

isServer()

、

registerMessages()

、

Storage

、

EnvVar

，或者切换到

@dcl/sdk@auth-server

。此功能需要切换到备用的 SDK 分支（

@dcl/sdk@auth-server

）。许多需要“多人游戏”的用户实际上只需要更简单的

multiplayer-sync

Skill（无需服务器）。实现前必须确认：

“如果采用这种方式处理多人游戏，我需要添加 Multiplayer Server——这要求从标准分支切换到
@dcl/sdk@auth-server
SDK 分支。你需要的是这种方案，还是更简单的点对点同步更适合你的使用场景？”

General principle

通用原则

These aren't things the agent should refuse to do — they're things it should communicate about before doing them. If the user confirms, proceed confidently. The goal is transparency, not gatekeeping.

这些并不是 Agent 应该拒绝执行的事情，而是应该在执行前与用户沟通的事情。如果用户确认，就应自信地继续执行。目标是保持透明，而不是设置审批门槛。

CRITICAL RULE — Composite-first scene authoring

关键规则——Composite 优先的场景创作

All static entities (models, lights, spawn points) MUST be defined in

assets/scene/main.composite

, NOT created in TypeScript via

engine.addEntity()

TypeScript (

src/index.ts

) is ONLY for:

Dynamic behavior (systems, event handlers, state changes)

Referencing composite entities via

getEntityOrNullByName('name')

getEntitiesByTag('tag')

Entities that are truly runtime-only (spawned/despawned during gameplay)

所有静态实体（模型、灯光、生成点）都必须在

assets/scene/main.composite

中定义，不得通过 TypeScript 中的

engine.addEntity()

创建。

TypeScript（

src/index.ts

）仅用于：

动态行为（系统、事件处理器、状态变更）

通过

getEntityOrNullByName('name')

或

getEntitiesByTag('tag')

引用 Composite 实体

真正的纯运行时实体（游戏过程中生成或移除的实体）

CRITICAL RULE — Editing an existing composite

关键规则——编辑现有 Composite

Before modifying

assets/scene/main.composite

, scan it for

inspector::Nodes

. If present, the user has opened the scene in the Creator Hub at least once and the file is in edit mode: every new entity you add MUST be registered in

inspector::Nodes

, or it will render in-world but be invisible and un-selectable in the Creator Hub entity tree. See the "Editing an existing composite (edit mode)" section of

{baseDir}/../composites/composite-reference.md

for the exact procedure.

The scene must NOT be open in the Creator Hub while you edit the composite. The inspector autosaves by default and regenerates the whole

main.composite

from its in-memory engine, overwriting the file wholesale — it never re-reads it from disk. Your edits will silently vanish. Ask the user to close the scene first, then reopen it when you are done.

修改

assets/scene/main.composite

之前，先扫描其中是否存在

inspector::Nodes

。如果存在，说明用户至少曾在 Creator Hub 中打开过该场景，并且该文件处于编辑模式：添加的每个新实体都必须注册到

inspector::Nodes

中，否则它虽然能在场景世界中渲染，但在 Creator Hub 的实体树中会不可见且无法选择。准确操作步骤请参阅

{baseDir}/../composites/composite-reference.md

中的“编辑现有 Composite（编辑模式）”章节。

编辑 Composite 时，场景不得在 Creator Hub 中处于打开状态。 Inspector 默认启用自动保存，并会根据内存中的引擎重新生成整个

main.composite

，从而完整覆盖该文件；它绝不会从磁盘重新读取文件。你的修改会悄无声息地丢失。请先让用户关闭场景，完成后再重新打开。

Individual Skills

各项 Skill

This skill is the entry point. The detailed implementation guidance lives in individual topic skills, each installable separately. Install specific ones or use

--skill '*'

for all.

此 Skill 是入口入口。详细的实现指南位于各个主题 Skill 中，每个 Skill 都可以单独安装。可以安装特定 Skill，也可以使用

--skill '*'

安装全部 Skill。

Scene Setup & Configuration

场景搭建与配置

Skill:
create-scene
— Scaffolding,

scene.json

schema, multi-parcel layouts, composite vs TypeScript entity rules.

Skill：
create-scene
——项目脚手架、

scene.json

schema、多 parcel 布局，以及 Composite 与 TypeScript 实体规则。

3D Models

3D 模型

Skill:
add-3d-models
— Loading

.glb

.gltf

with

GltfContainer

, positioning, colliders, and browsing the free asset catalogs (8,800+ models).

Skill：
add-3d-models
——使用

GltfContainer

加载

.glb

.gltf

，设置位置、碰撞体，以及浏览免费资源目录（8,800+ 个模型）。

Animations & Tweens

动画与补间

Skill:
animations-tweens
— GLTF animation clips with

Animator

, programmatic

Tween

and

TweenSequence

, easing functions.

Skill：
animations-tweens
——通过

Animator

播放 GLTF 动画片段、使用程序化

Tween

和

TweenSequence

，以及应用缓动函数。

Materials & Rendering

材质与渲染

Skill:
advanced-rendering
— PBR materials,

TextShape

Billboard

VisibilityComponent

, texture modes.

Skill：
advanced-rendering
——PBR 材质、

TextShape

、

Billboard

、

VisibilityComponent

和纹理模式。

Lighting & Environment

光照与环境

Skill:
lighting-environment
— Point/spot lights, shadows,

SkyboxTime

(day/night cycle), emissive materials.

Skill：
lighting-environment
——点光源、聚光灯、阴影、

SkyboxTime

（昼夜循环）和自发光材质。

Particle Systems

粒子系统

Skill:
particle-system
—

ParticleSystem

component for fire, smoke, sparks, snow, rain, magic, fireworks. Emitter shapes (Point/Sphere/Cone/Box), continuous rate vs Burst emission, gravity, sprite-sheet animation, blend modes.

Skill：
particle-system
——用于火焰、烟雾、火花、雪、雨、魔法和烟花效果的

ParticleSystem

组件。发射器形状（Point/Sphere/Cone/Box）、连续速率与 Burst 发射、重力、精灵图动画和混合模式。

Click & Proximity Interactivity

点击与接近交互

Skill:
add-interactivity
—

pointerEventsSystem

, trigger areas, raycasting. For polling-based input see

advanced-input

Skill：
add-interactivity
——

pointerEventsSystem

、触发区域和射线检测。如需基于轮询的输入，请参阅

advanced-input

。

Advanced Input & Movement Control

高级输入与移动控制

Skill:
advanced-input
—

inputSystem

polling, WASD-controlled entities,

InputModifier

PointerLock

PrimaryPointerInfo

Skill：
advanced-input
——

inputSystem

轮询、WASD 控制的实体、

InputModifier

、

PointerLock

和

PrimaryPointerInfo

。

Player & Avatar

玩家与 Avatar

Skill:
player-avatar
— Player position/profile, emotes, wearables,

AvatarAttach

AvatarModifierArea

Skill：
player-avatar
——玩家位置与资料、表情动作、可穿戴设备、

AvatarAttach

和

AvatarModifierArea

。

NPCs

NPC

Skill:
npcs
—

AvatarShape

NPCs and the NPC Toolkit library for GLB-based NPCs with dialogue and state machines.

Skill：
npcs
——

AvatarShape

NPC，以及用于创建带对话和状态机的 GLB NPC 的 NPC Toolkit 库。

Player Physics

玩家物理

Skill:
player-physics
— Impulse forces, knockback, repulsion fields.

Skill：
player-physics
——冲量、击退和排斥力场。

Camera

摄像机

Skill:
camera-control
— Camera state,

CameraModeArea

VirtualCamera

for cinematic shots.

Skill：
camera-control
——摄像机状态、

CameraModeArea

，以及用于电影化镜头的

VirtualCamera

。

Screen-Space UI

屏幕空间 UI

Skill:
build-ui
— React ECS components for 2D screen-space UI overlays: layout, text, images, buttons, inputs.

Skill：
build-ui
——使用 React ECS 组件构建 2D 屏幕空间 UI 叠加层，包括布局、文本、图像、按钮和输入框。

Audio & Video

音频与视频

Skill:
audio-video
—

AudioSource

AudioStream

VideoPlayer

, media permissions.

Skill：
audio-video
——

AudioSource

、

AudioStream

、

VideoPlayer

和媒体权限。

Audio Analysis (Reactive Visualizers)

音频分析（响应式可视化器）

Skill:
audio-analysis
—

AudioAnalysis

component for real-time amplitude + 8-band frequency data from any

AudioSource

AudioStream

VideoPlayer

. Drive scale, color, lights, and particles from music. Unity-explorer only.

Skill：
audio-analysis
——使用

AudioAnalysis

组件从任意

AudioSource

AudioStream

VideoPlayer

获取实时振幅和 8 波段频率数据。根据音乐驱动缩放、颜色、灯光和粒子。仅适用于 Unity-explorer。

Blockchain & NFTs

区块链与 NFT

Skill:
nft-blockchain
—

NftShape

, wallet checks, token gating, signed requests, smart contracts.

Skill：
nft-blockchain
——

NftShape

、钱包检查、token 门控、签名请求和智能合约。

Multiplayer (CRDT, no server)

多人游戏（CRDT，无服务器）

Skill:
multiplayer-sync
—

syncEntity

for peer-to-peer sync,

MessageBus

, parent-child sync.

Skill：
multiplayer-sync
——使用

syncEntity

实现点对点同步、

MessageBus

和父子实体同步。

Multiplayer Server

Skill:
authoritative-server
— Headless server,

isServer()

registerMessages()

Storage

EnvVar

. Requires

@dcl/sdk@auth-server

Skill：
authoritative-server
——无头服务器、

isServer()

、

registerMessages()

、

Storage

和

EnvVar

。需要使用

@dcl/sdk@auth-server

。

Script Components (Creator Hub)

脚本组件（Creator Hub）

Skill:
script-components
— Writing

.ts

script files for the Creator Hub Script component, constructor parameters,

@action

JSDoc tags (never decorator syntax).

Skill：
script-components
——为 Creator Hub Script 组件编写

.ts

脚本文件、配置构造函数参数，以及使用

@action

JSDoc 标签（绝不使用 decorator 语法）。

Async, HTTP, WebSocket, Timers

异步、HTTP、WebSocket 与定时器

Skill:
scene-runtime
—

executeTask

fetch

signedFetch

, WebSocket, timers, realm/scene info, restricted actions.

Skill：
scene-runtime
——

executeTask

、

fetch

、

signedFetch

、WebSocket、定时器、realm/scene 信息和受限操作。

Scene Optimization

场景优化

Skill:
optimize-scene
— Scene limits, object pooling, LOD, texture optimization, system throttling.

Skill：
optimize-scene
——场景限制、对象池、LOD、纹理优化和系统节流。

Game Design

游戏设计

Skill:
game-design
— DCL design philosophy, state management, UX guidelines, game loop archetypes, MVP planning.

Skill：
game-design
——DCL 设计理念、状态管理、UX 指南、游戏循环原型和 MVP 规划。

Deployment

部署

Skill:
deploy-scene
— Genesis City deployment,
```
dcl deploy
```
, troubleshooting.
Skill:
deploy-worlds
— Personal Worlds,
```
worldConfiguration
```
, ENS/DCL NAME requirements.

Skill：
deploy-scene
——Genesis City 部署、
```
dcl deploy
```
和故障排查。
Skill：
deploy-worlds
——Personal Worlds、
```
worldConfiguration
```
，以及 ENS/DCL NAME 要求。

SDK6 → SDK7 Migration

SDK6 → SDK7 迁移

Skill:
migrate-sdk6-to-sdk7
— Port legacy

decentraland-ecs

scenes to SDK7. Conceptual ECS shift (entities as IDs, data-only components, mutable/immutable access), full API mapping (

new Entity()

→

engine.addEntity()

GLTFShape

→

GltfContainer

OnPointerDown

→

pointerEventsSystem

ISystem

classes → free functions,

Input.instance

→

inputSystem

, etc.), and an annotated before/after example.

Skill：
migrate-sdk6-to-sdk7
——将旧版

decentraland-ecs

场景移植到 SDK7。涵盖 ECS 理念变化（实体即 ID、仅数据组件、可变/不可变访问）、完整 API 映射（

new Entity()

→

engine.addEntity()

、

GLTFShape

→

GltfContainer

、

OnPointerDown

→

pointerEventsSystem

、

ISystem

类 → 自由函数、

Input.instance

→

inputSystem

等），以及带注释的前后对比示例。

Shared References

共享参考

These reference files are used across multiple skills. Load them when you need detailed component APIs, validation rules, or asset catalogs.

以下参考文件供多个 Skill 共同使用。需要详细组件 API、验证规则或资源目录时再加载它们。

Components Reference

组件参考

Reference:
{baseDir}/references/components-reference.md
Quick-reference of key fields, types, and defaults for the SDK7 components you'll commonly use. For a component's complete field list, consult its dedicated skill or the SDK typings.

参考：
{baseDir}/references/components-reference.md

快速参考常用 SDK7 组件的关键字段、类型和默认值。如需查看某个组件的完整字段列表，请查阅其专用 Skill 或 SDK 类型定义。

Entity Validation Rules

实体验证规则

Reference:
{baseDir}/../create-scene/references/entity-validation-rules.md
Rules for validating entity component combinations — which components require each other, mutual exclusions, and common misconfigurations. Apply to both composite and TypeScript entities.

参考：
{baseDir}/../create-scene/references/entity-validation-rules.md

用于验证实体组件组合的规则，包括哪些组件需要相互依赖、互斥关系和常见错误配置。规则同时适用于 Composite 实体和 TypeScript 实体。

Free Asset Catalogs

免费资源目录

3D Models (8,800+ models):
```
{baseDir}/../add-3d-models/references/model-catalog.md
```
— optimized 3D models with descriptions, dimensions, animations, and download URLs
Audio (50 sounds):
```
{baseDir}/../audio-video/references/audio-catalog.md
```
— Music, Ambient, SFX, Game Mechanics, UI sounds

3D 模型（8,800+ 个模型）：
```
{baseDir}/../add-3d-models/references/model-catalog.md
```
——包含说明、尺寸、动画和下载 URL 的优化 3D 模型
音频（50 个音效）：
```
{baseDir}/../audio-video/references/audio-catalog.md
```
——音乐、环境音、SFX、游戏机制和 UI 声音

Composites

Composite

Reference:
{baseDir}/../composites/composite-reference.md
The

.composite

JSON format for declaring initial scene entities. Includes

getEntityOrNullByName

and

getEntitiesByTag

patterns for fetching composite entities in TypeScript.

参考：
{baseDir}/../composites/composite-reference.md

用于声明初始场景实体的

.composite

JSON 格式。包含在 TypeScript 中通过

getEntityOrNullByName

和

getEntitiesByTag

获取 Composite 实体的模式。

Library References

库参考

NPC Toolkit:
```
{baseDir}/../npcs/references/npc-library.mdc
```
— GLB-based NPCs with dialogue, movement, state machines
Blockchain/NFT patterns:
```
{baseDir}/../nft-blockchain/references/blockchain-patterns.md
```
— NFT display, wallet checks, MANA operations, currency/NFT transactions, marketplace integration (dcl-crypto-toolkit)

NPC Toolkit：
```
{baseDir}/../npcs/references/npc-library.mdc
```
——带对话、移动和状态机的 GLB NPC
区块链/NFT 模式：
```
{baseDir}/../nft-blockchain/references/blockchain-patterns.md
```
——NFT 展示、钱包检查、MANA 操作、货币/NFT 交易和市场集成（dcl-crypto-toolkit）

How to use

使用方法

Identify the topic from the user's request
Load the corresponding skill — it contains the full API, code patterns, and rules
For broad requests spanning multiple topics, load each relevant skill
For asset discovery, load the relevant catalog and suggest specific assets before fetching any

根据用户请求确定主题
加载对应 Skill——其中包含完整的 API、代码模式和规则
对于跨多个主题的广泛请求，加载每个相关 Skill
进行资源发现时，先加载相关目录，并在获取任何资源前推荐具体资源