用途 该技能用于从零搭建一个新的 Decentraland SDK7 场景项目,适用于用户想要新建场景或创建项目时。它明确不用于部署场景(部署参见 deploy-scene 技能)。
运行时前提 Decentraland 运行在 QuickJS 沙盒中,不提供 Node.js API(fs、http、path、process 等)。异步任务需使用 SDK 的 executeTask() 配合 fetch(),具体细节参见 scene-runtime 技能。生成任何代码前须知:场景加载时存在的全部初始实体(everything present at scene load)都必须放在 assets/scene/main.composite 中,绝不能写在 src/index.ts。
使用方式(按步骤)
- 确认需求:若用户未描述场景,需询问场景类型(画廊、游戏、社交空间、交互艺术等)、地块数量(默认 1 块 = 16x16m)以及特定功能(3D 模型、交互、UI、多人)。
- 用 /init 搭建项目:始终先运行 /init,它使用官方 @dcl/sdk-commands init 生成 scene.json、package.json、tsconfig.json 与 src/index.ts,并自动安装依赖。不要手写这些配置文件,模板可能随版本变化。tsconfig 的 jsx 与 jsxImportSource 设置已由 /init 包含,不要修改。
- 查找匹配的 3D 资源:仅当提示明确要求添加新模型时才从免费目录获取,并且必须与用户确认。可从 {baseDir}/../add-3d-models/references/model-catalog.md(8,800+ 模型,含描述、尺寸、动画与下载 URL)检索,并阅读 {baseDir}/../audio-video/references/audio-catalog.md(50 个免费音效)。下载到场景的 assets/Models/ 目录,例如 mkdir -p assets/Models 后 curl 下载。GltfContainer 只能使用本地文件,src 字段禁止使用外部 URL;不要写到场景根目录。已有目录优先,如 assets/scene/Models/、assets/asset-packs/、assets/custom/ 等路径应复用。
- 定制生成文件:在 scene.json 中设置 display.title、display.description、tags(根级数组,1-3 个,值取自预定义列表:art、game、casino、social、music、fashion、crypto、education、shop、business、sports、parkour)、scene.parcels、scene.base(西南角地块)。
复合文件与 TypeScript 的分工 初始场景实体(加载时存在的模型、灯光、图元、文字、音频,静态与装饰物,以及需要后续附加行为的实体)必须放在 assets/scene/main.composite;只有运行时动态生成的实体(投射物、克隆、按需出现的 NPC 等)才写入 src/index.ts。复合资源加载更快、可在 Creator Hub 中可视化编辑,并让 TypeScript 专注于逻辑。
编辑 composite 的注意事项 放置地板实体时,y 位置必须设为 0.01 或更高,避免与默认地面 z-fighting。单地块场景地面中心为 (8, 0, 8)。Y 轴向上,地面为 Y=0。如需在代码中引用复合实体,应通过名称或标签查找(如 engine.getEntityOrNullByName、engine.getEntitiesByTag),不要在代码中重新创建。若场景已在 Creator Hub 中打开,应通过 Creator Hub MCP 修改,而非直接编辑文件,否则会被编辑器自动保存覆盖。
scene.json 关键字段 必填/推荐字段包括 runtimeVersion("7")、main("bin/index.js")、scene.parcels、scene.base;推荐字段有 display.title、display.description、display.navmapThumbnail(16:9,1920x1080 推荐)、tags。可选字段含 spawnPoints、requiredPermissions、allowedMediaHostnames、featureToggles、worldConfiguration、landscapeTerrain。
权限说明 运行时识别 7 个权限字符串:ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE、ALLOW_TO_TRIGGER_AVATAR_EMOTE、ALLOW_MEDIA_HOSTNAMES(LEGACY)、USE_WEB3_API、USE_FETCH、USE_WEBSOCKET、OPEN_EXTERNAL_LINK。资料指出权限执行并不完全一致,应按意图声明正确权限。ALLOW_MEDIA_HOSTNAMES 与 allowedMediaHostnames 对新建场景不再要求;teleportTo 不需要权限。
多地块与边界 单地块为 16x16m,2x2 场景为 32x32m,高度上限对所有场景为 330 米,放在约 200 米以上可能出现多人同步问题。有效范围为 0 ≤ x ≤ 16宽、0 ≤ z ≤ 16深,负坐标在场景外;完全在边界外的实体不会渲染且不报错。修改已有场景的 scene.parcels 会移动坐标边界,需先与用户确认。
完成校验条件 main.composite 能解析为 JSON 且每个实体 ID 都有 core::Transform 与 core-schema::Name;所有位置在边界内;src/index.ts 中没有用于加载时场景的 engine.addEntity();scene.json 的 runtimeVersion 为 "7" 且 scene.base 属于 scene.parcels;npm run build 退出码为 0。
创建后 使用预览工具启动预览服务器,或手动运行 npx @dcl/sdk-commands start --bevy-web,场景将在浏览器 http://localhost:8000 打开。预览 CLI 支持 --web(别名 --bevy-web),在 Bevy Web 浏览器客户端打开;Chromium 142+ 需要本地网络访问权限才能连接本地预览服务器。
限制与暂未提供 资料未提供收费、价格信息,也未提供该技能的完整安装命令及更多平台支持细节,相关事实暂未提供。