decentraland-sdk-skills

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）。这会改变所有实体的坐标边界。要继续吗？”

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 分支。你想要的是这种方案，还是更简单的点对点同步就能满足需求？”

总体原则

这些不是 Agent 应该拒绝执行的操作——而是应该在执行前与用户沟通的操作。如果用户确认，就放心继续。目标是保持透明，而不是设置门槛。

---

关键规则——优先使用 Composite 创建场景

所有静态实体（模型、灯光、出生点）都必须定义在 assets/scene/main.composite 中，不能通过 engine.addEntity() 在 TypeScript 中创建。

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

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

---

独立技能

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

场景设置与配置

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

3D 模型

技能：add-3d-models — 使用 GltfContainer 加载 .glb/.gltf、定位、碰撞体，以及浏览免费资源目录（8,800+ 个模型）。

动画与补间

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

材质与渲染

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

光照与环境

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

粒子系统

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

点击与接近交互

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

高级输入与移动控制

技能：advanced-input — inputSystem 轮询、由 WASD 控制的实体、InputModifier、PointerLock、PrimaryPointerInfo。

玩家与 Avatar

技能：player-avatar — 玩家位置／个人资料、表情动作、可穿戴物品、AvatarAttach、AvatarModifierArea。

NPC

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

玩家物理

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

摄像机

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

屏幕空间 UI

技能：build-ui — 用于 2D 世界内 UI 的 React ECS 组件：布局、文本、图像、按钮、输入框。

音频与视频

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

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

技能：audio-analysis — AudioAnalysis 组件，可从任意 AudioSource／AudioStream／VideoPlayer 获取实时振幅和 8 频段频率数据。根据音乐驱动缩放、颜色、灯光和粒子。仅适用于 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 组件编写 .tsx 脚本文件、构造函数参数、@action() 装饰器。

异步、HTTP、WebSocket、计时器

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

场景优化

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

游戏设计

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

部署

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

SDK6 → SDK7 迁移

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

---

共享参考资料

这些参考文件会在多项技能中使用。需要详细的组件 API、验证规则或资产目录时，请加载这些文件。

组件参考

参考：{baseDir}/sdk-scenes/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
• 音频（50 种声音）： {baseDir}/audio-video/references/audio-catalog.md — 音乐、环境音、音效、游戏机制音效、UI 音效

复合实体

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

库参考

• NPC 工具包： {baseDir}/npcs/references/npc-library.mdc — 基于 GLB 的 NPC，支持对话、移动和状态机
• Crypto/MANA： {baseDir}/nft-blockchain/references/crypto-library.mdc — MANA 操作、货币/NFT 交易、市场集成

---

使用方法

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