add-3d-models

向 Decentraland 场景添加 3D 模型

规则：放置模型前检查包围盒

模型的 Transform.position 是其局部原点，而不是视觉范围。 植被和大型结构模型通常会延伸到原点之外 6-12 m。放置在 x=2 处的树可能会渲染在 x=-10 处——超出场景边界，无法显示。

放置任何 GLB 模型前，都要确定其实际世界空间包围盒。 原始 accessor 的 min/max 值并不足够——许多模型都烘焙了较大的节点级缩放。你必须考虑节点变换。请使用 {baseDir}/references/model-patterns.md 中的包围盒脚本。

然后计算安全放置区域：safeMinX = -bbox.minX + edgeMargin (>=1m) 等。只在安全区域内放置原点。如果包围盒未知，树木/大型树叶使用距所有边缘 12 m 的缓冲区，小型道具使用 3 m。

规则：几何体烘焙在世界坐标中时，检查 DCL 轴上的边界，并先探测轴向

上述包围盒规则假设模型以自身原点为中心构建，并通过 Transform 定位。一旦你将世界空间中的位置烘焙进网格——例如整个区域合并后的地面/墙体块、导出为单个 GLB 的拼装布局，或由 Blender 中的脚本而非实体 Transform 放置的任何内容——模型的位置就取决于导出器的轴向约定。猜错轴向会让几何体落在场景之外，而你能读到的所有数值看起来却都正确。

故障模式，观察于 2026-10-08（耗时约 1.5 h）： 渲染会在场景边界处被裁剪，因此只有落在地块之外的网格部分会消失——模型的其余部分仍然可见。这正是轴向猜错让人困惑的地方：如果整个烘焙网格都落在外面（例如在 X 轴上镜像），整个网格都会被裁剪，且不会报错，即使实体自身的 Transform.position 位于场景内也是如此。Explorer 和 Creator Hub 编辑器都会以相同方式裁剪；Creator Hub 的 get_scene_metrics.entitiesOutOfBoundaries 也不会列出该模型——在 Bevy 渲染器下，该列表是硬编码的空数组（已在检查器的 BevyRenderer 中确认），因此它永远无法发出警告；在 Babylon 下，该列表则基于边界计算，会发出警告。判断线索是两项读取结果互相矛盾：

• explorer_get_scene_content_stats 会统计模型的三角形——说明 GLB 已成功加载；
• explorer_get_scene_content_breakdown 会显示来源包含 N 个 renderers，且从每个视角看，visibleRenderers: 0；
• 场景日志正常。

尺寸不是原因：同一场景中，一个完全处于边界内的 36 × 30 m 网格能够正常渲染。

因此，烘焙正式模型前，先导出一个简单的不对称探测模型并查看效果。 对称方块毫无用处——它无法显现镜像和旋转错误。使用一侧明显可辨的模型：一根沿 +X 方向的短杆，加上一根长度不同的沿 +Z 方向的杆；或者任何一端开口的资产。将其放置在已知位置，然后在场景中确认（使用 unity-explorer-mcp）：从已知摄像机姿势截图、走进模型并从 explorer_get_player_state 读取受阻位置，或两者都做。确认后再烘焙整套模型。重新烘焙一套模型的成本远高于导出一个一次性探测模型。

Blender → DCL 的轴向映射和 place() 辅助函数见 {baseDir}/references/blender-authoring.md。 另请注意，{baseDir}/references/model-patterns.md 中的包围盒脚本报告的是 glTF 轴向，并非所有组件的 DCL 轴向——与场景边界比较前请先转换。

规则：在放置相邻实体前考虑模型深度

两个模型的原点不同，并不意味着它们就不会重叠。务必确认 origin +/- extent 不会与任何相邻模型的包围盒相交。尤其注意深拱门/入口模型（在 +/-Z 方向可能延伸 14 m）和旋转后的模型（绕 Y 轴旋转 90 度会交换 X 和 Z 方向的范围）。

规则：为第三人称镜头放大室内空间

这是本指南的规范版本；其他技能会链接到此处，而不是重复这些数值。 这是基于实践经验的设计指导（Decentraland 工作人员于 2026-10-08 在 Explorer 中体验场景后的反馈），并非引擎常量。

Decentraland 的游玩大多使用默认的第三人称镜头，镜头位于化身后方上方。因此，室内在屏幕上看起来会比其现实尺寸小得多：镜头紧贴天花板，化身占据大部分画面，普通房间看起来像走廊。不要按现实尺寸建造房间。 空间高度大致应为现实的 1.5 倍至 2 倍：

元素	现实尺寸	建造尺寸
天花板高度	2.5–3 m	5–6 m
主通道的门口／开口	~2.1 m × 0.9 m	高约 4 m，宽 ≥3 m
走廊宽度	1.2–1.8 m	4 m 以上
化身必须穿过的任何间隙	—	净宽 ≥1.2 m

• 手边大小的道具应接近真人尺寸。 椅子、桌子、柜台、栏杆、屏幕和标识都应大致保持实际尺寸，这样化身在房间中看起来仍像一个人。随着空间一起放大家具，只会把拥挤感放大一号：放大房间，不要放大房间里的物品。
• 缩放目录模型时也要遵循此规则。 下方的模型替换审核会根据原始尺寸选择 scale；对于建筑模型，目标应是放大后的尺寸，而非现实尺寸。
• 按这些数值规划楼面面积。 放大的房间会改变平面布局所需的地块面积，因此计算边界时就要应用这些数值（参见 composites 第 0 步），而不是摆放后再调整。
• 从零售镜头视角判断，切勿使用自由镜头或编辑器视口。 这些视角会美化室内效果，因为镜头可以位于几何体之外。使用 third_person 沿路线行走，并从该视角截图（unity-explorer-mcp）。如果镜头被天花板挡住，或化身的头部挤到画面顶部，说明房间太矮。

观察记录，同一场体验： 首个室内外壳采用接近现实的高度建造（天花板高 4 m，门口高 2.8 m，飞机客舱高 2.2 m，廊桥高 2.6 m），在第三人称视角下显得很拥挤，创作者因此要求增加头顶空间。净宽 0.75 m 的金属探测器拱门需要几乎精确对齐，化身才能通过。

规则：单面模型——将渲染面朝向玩家

许多 GLB 模型会剔除背面。渲染面通常朝向局部 -Z。Y 轴旋转会改变朝向：0deg -> 南，90deg -> 东，180deg -> 北，270deg -> 西。如果玩家会从两侧接近，请添加一个旋转 180deg 的副本。对于从各个角度都能看到的元素，优先使用双面几何体。

Decentraland 使用 Y-up 坐标系——导入后请测试模型朝向：以 Z-up 导出的模型（Blender 中很常见）载入后会倾倒，必须重新导出并选择 "Y Up"。

规则：文本标签必须置于空旷处——避免被几何体遮挡

TextShape 标签以世界空间渲染，可能会被实体几何体遮挡。放置标签时，确保其水平方向 2 m 内没有实体模型，并留出足够的高度空间；使用 Billboard，将 billboardMode: 2 用于确保标签易读，并优先放在开阔区域。例外情况：安装在墙上的标签可以不使用 Billboard。

规则：初始模型使用 composite

场景加载时就存在的模型，始终添加到 assets/scene/main.composite，不要在 TypeScript 中添加。 仅对运行时动态生成的模型使用 TypeScript。如果模型没有 _collider 网格（常见情况），请使用 visibleMeshesCollisionMask: 3, invisibleMeshesCollisionMask: 0。如果模型有 _collider 网格，请使用 visibleMeshesCollisionMask: 0, invisibleMeshesCollisionMask: 3。切勿同时将两者设为非零值。

如需为 composite 模型添加行为，请按名称或标签在 index.ts 中获取该模型，不要重新创建它。

如果场景已在 Creator Hub 中打开，且其 MCP 工具可用，请通过这些工具添加模型，而不要编写 composite（技能：creator-hub-mcp）：对于目录项，使用 search_catalog + place_smart_item（目录包含静态项和 Smart Items，并会为你下载文件）；对于放置在 assets/Models/ 下的 GLB，使用 create_entity + set_component Transform + set_component core::GltfContainer。无论使用哪种方式，都适用本技能中的包围盒、碰撞掩码和 Animator 规则。

规则：替换模型 src 时必须使用新的 Transform — 绝不继承缩放／位置

当你更改现有 GltfContainer 的 src（在 composite、代码中或通过构建器替换资源）时，实体原有的 Transform.scale、Transform.position，以及通常的 rotation，都是针对先前模型的原生尺寸和枢轴调整的。它们几乎从不适用于新模型——盲目套用可能导致建筑超出场景边界、道具高度不对，或模型明显偏离用户预期的位置。

每次替换模型，都应视为一次全新的摆放：

1. 查询新 GLB 的原生包围盒 — 使用 {baseDir}/references/model-patterns.md 中的包围盒脚本（仅使用原始访问器的 min／max 不够；必须应用节点级缩放／平移）。
2. 重新计算 scale，使世界空间尺寸（原生尺寸 × 缩放）符合模型用途。不要沿用先前实体的缩放——它是根据不同的原生尺寸校准的。
3. 核实枢轴位置。 许多建筑／构筑物 GLB 的枢轴位于角落（例如，某个底角的坐标为 (0,0,0)），而不是中心。枢轴不同的两个模型即使 position 相同，替换后也会出现视觉偏移。
4. 核实最终世界空间包围盒是否位于场景边界内。 每块地块的水平尺寸为 16 × 16 m；无论地块数量多少，每个场景的最大高度均为 330 m（高于约 200 m 时可能出现多人同步问题 — 参见 {baseDir}/../optimize-scene/SKILL.md）。根据场景范围 [0, maxX] × [0, maxZ] 计算 position +/- bbox，并确保 y <= 330。
5. 明确说明审查结果。 替换模型后，Agent 必须报告：新 GLB 的原生尺寸、选定的缩放、选定的位置，以及最终世界空间包围盒与场景边界的关系。不要悄悄保留先前的 Transform。

此规则同样适用于代码（调用 GltfContainer.createOrReplace(entity, { src: '...' }) 时不更改 Transform）和 composite 编辑（只修改了 core::GltfContainer.data["<id>"].json.src）。

运行时替换机制：如需原位更改模型，直接修改字段 — GltfContainer.getMutable(entity).src = newSrc — 引擎会在同一实体上重新加载 GLB。其他 GltfContainer 字段（例如 visibleMeshesCollisionMask）也可以通过相同方式实时修改。仅当两个模型的原生尺寸和枢轴相同时，才能安全复用 Transform；否则请按上述步骤重新审查。

规则：编辑现有复合场景时，在 inspector::Nodes 中注册新实体

此规则适用于手动编辑文件；仅当 Creator Hub MCP 不可用时才应手动编辑（参见 creator-hub-mcp——它的 create_entity 会自动完成注册，而且在 Creator Hub 中打开场景时手动编辑会丢失更改）。

如果 assets/scene/main.composite 已包含 inspector::Nodes（说明用户至少在 Creator Hub 中打开过一次场景），你添加的每个新实体都必须同时在其中注册，否则它将在 Creator Hub 实体树中不可见——模型仍会在场景中渲染，但用户无法在编辑器中选择或编辑它。你还需要为新实体添加 core-schema::Name 条目和 inspector::TransformConfig 条目。

关于要追加的确切数组，请参见 {baseDir}/../composites/composite-reference.md 中的“编辑现有复合场景（编辑模式）”一节。向现有场景添加 3D 模型时，切勿跳过此步骤。

规则：将模型设为玩家的子级时，根据物品类型选择方式

当 GltfContainer 实体需要跟随玩家（手持武器、瞄准准星、装饰背包、光环、火把）时，SDK7 提供三种机制，它们不可互换。对瞄准敏感的物品，默认设为 engine.CameraEntity 的子级——这是从 SDK6 迁移时最常见的错误。

• 对瞄准敏感的手持物品（枪、瞄准准星、手电筒——任何玩家应能通过转动视角来瞄准的物品）→ Transform.create(entity, { parent: engine.CameraEntity, position: ..., ... })。跟随相机的偏航角和俯仰角，因此物品会指向玩家视线所及之处。这相当于 SDK6 的 Attachable.FIRST_PERSON_CAMERA。这是手持游戏物品的推荐默认方式。
• 仅跟随偏航角／固定于身体的物品（不用于瞄准的手持盾牌、固定携带的火把、不用于瞄准的物品栏物品）→ Transform.create(entity, { parent: engine.PlayerEntity, position: ..., ... })。仅跟随双脚位置和身体偏航角——不跟随俯仰角，也不随动画移动。枪械不应默认使用此方式：以 PlayerEntity 为父级的武器会在玩家抬头瞄准时保持水平。
• 装饰物品（帽子、光环、背包、名牌、其他玩家也能看到的装饰火把）→ AvatarAttach.create(entity, { anchorPointId: AAPT_HEAD | AAPT_SPINE | AAPT_LEFT_HAND | ... })。跟随动画骨骼——物品会随待机晃动、行走循环和手势动作而移动。不用于瞄准（动画抖动会让对瞄准敏感的物品无法使用）。

用 AAPT_RIGHT_HAND 之类的骨骼锚点来设置枪械的位置，看起来是正确的（“把枪放在手里”），但手部骨骼会播放动画——枪械会逐帧抖动，无法瞄准。这是从 SDK6 的 Attachable.FIRST_PERSON_CAMERA 模式迁移时容易踩到的陷阱；SDK7 中正确的对应方式是 engine.CameraEntity，而不是 AvatarAttach，也不是 engine.PlayerEntity（后者无法跟随俯仰角）。

完整对比和枪械示例请参见 [[player-avatar]]（手持物品与装饰物品）。SDK6 迁移背景请参见 [[migrate-sdk6-to-sdk7]]。

规则：始终检查动画

在完成任何带有 GltfContainer 的实体之前，请检查 GLB 是否包含动画。如果包含动画，务必添加 Animator 组件。否则引擎会静默地无限循环播放第一个片段。如果不包含动画，则省略 Animator。

规则：始终检查内置碰撞体

检查 GLB 是否包含 _collider 网格（网格或节点名称中包含 _collider）。请使用 {baseDir}/references/model-patterns.md 中的碰撞体检测脚本。

两种正确模式——选择一种，切勿混用

模型包含 _collider 网格：visibleMeshesCollisionMask: 0, invisibleMeshesCollisionMask: 3

模型不包含 _collider 网格：visibleMeshesCollisionMask: 3, invisibleMeshesCollisionMask: 0

根据用途选择掩码：

用途	visibleMeshesCollisionMask	原因
可交互（点击）	3	物理碰撞 + 指针检测
结构性 / 装饰性	3	阻挡行走 + 点击
仅可点击，无大量碰撞体	1	仅检测点击
纯装饰性	0	无交互

反面模式——切勿使用：visibleMeshesCollisionMask: 2, invisibleMeshesCollisionMask: 3——混用了两种模式，会导致指针检测失败。

规则：始终根据地块边界验证实体位置

完全位于场景地块之外的实体不会渲染——不会显示错误；跨越边界的模型仍会渲染位于地块内的部分。每个地块为 16x16 m。有效范围：0 <= x <= 16 * parcelsWide、0 <= z <= 16 * parcelsDeep、y >= 0。

裁剪针对的是几何体，而不是实体的位置。 即使 Transform 位于合法位置，也无法保留延伸到地块之外的几何体——地块外的部分会被静默裁剪，其余模型仍可见。因此，完全烘焙在地块外的网格会彻底消失。不要依赖 Creator Hub 的 entitiesOutOfBoundaries 来检测：在 Bevy 渲染器下，它是一个空桩。症状及探测流程请参阅上面的世界坐标规则。

在 TypeScript 中加载 3D 模型（仅限动态实体）

对运行时生成的实体，使用 GltfContainer.create(entity, { src: 'assets/Models/myModel.glb' })。将文件放在 assets/Models/ 中。

资源文件夹约定

• 默认：自行下载的模型放在 assets/Models/。
• 旧版场景可能已将模型放在 assets/scene/Models/ 下——该路径仍然有效；这些场景中的新模型也应沿用此路径，而不是另建一个 assets/Models/ 文件夹。
• Creator Hub 资源：通过 Creator Hub UI 直接导入的模型会放在 assets/Models/ 中（与标准路径相同）。免费 DCL 资源包中的项目会放在 assets/asset-packs/ 中，自定义项目则会放在 assets/custom/ 中。较旧的场景也可能将用户导入的资源直接放在 assets/scene/ 下。按原路径引用这些资源——切勿移动或重命名。

决定新模型的存放位置前，务必先检查场景中已有的文件夹。

在 Creator Hub 中打开场景时，将资源从“本地资源”选项卡拖到视口是用户最快捷的操作方式。 .glb / .gltf 会像以往一样作为普通模型拖入。自 creator-hub 062ed0a2 起，媒体文件会作为目录智能项拖入，而非独立组件：.png / .jpg / .jpeg 会生成 图像 项，其 Material PBR 纹理的 src 会重新指向该文件，平面会抬高 +0.5 m 以便立于地面；.mp3 / .mp4 会生成对应的项目（参见 音视频）。对于平面图像，建议直接拖入，而不是手动组装平面和 Material；完整表格和资源 ID 请参阅 creator-hub-mcp。

规则：新增模型——在 Blender 中提供目录模型和自定义创作

当用户要求添加模型时，有两个来源可选，选择权在用户手中——请先询问，再做选择：

“我可以从免费目录下载最匹配的模型（8,800 多个 OpenDCL 模型，加上 Creator Hub 资源包），也可以在 Blender 中为你创建自定义模型。你更倾向哪一种？”

• 目录 → 使用下一节中的工作流（搜索 → 检查 → 下载）。
• Blender → 通过操作 Blender 来创作模型；两种操作方式、设置、建模规则和导出方法的完整指南见 {baseDir}/references/blender-authoring.md，现成的 bpy 脚本见 {baseDir}/references/blender-patterns.md。Blender 也适用于编辑现有场景模型，例如重新贴图、调整形状和优化，不仅仅用于创建新模型。

作为子 Agent 运行时，你无法提问——请向调用方说明选项并给出建议，而不是自行决定。

为 avatar 制作动画（自定义表情动作）也使用这两种 Blender 路径，但需使用官方 Decentraland avatar 骨架和另一套导出流程——请参阅 avatar-animations 技能。本技能仅涵盖模型和道具。

操作 Blender 的两种方式

	无界面 CLI（blender --background --python）	Blender MCP
额外安装项	无——只需 Blender 本身	Blender 5.1+、MCP 插件、uv 和服务包、客户端注册、重启会话
可用性	安装了 Blender 的任何会话	仅限会话启动时已绑定 mcp__blender__* 工具的情况
交互模式	批处理：每次运行一个脚本，运行之间状态会重置	实时：在运行中的 Blender 中逐步编辑，状态会保留
视觉验证	将渲染的静帧写入磁盘（使用临时相机）	查看真实视口的屏幕截图
用户参与	只能看到结果	可以观看，也可以在打开的 Blender GUI 中共同编辑
最适用于	格式转换、减面、批量优化、脚本化模型构建	迭代建模会话、处理用户已打开的文件

规则：绝不静默切换到无界面模式

每当任务需要在 Blender 中创建或编辑模型，且有可能使用 MCP 时，请根据会话所处的以下三种状态之一进行选择：

1. MCP 已连接且正常工作——只读探测（get_objects_summary 或等效操作）有响应 → 使用 MCP。 无需询问。

2. MCP 已配置但尚未连接——会话中存在 mcp__blender__* 工具，但探测报错（Blender 未运行、插件已禁用，或桥接服务已停止）→ 切换到无界面模式前先询问：

   “Blender MCP 已配置，但 Blender 尚未运行。你想打开 Blender，让我在其中实时操作吗？你可以看到模型的构建过程，也可以和我一起编辑；或者我也可以改用无界面模式。”

   用户不介意打开 Blender，并且可能想一起处理模型。只有用户明确同意，或你确实无法提问（完全非交互场景——作为子 Agent 运行时，请将待选事项报告给调用方，而不是自行决定），才能切换到无界面模式。

3. 完全未安装 MCP——会话中没有 mcp__blender__* 工具 → 不要要求用户安装（这需要大量配置工作）。改用无界面模式，但请在报告中说明，Blender MCP 可用于实时交互式模型编辑，设置步骤见 {baseDir}/references/blender-authoring.md。

原因： MCP 能让模型工作变成协作过程——用户可以在自己的 Blender 会话中观看并迭代修改模型。静默切换到无界面模式会剥夺用户的选择权。

务必说明当前使用的是哪种路径；绝不要让用户误以为 CLI 完成的工作是 MCP 完成的，或反之。两种路径的建模规则（低多边形、PBR、调色板纹理、裸露碰撞体、场景限制）完全相同。

免费 3D 模型——两个目录

始终先检查场景的本地资源文件夹。获取任何模型前，先向用户确认。使用一次 grep 搜索两个目录——grep -i "keyword" {baseDir}/references/asset-pack-catalog.md {baseDir}/references/model-catalog.md——如果没有匹配项，再尝试同义词。使用任一文件中的 grep "^##" 浏览分类。每一行都有一个 preview: 图片 URL；导入前先获取图片并检查模型外观。

OpenDCL 目录（8,800 多个模型）——{baseDir}/references/model-catalog.md。单文件 GLB。工作流：搜索 → 查看尺寸／三角面数量／动画 → 使用 curl 下载到 assets/Models/ → 在代码中引用 → 如果模型带有动画，则添加 Animator。

Creator Hub 资源包——{baseDir}/references/asset-pack-catalog.md：最近添加的 420 个模型和 7 个 Smart Items（Genesis Plaza 和模板场景导入内容：建筑、街道设施、办公室／咖啡馆家具、自然景物、万圣节内容、科幻实验室套件、棋盘，以及脚本化按钮、门、活塞平台和水）。每个项目都包含一个 GLB 和外部纹理，因此请使用 {baseDir}/references/model-patterns.md 中的 dl-asset.mjs 辅助脚本（不要直接使用 curl），下载到 assets/asset-packs/<folder>/；每行都提供最终的 glb: 路径、用于碰撞体遮罩的 col: 标志，以及在 Creator Hub 中场景已打开时 place_smart_item 所需的 id:（此时优先使用 MCP 路径）。资源包中较早添加的项目未离线编入目录：使用 search_catalog 进行实时搜索（creator-hub-mcp）。

重要：GltfContainer 仅适用于本地文件。务必先下载（OpenDCL 模型下载到 assets/Models/，资源包项目下载到 assets/asset-packs/<folder>/）。不要切换到 models 目录中——请在项目根目录运行 curl／辅助脚本。

故障排查

问题	原因	解决方案
模型不可见	文件路径错误	确认路径是相对于项目根目录的
模型不可见	位于场景边界之外	检查位置是否在每个地块的 0-16 范围内
模型部分被截断	这些部分位于地块之外（在边界处被裁切）	移动／缩放模型，使其边界适合场景范围
模型不可见	缩放值为 0 或非常小	检查 Transform.scale
模型已加载但外观不正确	Y-up 与 Z-up 不匹配	在 Blender 中使用 "Y Up" 重新导出
统计到三角面，但从所有视点都看不到渲染器	网格完全烘焙在地块之外（实体位置仍可能在地块内）	检查 GLB 在 DCL 坐标轴下的边界；参见上文的世界坐标规则
"FINISHED_WITH_ERROR"	.glb 已损坏	重新导出为 .glb（二进制 GLTF）
点击无反应	未设置 CL_POINTER	如果没有 _collider 网格，则设置 visibleMeshesCollisionMask: 3
点击穿过墙壁	可见网格上未设置 CL_POINTER	设置 visibleMeshesCollisionMask: 3（或至少设置为 1）
灯具不发光	GLB 灯光几何体仅用于视觉呈现	为实体添加 LightSource 组件（参见 lighting-environment）

规则：3D 模型灯具不会发出真实光线

GLB 中的灯具网格、灯泡形状、吊灯臂及其他灯具几何体纯粹用于装饰——不会向周围物体投射动态光线。Decentraland 渲染器会将它们视为普通几何体（可使用自发光材质实现自发光效果）。若要让灯具模型产生实际照明，请在同一实体或位于光源位置的子实体上添加 LightSource 组件。如果 Creator Hub MCP 可用，优先使用 search_catalog 搜索 Smart Item 灯具（例如 lights 类别中的 Spotlight 或 Point Light），它会将模型、LightSource 和切换操作打包在一起——详情请参阅 lighting-environment。

模型最佳实践

• 每个文件中的模型应小于 50MB，以获得良好的加载速度
• 使用 .glb 格式（二进制 GLTF）——比 .gltf 更小
• 优化三角形数量：小型道具的每个模型尽量控制在 1,500 个三角形以内
• 尽可能使用纹理图集来减少绘制调用
• 模型中的材质应使用 PBR，以获得最佳效果
• 对于重复内容（路灯、椅子、树木），让多个实体引用同一个共享 .glb，而不是为每个副本导出几乎相同的文件——引擎会在整个会话期间只下载、转换并存储一次共享源文件的网格和纹理。这不会减少绘制调用或材质数量——两者都与渲染对象数量相关；关于何时应改为合并网格，请参阅 optimize-scene → 重复模型。
• ⚠️ 如果场景面向移动设备，请勿使用 Draco 压缩。 移动应用没有运行时 Draco 解码器。Draco 压缩的 GLTF/GLB 只有在场景的优化资源中才能在手机上加载（由服务器端解压）；如果没有优化资源——包括任何本地或 Creator Hub 移动预览——就会静默加载失败：模型会直接消失，不会出现控制台错误或占位符。因此，模型可能在已发布的场景中正常显示，却在该场景的所有移动预览中不可见，仅凭预览几乎无法排查这一问题。请导出未压缩的模型，并改为减少三角形数量或纹理大小。（文档提交 5f212e3，2026 年 10 月；错误对话框已在 godot-explorer #2432 中跟踪。请注意，下方的引擎场景 54,-55-Testing-3d-models 包含 Draco 变体——这是桌面端能力测试，并非跨平台建议。）

完整代码示例（加载、碰撞体、操作、目录工作流）请参阅 {baseDir}/references/model-patterns.md。资源目录请参阅 {baseDir}/references/model-catalog.md（8,800 多个 OpenDCL 模型）和 {baseDir}/references/asset-pack-catalog.md（Creator Hub 资源包，含最新新增内容）。

示例场景

引擎团队的测试场景，用于在真实运行时中测试这些 API：

• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/54,-55-Testing-3d-models — 通过 GltfContainer 加载多种 GLB 变体（Draco、形态目标、绑定骨骼的动画、外部依赖模型）；请注意，它使用 models/ 文件夹，而不是 assets/Models/。
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/3,33-gltf-container-update — 通过 GltfContainer.getMutable() 替换实时模型的 src 并修改 visibleMeshesCollisionMask（点击后在书本与怪物之间切换；使用 CL_CUSTOM1 进行射线检测）。
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-12-asset-load — 使用 AssetLoad 组件和各资源的加载状态回调预加载 GLB、音频、纹理和视频；还会在点击时通过 GltfContainer.getOrCreateMutable() 延迟生成模型。