SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场deploy-scene

deploy-scene

部署与运维

查看项目

更新于 10-15 13:41

技能介绍

用途

本技能用于把 Decentraland 场景部署（发布）到 Genesis City，即基于 LAND 的部署方式。适用于用户希望部署或发布到自己拥有的地块，或希望减小已部署场景体积的场景。若目标是通过 DCL NAME 或 ENS 域名部署到 World（个人空间），则应使用 deploy-worlds 技能。

使用方式与部署流程

使用 /deploy 命令进行部署，它运行 npx @dcl/sdk-commands deploy 并处理完整流程：构建场景、上传资产到 IPFS、部署到指定地块。前提是拥有带有 LAND 或部署权限的钱包。

使用 CLI 时：

# Build first
npx @dcl/sdk-commands build

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

也可通过 Creator Hub：打开 Creator Hub，选择场景，点击 “Publish”，连接钱包，确认交易。

部署前检查清单

  • scene.json 有效：ecs7: true 且 runtimeVersion: "7"；parcels 与所拥有的 LAND 匹配；有效的 base parcel；main: "bin/index.js"。
  • 发现元数据完整，包括 display.title（场景名称，显示在小地图下方及地图弹窗中）、display.description（一两句描述）、tags（根级数组，1-3 个 Places-dApp 分类，取值来自预定义列表：art、game、casino、social、music、fashion、crypto、education、shop、business、sports、parkour）、display.navmapThumbnail（已设置且图片有效：文件存在或 URL 可解析，16:9 比例，推荐 1920x1080，关键内容位于中央 1080x1080 方形区域内）。
  • 代码可编译：npx tsc --noEmit。
  • 场景预览正常：可通过多浏览器标签验证多人行为。
  • 依赖已安装：npm install。
  • 资产在限制内：参见 optimize-scene 技能了解每个地块数量的三角形、实体、材质、纹理限制公式以及 330 米高度上限，尽量让场景加载时间低于 15 秒。
  • .dclignore 覆盖所有工作文件（Blender/FBX 源文件、概念图、表格、markdown 文档等不应上传）。

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；需保持 16:9，否则会被拉伸；中央 1080x1080 方形为安全区，文字、logo 和主体应位于其中；大小需小于 1 MB（1,048,576 字节），否则 Worlds 内容服务器会在部署时拒绝。值可以是项目内路径或外部托管图片 URL（外部主机需提供宽松的 CORS 头）。可用 unity-explorer MCP 自行截图，或使用 ImageMagick、macOS 的 sips 工具进行居中裁剪和缩放。

生成点

可配置玩家进入场景时的出现位置，position 支持范围（如 [1, 5]）使玩家在范围内随机生成，cameraTarget 用于设定初始相机朝向：

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

.dclignore

.dclignore 位于项目根目录，列出部署时不上传到内容服务器的文件和模式。项目文件夹中未被 .dclignore 匹配的全部内容都会上传，并计入每地块的 MB 限制，因此只应部署运行场景实际需要的文件。格式为每行一个 glob 模式。若部署失败提示 “Scene is too large”，第一步应检查 .dclignore，工作文件往往是超出体积的主要部分。不要忽略运行时需要的文件：bin/index.js、scene.json、assets/（合成物、.glb 模型、纹理、声音、视频）、scene.json 中引用的缩略图或代码中引用的任何文件路径。

发布后：资产包转换

每次发布后，内容服务器会把所有 .gltf/.glb 模型压缩为 asset bundles（更轻量的格式）。转换会立即开始但按平台（Windows、Mac）排队。转换期间会向玩家提供上一个完整可用的场景版本。典型耗时为数秒，大型场景或转换服务器繁忙时更长；若转换运行超过几分钟则是失败信号。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。

故障排查

  • “You don't have permission to deploy”：钱包不拥有目标 LAND/地块，需在市场上验证所有权，或从 LAND 所有者处获得部署权限。
  • “Scene is too large”：资产超出地块大小限制，先将工作文件加入 .dclignore，再对照限制检查三角形数、文件大小和纹理数量。
  • 钱包连接失败：浏览器弹窗被拦截或 MetaMask 锁定，允许弹窗并解锁后重试。
  • “Invalid scene.json”：缺少必填字段或 JSON 格式错误，验证 ecs7: true、runtimeVersion: "7"、有效 parcels 数组和 main: "bin/index.js"。
  • 部署成功但场景为空：main 未指向编译输出，确保 main 为 "bin/index.js" 并先运行 build。
  • Catalyst 拒绝：内容违反 Decentraland 内容政策。
  • 部署后场景看起来损坏：资产包转换尚未完成，用 /detectabs 检查并等待。
  • 部分玩家看到旧版本：各平台转换完成时间不同加上客户端缓存，需等待两个平台都完成，受影响玩家完全重启 Decentraland。
  • 发布卡在 Converting 阶段：转换失败或排队在其他场景之后，检查队列状态 URL，如某平台显示 failed 则重新发布。
  • 部署后 3D 模型缺失、变黑或无纹理：转换仍在进行，或纹理超出转换上限（3D 模型纹理转换时限制为 1024x1024）。
  • 近看正常远看损坏：LOD 生成尚未完成，不阻止近距离测试。

Genesis City 与 Worlds 对比

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

场景打赏

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

{
  "creator": "0x1234567890123456789012345678901234567890"
}

设置后，访客左上角会显示一个存钱罐图标，点击打开 MANA 打赏弹窗。如果该地址关联了 Decentraland NAME，弹窗中会显示该名称。创作者会收到每笔打赏的应用内通知。也可通过 Creator Hub → 场景 Settings → Details → Creator wallet address 配置。

限制

本技能不安装在 Creator Hub 代理内，Creator Hub 的技能安装器将此技能列入拒绝名单，且该目录只有 SKILL.md 会被完全跳过，不会到达应用内置 AI 助手。Creator Hub 通过自己的 UI 负责发布。在 Creator Hub 之外（Claude Code、Cursor、SDK agent），该技能正常工作。