SuperAPI AI 工具集

add-3d-models

通用与其它

查看项目

更新于 10-16 05:05

技能介绍

本技能用于在 Decentraland 场景中添加 3D 模型(.glb/.gltf),核心组件为 GltfContainer,可使用 OpenDCL 目录中的免费资产,也支持自制与编辑模型。

主要能力与用法:场景加载时即存在的模型应写入 assets/scene/main.composite,而非 TypeScript;只有运行时动态生成的模型才在代码中用 GltfContainer.create(entity, { src: 'assets/Models/myModel.glb' }) 创建,文件默认放在 assets/Models/(旧场景若已有 assets/scene/Models/ 则沿用该路径)。场景在 Creator Hub 中打开且其 MCP 工具可用时,可通过 search_catalog + place_smart_item 或 create_entity + set_component 添加模型,本技能的包围盒、碰撞掩码、Animator 规则同样适用。

关键规则:放置前必须确定模型真实世界空间包围盒(原始 accessor 的 min/max 不够,需计入节点变换),并据此计算安全放置区;几何体若已烘焙进世界坐标,需先导出非对称探针模型验证 DCL 轴向,因为边界裁剪只移除落在包裹之外的几何部分,且 Bevy 渲染器下 entitiesOutOfBoundaries 恒为空数组,无法告警。相邻实体需检查各自 origin±extent 是否相交,注意深拱门/门洞模型(±Z 可延伸 14 m)与旋转 90° 时 X、Z 范围互换。

室内设计应放大:默认第三人称相机下,天花板建议 5–6 m、主通道门洞约 4 m 高且 ≥3 m 宽、走廊 4 m+,手持尺度道具保持接近真人比例;应以第三人称相机在场景内截图判断,而非编辑视口。

单面模型(背面剔除)需将渲染面朝向玩家,通常朝本地 -Z,Y 旋转 0°/90°/180°/270° 分别对应南/东/北/西;两侧可见时复制一份旋转 180°。Decentraland 为 Y-up,Blender 导出的 Z-up 模型需以“Y Up”重新导出。文字标签(TextShape)会被实体几何遮挡,需在水平 2 m 内无实体、留出高度并配合 Billboard(billboardMode: 2)。

碰撞掩码二选一,不可混用:有 _collider 网格用 visibleMeshesCollisionMask: 0、invisibleMeshesCollisionMask: 0/3;无 _collider 网格用 3/0。不要使用 2 与 3 的组合。含动画的 GLB 必须加 Animator,否则会静默循环第一段动画;无动画则省略。

更换模型 src 必须重新审核 Transform:重新计算包围盒、缩放与枢轴,并核对世界空间包围盒是否落在场景范围内(每个地块 16×16 m,高度上限 330 m)。运行时可直接改 GltfContainer.getMutable(entity).src 触发同实体重载。手改已含 inspector::Nodes 的 composite 时,新实体必须同时注册 core-schema::Name 与 inspector::TransformConfig,否则在 Creator Hub 实体树中不可见。

模型跟随玩家按类型选择:瞄准类手持物用 engine.CameraEntity,仅偏航/身体固定物用 engine.PlayerEntity,装饰物用 AvatarAttach 骨骼锚点;把枪挂在 AAPT_RIGHT_HAND 会因骨骼动画抖动而无法瞄准。

限制与缺失:资料未提供具体价格、收费方式、支持平台与效果数据;部分参考文件路径(如 {baseDir}/references/model-patterns.md)仍需在实际环境中确认。