deploy-scene

部署到 Genesis City

未安装在 Creator Hub Agent 中。 Creator Hub 的技能安装程序会将此技能列入拒绝列表；而且该目录中只有 SKILL.md，因此会被完全跳过——不会进入应用内嵌的 AI 助手。Creator Hub 通过自己的 UI 管理发布。如果你是 Creator Hub 助手，用户要求发布时，请引导他们使用应用的发布流程。在 Creator Hub 之外（Claude Code、Cursor、SDK Agent）可以正常使用此技能。

部署到你拥有或获准部署的特定地块。

使用 /deploy 命令进行部署。该命令运行 npx @dcl/sdk-commands deploy 并处理整个流程：

1. 构建场景
2. 将资源上传到 IPFS
3. 部署到指定地块
4. 需要拥有 LAND 或部署权限的钱包

要改为部署到 World？ 请参阅 deploy-worlds 技能，了解 Worlds 部署（使用 DCL NAMEs 或 ENS 域名的个人空间）。

部署前检查清单

部署前，请确认：

1. scene.json 有效：

   • ecs7: true 和 runtimeVersion: "7"
   • parcels 与你的 LAND（适用于 Genesis City）匹配
   • base 地块有效
   • main: "bin/index.js"

2. 发现元数据完整 — 以下四个字段决定是否有人能找到并进入场景，而且它们经常保留模板默认值。逐项检查，并根据场景本身能推断的信息填写；只有无法推断时才询问用户：

   • display.title — 场景名称，会显示在游戏内小地图下方和地图弹窗中
   • display.description — 用一两句话说明场景内容
   • tags — 根级数组，从预定义列表中选择 1–3 个 Places-dApp 类别："art"、"game"、"casino"、"social"、"music"、"fashion"、"crypto"、"education"、"shop"、"business"、"sports"、"parkour"。根据场景主题推断（参见 create-scene 技能中的“标签（场景类别）”）
   • display.navmapThumbnail — 设置该字段，_并且_确保图片本身有效：引用的文件存在于项目中（或 URL 可访问），尺寸为 16:9（建议 1920x1080），且关键内容位于中央 1080x1080 方形区域内。通过 shell 检查尺寸 — 在 macOS 上使用 sips -g pixelWidth -g pixelHeight <path>，或使用 magick identify -format "%wx%h\n" <path> — 然后裁切中央方形并查看裁切后的图片，而非完整画面。所有文字和主体都必须位于其中。在 macOS 上：H=$(sips -g pixelHeight <path> | awk '/pixelHeight/{print $2}'); sips -c $H $H <path> --out "${TMPDIR:-/tmp}/thumb-square.png"。使用 ImageMagick：H=$(magick identify -format %h <path>); magick <path> -gravity center -crop ${H}x${H}+0+0 +repage "${TMPDIR:-/tmp}/thumb-square.png"。然后读取方形图片。如果图片缺失、比例不正确或主体偏在一侧，请重新截取 — 参见下文的 缩略图 部分

3. 代码可编译：

   npx tsc --noEmit
   

4. 场景预览正确： 使用 preview 工具验证场景是否正常运行（或手动运行 npx @dcl/sdk-commands start，也可以添加 --web，在 Bevy Web 浏览器客户端中预览）。使用多个浏览器标签页测试，以验证多人游戏行为。

5. 已安装依赖项：

   npm install
   

6. 资源未超出限制 — 关于按地块数量计算的各项限制公式（三角形、实体、材质、纹理）以及固定的 330 m 高度限制，请参阅 optimize-scene 技能。通过优化资源，将场景加载时间控制在 15 秒以内。

   然后，在部署前检查实际将要上传的内容大小，不要等到被拒绝后再检查：

   find assets -type f -size +1M -exec ls -lh {} +        # the heavy files
   npx @gltf-transform/cli inspect assets/Models/big.glb   # Textures table: each embedded map's resolution and bytes
   

   内嵌的 2048 px 纹理贴图最容易让人意外 — 两个生成的 GLB 在一个 34 MB 的场景中包含了 17 MB 的这类贴图，直到发布后才被发现（Agent 报告，2026-10）。将它们缩小到 1024 或更低（使用 npx @gltf-transform/cli resize in.glb out.glb --width 1024 --height 1024，或在 Blender 中操作 — 参见 optimize-scene）：转换器无论如何都会缩小到 1024，而原始文件仍会按完整大小计入。不要根据项目中的 bin/index.js 估算：预览的开发构建包含内联源映射且未经压缩，而 deploy 会使用 --production 重新构建（已压缩、无映射 — @dcl/sdk-commands 中的 commands/deploy/index.ts），大小通常只有前者的一小部分。

7. .dclignore 涵盖所有工作文件 — Blender/FBX 源文件、概念图、电子表格、Markdown 文档等都不得上传。参见下文的 .dclignore 部分。

部署流程

使用 CLI

# Build first
npx @dcl/sdk-commands build

# Deploy (will open browser for wallet connection)
npx @dcl/sdk-commands deploy

使用 Creator Hub

1. 打开 Creator Hub
2. 选择你的场景
3. 点击“发布”
4. 连接钱包
5. 确认交易

发布后要分享的链接

成功面板会显示并复制一个 网页 /jump 链接，没有桌面客户端的玩家也能使用；其 Jump In 按钮则会单独打开桌面客户端（creator-hub 4305bb17c）。为玩家编写内容时，请使用相同格式的链接：

目标	分享链接
Genesis City 场景	https://decentraland.org/jump?position=x,y
World	https://decentraland.org/jump?realm=NAME.dcl.eth
直接打开桌面客户端	decentraland://?position=x,y&dclenv=<env>（或 ?realm=…）

/jump 是规范路径——旧版 /play/... 路径只会重定向到该路径（301），因此不要生成旧版路径。

用于部署的 scene.json

{
  "ecs7": true,
  "runtimeVersion": "7",
  "display": {
    "title": "My Awesome Scene",
    "description": "A description for the marketplace",
    "navmapThumbnail": "images/thumbnail.png"
  },
  "tags": ["art", "social"],
  "scene": {
    "parcels": ["0,0", "0,1"],
    "base": "0,0"
  },
  "main": "bin/index.js"
}

tags 位于根级别，而不是 display 下。有效的类别值请参阅上方的清单条目。

缩略图

display.navmapThumbnail 是玩家选择场景地块时在地图模态框中看到的图片，也是其他场景将玩家传送到此处时在确认屏幕上看到的图片。请务必提供。

规格：

• .png 或 .jpg，16:9 宽高比，建议尺寸为 1920x1080 px。其他尺寸也可，只要保持 16:9——否则图片会被拉伸
• **中央方形安全区域：**平台的部分界面会显示中央 1080x1080 px 的方形裁剪区域。请将文字、徽标和主体内容放在该区域内。在 1920x1080 图片中，左右两侧各 420 px 的区域可能会被裁掉
• 小于 1 MB（1,048,576 字节）——Worlds 内容服务器在部署时会拒绝更大的文件（Invalid thumbnail: size … exceeds maximum of 1048576 bytes (1MB)），而普通的 1920x1080 PNG 可能超过此大小。发布前用 ls -l 检查；如果超出限制，请改为导出 JPEG（ffmpeg -i images/thumbnail.png -q:v 2 images/thumbnail.jpg）。如果是生成而非捕获封面（例如 Blender 渲染或图像工具），请参阅 creator-hub-mcp > 注意事项
• 值可以是项目内的路径（例如 images/thumbnail.png），也可以是外部托管图片的 URL——外部主机必须提供宽松的 CORS 标头

**自行捕获——如果用户没有提供图片，请询问他们是否希望你来捕获。**使用 unity-explorer MCP（参见 unity-explorer-mcp 技能），在预览中运行场景，移动摄像机以构图展示场景主题——让关键内容位于中间三分之一处，并处于中央方形区域内——然后使用捆绑脚本捕获无 UI 的 PNG：

# <skill-dir> is the unity-explorer-mcp skill's base directory
<skill-dir>/scripts/screenshot.sh --world-only --png -w 1920 -o images/thumbnail.png

以 16:9 窗口模式启动客户端（npm run start -- --mcp -- --windowed-mode --resolution 1920x1080），即可原生获得 16:9 画面，无需裁剪。否则请对其进行标准化：

# ImageMagick: center-crop to 16:9 and resize, in one step
magick images/thumbnail.png -resize 1920x1080^ -gravity center -extent 1920x1080 images/thumbnail.png

# macOS, no extra tooling: -c takes HEIGHT then WIDTH, both centered
sips -g pixelWidth -g pixelHeight images/thumbnail.png   # read the source size first
sips -c 1080 1920 images/thumbnail.png --out images/thumbnail.png   # center-crop a larger frame
sips -z 1080 1920 images/thumbnail.png                              # then resample to exactly 1920x1080

将 display.navmapThumbnail 指向生成的路径。只有在 MCP 不可用时，才应向用户索要图片，而不是在没有图片的情况下发布场景。确保 .dclignore 未排除缩略图——必须将其与场景一同上传。

大小写很重要。navmapThumbnail 中的路径必须与磁盘上的文件夹名称完全一致：部署文件列表会保留磁盘上的大小写，而 Catalyst 会区分大小写；macOS 和 Windows 则会在本地解析任意大小写——因此，大小写不匹配会导致发布时出现 Scene thumbnail '…' must be a file included in the deployment，且在测试中始终不会显示。在 Creator Hub 项目中，标准文件夹为 assets/Images/（I 大写），Hub 也会将其自动生成的捕获图片写入此处。写入路径前先运行 ls assets，并且不要保留两个仅大小写不同的文件夹。

出生点

配置玩家进入场景时出现的位置：

{
  "spawnPoints": [
    {
      "name": "spawn1",
      "default": true,
      "position": { "x": [1, 5], "y": [0, 0], "z": [2, 4] },
      "cameraTarget": { "x": 8, "y": 1, "z": 8 }
    }
  ]
}

位置范围（例如 [1, 5]）会让玩家在该范围内随机出生。使用 cameraTarget 设置玩家出生时摄像机的朝向。

.dclignore — 排除上传文件

.dclignore 文件始终位于项目根目录，用于列出部署时不会上传到内容服务的文件和匹配模式。项目文件夹中所有未匹配 .dclignore 的内容都会上传，上传总量会计入每个地块的 MB 限制，因此部署时只应包含运行中的场景实际需要的文件。

格式：每行一个 glob 匹配模式。场景模板中的默认配置：

.*
package-lock.json
yarn-lock.json
build.json
export
tsconfig.json
tslint.json
node_modules
*.ts
*.tsx
.vscode
Dockerfile
dist
README.md
*.blend
*.fbx
*.zip
*.rar
*.md
src

随着项目扩展，及时更新此文件。 只要项目中存在工作文件——Blender 或其他 3D 源文件、模型草稿、概念图、PSD、电子表格、Markdown 笔记、参考照片——就将它们（或其扩展名）加入 .dclignore，让部署的场景尽可能精简。创建或编辑场景时，应主动添加这些匹配模式；不要等到部署失败后才处理。常见的添加项：

*.blend
*.blend1
*.fbx
*.psd
*.kra
*.xcf
*.md
*.csv
*.xlsx
drafts
concept-art
reference

如果部署失败并提示 “Scene is too large”，首先检查 .dclignore：超出部分通常主要是工作文件，排除它们可以缩小上传体积，且不会影响场景。

切勿忽略场景运行时需要的文件： bin/index.js、scene.json、assets/（合成文件、.glb 模型、纹理、声音、视频）、scene.json 中引用的缩略图，以及代码中引用的任何文件路径。请注意，默认配置会忽略 *.ts/src——只有编译后的 bin/index.js 会运行，因此上传时不需要源代码。

发布后：资源包转换

每次发布后，内容服务都会将所有 .gltf/.glb 模型压缩为资源包——这是一种体积显著更小的格式。转换会立即开始，但会按平台（Windows、Mac）排队。在转换期间，玩家会看到场景最后一个完全可用的版本，这是有意为之。

• 通常耗时： 几秒。 对于非常大的场景，或转换服务繁忙时，耗时会更长。（文档此前记载为约 15 分钟 / 30-60 分钟；已在文档提交 2dfbb00 中更正。）
• 转换运行超过几分钟是故障信号，并非正常排队；请检查状态端点，而不是继续等待。
• 场景可玩后，“Jump In”按钮就会出现，即上传和转换完成后。
• 举办现场活动前： 至少提前一小时发布最终版本，为意外情况留出余地。等待期间避免重新发布——每次发布都会重新开始排队。
• 在浏览器中检查转换状态：
  • https://asset-bundle-registry.decentraland.org/entities/status/<pointer> — 将 <pointer> 替换为场景坐标（例如 20,-34）或部署实体 ID。此端点会在 assetBundles 下显示各平台的状态，并在 lods 下显示 LOD 状态。对于 World，请追加 ?world_name=myname.dcl.eth。
  • https://asset-bundle-registry.decentraland.org/queues/status — 按平台列出当前排队等待转换的所有场景。
• /detectabs 聊天命令： 在世界中运行此命令，会将模型染成绿色（已转换）或红色（尚未转换）。
• 仅重新加载场景无法获取新版本——重新加载会重启场景代码，但不会获取新发布的内容。本次会话中已经加载场景的玩家会继续看到缓存版本，直到完全关闭并重新进入 Decentraland。 你也一样：转换完成后，退出并重新启动，然后通过跳转链接或 /goto 重新进入。

你也可以在发布前启用预览中的本地资源包，提前发现转换问题——请参阅 optimize-scene 技能中的“本地资源包预览”。

故障排除

错误	原因	解决方案
"You don't have permission to deploy"	钱包不拥有目标 LAND/地块	在市场中验证 LAND 所有权，或从 LAND 所有者处获取部署权限
"Scene is too large"	资源超出地块大小限制	先将所有工作文件（Blender/FBX 源文件、概念图、文档）添加到 .dclignore 中——请参阅上方的 .dclignore 部分。然后对照限制检查三角形数量、文件大小和纹理数量。请参阅 optimize-scene 技能
Wallet connection fails	浏览器弹窗被拦截或 MetaMask 已锁定	允许弹出窗口，解锁 MetaMask，刷新后重试
"Invalid scene.json"	缺少必填字段或 JSON 格式错误	验证 ecs7: true、runtimeVersion: "7"、有效的 parcels 数组，以及 main: "bin/index.js"
Deploy succeeds but scene is empty	main 字段未指向编译后的输出	确保 main 为 "bin/index.js"，并先运行 npx @dcl/sdk-commands build
Catalyst rejection	内容违反 Decentraland 内容政策	在 docs.decentraland.org 查看内容指南
Scene looks broken right after deploy	资源包转换尚未完成	在聊天中输入 /detectabs——红色模型表示尚未转换。检查转换状态（见上文）并等待
Some players see old version, others see new	各平台转换完成时间不同，加上客户端缓存	在转换状态端点的 assetBundles 下检查 windows 和 mac。两者均为 complete 后，受影响的玩家必须完全重启 Decentraland
Publication stuck on Converting stage	转换失败，或场景正在其他场景之后排队	转换通常只需几秒，因此超过几分钟通常意味着失败，而不是排队。检查与你的实体 ID 对应的队列状态 URL。如果未排队，请检查转换状态——如果某个平台显示 failed，请重新发布。如果再次失败，请附上实体 ID 报告此问题
3D models missing, black, or untextured after deploy	转换仍在进行中，或纹理超出转换上限	使用 /detectabs 检查；转换时，3D 模型的纹理上限为 1024x1024（不是 512x512，该数值已过时）
Scene looks fine up close but broken from a distance	LOD 生成（最终发布阶段）尚未完成	检查转换状态端点中的 lods 值；LODs 不会妨碍近距离测试
"Scene thumbnail '…' must be a file included in the deployment" (the file plainly exists)	display.navmapThumbnail 与磁盘上的文件夹大小写不一致——通常是 scene.json 中的 assets/images/ 与磁盘上的 assets/Images/ 不一致	上传的文件列表会保留磁盘上的大小写，而 Catalyst 会区分大小写；macOS/Windows 则会在本地忽略大小写——因此只有部署时才会出现此问题。运行 ls assets 查看实际文件夹名称，并确保 navmapThumbnail 与之完全一致。标准路径为 assets/Images/（大写 I），这是资源导入器创建的文件夹。切勿保留两个仅大小写不同的文件夹
"Invalid thumbnail: size … exceeds maximum of 1048576 bytes"	缩略图超过 1 MB（普通的 1920x1080 PNG 就会超出）	以高画质导出 JPEG（ffmpeg -i cover.png -q:v 2 cover.jpg），或缩小至 1344x756。检查在部署时由服务端执行，因此本地不会收到任何警告。缩略图还必须为 16:9，误差在 1% 以内

Genesis City 与 Worlds

	Genesis City	Worlds
要求	拥有 LAND 地块	拥有 DCL NAME 或 ENS 域名
地块限制	强制执行（每个地块的实体／三角形预算）	不受 LAND 限制
可见性	显示在 Genesis City 地图上	列于 Places 页面（可选择不显示）
部署目标	默认的 Catalyst 网络	--target-content https://worlds-content-server.decentraland.org
最适合	永久装置、高流量场景	测试、个人空间、活动

要改为部署到 World？ 请参阅 deploy-worlds 技能。

场景打赏

让访客向场景创建者发送 MANA 打赏。在 scene.json 中添加 creator 字段：

{
  "creator": "0x1234567890123456789012345678901234567890"
}

设置后，访客会在左上角看到一个存钱罐图标。点击后会打开 MANA 打赏弹窗。如果该地址关联了 Decentraland NAME，弹窗中会显示该名称。创建者每收到一笔打赏，都会收到一条应用内通知。

也可通过 Creator Hub → 场景设置 → 详情 → 创建者钱包地址进行配置。