sdk-scenes

Decentraland SDK7 场景开发

**运行时限制：**Decentraland 运行在 QuickJS 沙盒中。不支持 Node.js API（fs、http、path、process）。异步工作请使用 executeTask() + fetch()。

Agent 行为准则

采取任何重要行动前，请先确认是否属于以下类别之一；如果是，请先征求用户同意。

**提问方式：**用通俗、非技术性的语言描述_场景将发生什么变化_，而不是描述底层命令。

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

1. 更改地块数量或布局

对 scene.json 中 scene.parcels 的任何修改都会改变场景的坐标空间。靠近当前边界的实体可能会落到边界之外（不可见），或进入错误的地块。用户可能也有意部署到特定地块，因此地块数量需要与之匹配。采取行动前，请说明更改及其影响：

“要满足你描述的场景需求，我需要将布局从 1 个地块（16×16 m）扩展为 2×1 的布局（32×16 m）。这会改变每个实体的坐标边界。要我继续吗？”

原则是先询问，而不是避免更改。如果设计所需空间超出当前地块可提供的范围，就向用户提出问题。不要擅自增加地块，也不要为了跳过询问而缩小设计。（2026-10：某个 Agent 没有询问，而是在一个地块里垂直堆叠了三个密室；地块所有者问：“你怎么没想到需要分配更多地块？？”）

2. 从外部来源获取资源

下载任何项目中尚不存在的文件——3D 模型（.glb）、图片、音频、视频。用户可能有自己的资源，也可能不希望添加新文件，或者有特定的视觉风格要求。下载前请先确认：

“我想从 [source] 下载一个[description]模型并添加到你的场景中。要我继续吗？”

对于流式传输引用（AudioStream、VideoPlayer）：这不会下载文件，但会添加外部 URL 依赖。如果 URL 不是用户提供的，请先确认：

“我想设置一个来自 [source] 的视频流。这是你想使用的来源吗？”

3. 添加多人游戏服务端

这会引入 isServer()、registerMessages()、Storage、EnvVar，或切换到 @dcl/sdk@auth-server。此功能需要切换到替代 SDK 分支（@dcl/sdk@auth-server）。许多想要“多人游戏”的用户只需要更简单的 multiplayer-sync 技能（无需服务端）。实现前请先确认：

“要用这种方式处理多人游戏，我需要添加多人游戏服务端——这需要从标准 SDK 分支切换到 @dcl/sdk@auth-server SDK 分支。这符合你的需求吗？还是说更简单的点对点同步就能满足你的使用场景？”

4. 从 Blender MCP 改用无头 Blender

如果会话中存在 mcp__blender__* 工具，但未连接（Blender 未运行或插件已禁用），绝不要静默改用无头 Blender CLI——请先询问：

“Blender MCP 已配置，但 Blender 目前没有运行。要打开 Blender，让我在其中实时操作吗？这样你可以看到模型逐步构建，并同步进行编辑；还是要我改用无头模式？”

MCP 能让模型制作过程具备协作性；静默切换会剥夺用户的选择权。如果根本没有安装 MCP，不要要求用户安装——直接使用无头模式，并在报告中提及 MCP 作为一个选项。完整规则见 add-3d-models。

5. 由于场景已在 Creator Hub 中打开，因此在代码中构建静态几何体

当需要在场景中添加墙壁、地板、家具或道具时，如果当前会话中没有 Creator Hub MCP（没有 mcp__creator-hub__* 工具），且场景已在或可能已在 Creator Hub 中打开，请停下来让用户选择——绝不能擅自退而使用 src/ 中的 engine.addEntity()。表明场景已打开或由 Hub 管理的迹象：

• pgrep -fl 'sdk-commands start' 列出 sdk-commands start … --data-layer，且场景文件夹出现在其路径中——这是强烈信号。场景文件夹中运行着 tsc … --watch 只能作为提示（普通预览也会运行它）。
• .editor/project.json 存在，或 assets/scene/main.composite 包含 inspector::* 组件——Hub 至少曾打开过该场景。

询问：

“你的场景已在 Creator Hub 中打开，因此我无法安全地将房间添加到场景文件中——编辑器会覆盖我的更改。我们有三种选择：（1）在 Creator Hub 中关闭场景，我会将所有内容添加到场景文件中；（2）启用 Settings > AI > Expose AI assistant MCP server 并连接我，这样我就能在编辑器中实时放置所有内容；或者（3）我用代码构建房间——它会显示在预览中，但不会显示在编辑器里，所以你无法在那里选择或移动任何内容。你更倾向哪种方式？”

只有用户明确选择后，才可以采用选项 3。未经用户决定，绝不能在 src/ 中构建静态实体——无论是灰盒、原型还是“临时”替代物都不行；也不能因为会话无法交互或处于自主模式就这么做（请在最终消息中提出这个问题）。先完成所有不依赖答案的工作（脚本、行为、资源文件），然后停下来提问。（2026-10-23：某个 Agent 拒绝手动编辑一个已打开场景的 composite，随后却用代码构建了整个房间、一把椅子和约 60 件道具，并且只在总结中提及此事；创作者说：“未经警告绝对不要这样做……由用户决定怎么做。”）这是规范说明；composites 和 creator-hub-mcp 均指向此处。

6. 规避 SDK 缺陷前先报告

当 SDK、Explorer 或 Creator Hub 的行为与文档不符，或缺少场景所需的功能，而你准备绕过该问题时，请先使用 report-sdk-issue 技能进行报告。某个场景中第一次出现这种情况时，先询问用户是否可以发送 SDK 问题报告。之后，根据用户的回答，要么直接报告，不再询问；要么永远不报告。发送报告时，用一行告知用户。报告不会阻碍工作。

在将问题称为平台限制前，请按以下顺序检查：所属主题技能、node_modules/@dcl/ecs 下已安装的类型声明、最小复现、正在运行的客户端和 SDK 版本，以及 Explorer 和 SDK 更新日志中与当前运行版本相匹配的已知修复——较旧的源码检出版本不能说明眼前客户端的情况（某次会话根据 8 月的检出版本排除了音量渐变功能，但该修复当时早已发布）。在设计架构级规避方案前，先区分场景错误、引擎缺陷和不受支持的功能。想不起某个 API 并不代表该 API 不存在（advanced-rendering 中的 GltfNodeModifiers 可以在运行时更改 GLB 材质；数字键操作是 advanced-input 中的 IA_ACTION_3–IA_ACTION_6——请读取枚举，绝不要臆测成员）。

7. 在没有运行时视图的情况下

如果未连接 explorer MCP 服务（出现 ConnectionRefused，或没有 explorer_* / mcp__explorer__* 工具），说明一次情况，并提出按照 unity-explorer-mcp 进行设置；连接被拒绝只表示 Explorer 未在运行。在此之前，每条视觉效果相关的描述都必须标明未经验证（“现在应该能贴合边框了——尚未查看”），绝不能仅凭代码就报告视觉问题已修复。两个会话在同一个场景中（2026-10）都因此把所有视觉缺陷原样交付给了用户。

当 Explorer MCP 已连接时，报告任何改动已完成之前，都必须在场景中验证。不要等用户提出要求。“尚未在场景中验证”并非已完成状态，尤其是在你本可以验证的情况下。如果之前设置过 MCP，但 Explorer 当前未运行，请按照 unity-explorer-mcp 的关卡要求，提出启动它。不要在用户未要求时启动。

一般原则

这些都不是 Agent 应拒绝执行的事项，而是执行前应与用户沟通的事项。如果用户确认，就放心继续。目标是保持透明，而不是设置障碍。

---

关键规则——优先使用复合体创作场景

所有静态实体（模型、基本形状的墙壁和地板、灯光、生成点）都必须定义在 assets/scene/main.composite 中，不能通过 engine.addEntity() 在 TypeScript 中创建。在 Creator Hub 中打开的场景里，应通过 MCP（creator-hub-mcp）将这些实体放入场景；在 src/ 中构建的房间会在预览中渲染，但在编辑器中不可见。如果场景已打开但 MCP 不可用，请停止并询问用户（关闭场景／连接 MCP／明确接受以代码构建实体）；绝不能自行在 src/ 中构建静态实体（Agent Behavioral Guidelines，第 5 项）。

TypeScript（src/index.ts）仅用于：

• 动态行为（系统、事件处理程序、状态变更）
• 通过 getEntityOrNullByName('name') 或 getEntitiesByTag('tag') 引用复合体实体
• 真正仅在运行时存在的实体（在游戏过程中生成／销毁）

关键规则——编辑现有复合体

如果 Creator Hub MCP 可用，就必须使用它——绝不能手动编辑文件。 Creator Hub 内置了 MCP 服务（技能：creator-hub-mcp），其工具（scene_state、create_entity、set_component、remove_entity、place_smart_item、attach_script、set_scene_settings，……）可以实时编辑打开的场景，并自动保存、支持撤销，还会替你处理编辑器的记录管理。该服务已预先接入 Creator Hub 自带的 AI 助手；任何其他支持 MCP 的工具（Claude Code、Cursor、Codex、Claude Desktop）也可以通过 Settings > AI > Expose AI assistant MCP server 连接。scene.json 的改动也应使用它（set_scene_settings）。在 Creator Hub 打开场景时编辑文件会悄无声息地丢失你的修改：检查器默认会自动保存，并根据其内存中的引擎重新生成整个 main.composite，从而覆盖整个文件——它绝不会从磁盘重新读取文件。

只有在 MCP 不可用时（没有使用 Creator Hub，或用户拒绝连接 MCP），才可以改为直接编辑 assets/scene/main.composite；此时：

• 编辑文件时，场景不得在 Creator Hub 中打开。 请先让用户关闭场景，完成后再重新打开。在用户回复之前，不得写入任何静态内容——既不能写入文件，也不能将 src/ 用作替代方案（Agent Behavioral Guidelines，第 5 项）。
• 扫描文件，查找 inspector::Nodes。如果存在，说明用户至少曾在 Creator Hub 中打开过该场景，且文件处于编辑模式：你添加的每个新实体都必须在 inspector::Nodes 中注册，否则它会在场景中渲染，却在 Creator Hub 的实体树中不可见且无法选中。具体操作请参阅 {baseDir}/../composites/composite-reference.md 中的“编辑现有复合体（编辑模式）”一节。

单项技能

此技能是入口。详细的实现指南位于各个主题技能中，每项都可单独安装。安装特定技能，或使用 --skill '*' 安装全部技能。

场景搭建与配置

技能：create-scene — 脚手架、scene.json 架构、多地块布局、复合实体与 TypeScript 实体规则。

3D 模型

技能：add-3d-models — 使用 GltfContainer 加载 .glb/.gltf、定位、碰撞体，以及浏览免费资源目录（8,800 多个 OpenDCL 模型，以及 Creator Hub 资源包）。还涵盖通过驱动 Blender（无头 CLI 或 Blender MCP）创作和编辑自定义模型。

动画与补间

技能：animations-tweens — 使用 Animator 播放 GLTF 动画片段、以编程方式创建 Tween 和 TweenSequence、缓动函数。

材质与渲染

技能：advanced-rendering — PBR 材质、TextShape、Billboard、VisibilityComponent、纹理模式。

光照与环境

技能：lighting-environment — 点光源／聚光灯、阴影、SkyboxTime（昼夜循环）、自发光材质。

粒子系统

技能：particle-system — 用于火焰、烟雾、火花、雪、雨、魔法和烟花的 ParticleSystem 组件。发射器形状（Point/Sphere/Cone/Box）、连续速率与 Burst 发射、重力、精灵图动画、混合模式。

点击与接近交互

技能：add-interactivity — pointerEventsSystem、触发区域、射线投射。基于轮询的输入请参阅 advanced-input。

高级输入与移动控制

技能：advanced-input — inputSystem 轮询、WASD 控制的实体、InputModifier、PointerLock、PrimaryPointerInfo、TouchScreenControls（移动设备上的屏幕摇杆／准星／按钮）。

玩家与化身

技能：player-avatar — 玩家位置／档案、表情动作、可穿戴物品、AvatarAttach、AvatarNametag、AvatarModifierArea。

化身动画（自定义表情动作）

技能：avatar-animations — 在官方 Decentraland 骨架上使用 Blender 创作自定义化身动画：骨架控制、姿势规则、导出为 *_emote.glb、GLB 验证，以及上半身（遮罩）动画片段。

NPC

技能：npcs — AvatarShape NPC，以及用于基于 GLB 的 NPC 的 NPC Toolkit 库，支持对话和状态机。

玩家物理

技能：player-physics — 冲量、击退、排斥场。

摄像机

技能：camera-control — 摄像机状态、CameraModeArea、用于电影镜头的 VirtualCamera。

字体

技能：fonts — TextShape 和所有 UI 文本支持内置字体（font）和随场景打包的自定义 .ttf 字体（fontSrc）。涵盖 Explorer 支持矩阵、移动设备不支持的情况、限制、许可，以及桌面客户端仅从资源包中显示自定义字体的原因。

屏幕空间 UI

技能：build-ui — 用于 2D 屏幕空间 UI 覆盖层的 React ECS 组件：布局、文本、图像、按钮、输入框、滑块。默认情况下会编写 Creator Hub 的 2D UI 编辑器（UI Designer）可读取和编辑的 UI——包括 src/ui/ 按组件拆分的文件布局、state/props 绑定接口、useInteraction 样式层、@ui-action 处理程序，以及将动画置于编辑器可触及范围之外的驱动器模式——仅当编辑器无法表示数据驱动型 UI 时，才回退到自由形式的代码化 React-ECS。还涵盖如何改造现有的代码化 UI，使其适用于编辑器。

玩家反馈与游戏测试

技能：scene-feedback — 帮助创作者选择游戏测试重点、审阅调整后的问题和时间安排，然后整合游戏问题或由玩家打开的表单。也可用于检索和分析 World 场景 Storage 中现有的 Scene Feedback CSV 回复。

音频与视频

技能：audio-video — AudioSource、AudioStream、VideoPlayer、媒体权限。

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

技能：audio-analysis — 用于从任意 AudioSource/AudioStream/VideoPlayer 实时获取振幅和 8 频段频率数据的 AudioAnalysis 组件。根据音乐驱动缩放、颜色、灯光和粒子。仅适用于 Unity-explorer。

区块链与 NFT

技能：nft-blockchain — NftShape、钱包检查、代币门控、签名请求、智能合约。

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

技能：multiplayer-sync — 用于点对点同步的 syncEntity、MessageBus、父子同步。

多人游戏服务端

技能：authoritative-server — 无头服务端、isServer()、registerMessages()、Storage、EnvVar。需要 @dcl/sdk@auth-server。

脚本组件（Creator Hub）

技能：script-components — 为 Creator Hub 的 Script 组件编写 .ts 脚本文件、构造函数参数、@action JSDoc 标签（切勿使用装饰器语法）。

Creator Hub MCP（实时场景编辑）

技能：creator-hub-mcp — 通过其 MCP 服务编辑 Creator Hub 中打开的场景：工具目录（scene_state、create_entity、set_component、place_smart_item、attach_script、set_scene_settings、launch_preview，等等）、先读取后写入的工作流、放置目录物品和自定义模型，以及如何将外部 Agent（Claude Code、Cursor、Codex）连接到它。只要场景在 Creator Hub 中打开，这就是修改实体的首选方式，而不是编辑 main.composite。

在 Explorer 中测试（MCP）

技能：unity-explorer-mcp — 通过运行中的 Decentraland Explorer 的 MCP 自动化服务进行操作：启动、摄像机和玩家移动、截图、日志、性能统计。在 Creator Hub 中，可以通过 Creator Hub MCP 的 launch_preview / explorer_* 使用相同的工具。

异步、HTTP、WebSocket、计时器

技能：scene-runtime — executeTask、fetch、signedFetch、WebSocket、计时器、realm/scene 信息、受限操作。

场景优化

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

游戏设计

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

技能：unity-explorer-mcp — 启动 Decentraland Explorer 并通过 MCP 操作它，以便在游戏中查看场景、行走、点击、截图和调试。如果 explorer MCP 服务在会话开始时报告 ConnectionRefused，或根本没有设置，这也是对应的解决方案——这两种情况都只意味着 Explorer 尚未运行。

部署

• 技能：deploy-scene — Genesis City 部署、dcl deploy、故障排查。
• 技能：deploy-worlds — Personal Worlds、worldConfiguration、ENS/DCL NAME 要求。

报告 SDK 问题

技能：report-sdk-issue — 在尝试规避问题之前，向 Decentraland 团队报告 SDK、引擎或 Explorer 的 Bug 和限制。每个场景只询问一次是否同意，会保留本地忽略记录，以免重复发送，并在离线时将报告加入队列。

场景复盘

技能：scene-retro — 当用户要求对场景或游戏进行复盘、回顾或事后分析（“根据这款游戏制作一份复盘报告”）时，检查会话历史，并将真实的错误、失败的首次尝试和所有者的纠正转化为有证据支持的技能改进建议。只读：保存报告，不做其他更改。

SDK6 → SDK7 迁移

技能：migrate-sdk6-to-sdk7 — 将旧版 decentraland-ecs 场景移植到 SDK7。介绍 ECS 的概念转变（实体作为 ID、仅含数据的组件、可变/不可变访问）、完整的 API 对照（new Entity() → engine.addEntity()、GLTFShape → GltfContainer、OnPointerDown → pointerEventsSystem、ISystem 类 → 自由函数、Input.instance → inputSystem 等），以及带注释的迁移前后示例。

---

术语 — 已弃用的工具名称

旧名称仍会出现在教程、论坛帖子和模型生成的回答中。不要向用户推荐这些名称；如果用户提到其中一个，请告知他们当前使用的名称：

已弃用的名称	曾指什么	应改用的名称
Web Editor	基于浏览器的场景编辑器	Creator Hub
Decentraland Editor	Visual Studio Code 扩展	Creator Hub
SDK6	旧版 SDK；其代码无法在当前 Decentraland 中运行	SDK7（要移植旧场景，请参阅 migrate-sdk6-to-sdk7 技能）
dclcontext folder	场景项目中下载的 AI 上下文文件	SDK Skills（这些技能）

当前名称：Creator Hub、Scene Editor、SDK7、SDK Skills。已根据文档术语表提交 4b6733c 核实。

共享参考资料

这些参考文件供多个技能使用。需要详细的组件 API、验证规则或资源目录时，请加载它们。

组件参考

参考：{baseDir}/references/components-reference.md 快速查阅常用 SDK7 组件的关键字段、类型和默认值。要查看组件的完整字段列表，请查阅其专属技能或 SDK 类型定义。

实体验证规则

参考：{baseDir}/../create-scene/references/entity-validation-rules.md 验证实体组件组合的规则——哪些组件需要搭配使用、哪些组件不能同时使用，以及常见配置错误。对组合式实体和 TypeScript 实体均适用。

免费资源目录

• 3D 模型（8,800+ 个）： {baseDir}/../add-3d-models/references/model-catalog.md — 优化后的 3D 模型，附带描述、尺寸、动画和下载 URL
• Creator Hub 资源包（420 个模型 + 7 个 Smart Items，最新新增内容）： {baseDir}/../add-3d-models/references/asset-pack-catalog.md — Genesis City 建筑、街道、家具和自然景观，万圣节、科幻实验室套件、脚本化按钮/门/平台/水；多文件下载助手见 model-patterns.md
• Avatar 动画（32 个内置表情动作 + 45 个可下载片段）： {baseDir}/../avatar-animations/references/animation-catalog.md — 编写任何表情动作前请先查阅
• 音频（50 种声音）： {baseDir}/../audio-video/references/audio-catalog.md — 音乐、环境音、音效、游戏机制、UI 声音

组合体

参考：{baseDir}/../composites/composite-reference.md 用于声明初始场景实体的 .composite JSON 格式。包含在 TypeScript 中获取组合体实体的 getEntityOrNullByName 和 getEntitiesByTag 模式。

库参考资料

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

---

使用方法

1. 根据用户请求确定主题
2. 加载对应技能——其中包含完整 API、代码模式和规则
3. 对于涉及多个主题的广泛请求，加载每个相关技能
4. 查找资源时，加载相关目录，并在获取任何资源前推荐具体资源