用途:面向 Decentraland SDK7 场景开发,按需求选择渲染组件。实体需要面向相机时用 Billboard;三维世界中的文字用 TextShape(屏幕 UI 文字应改用 build-ui 的 React-ECS Label);自定义材质外观用 Material.setPbrMaterial;需要隐藏而不删除实体用 VisibilityComponent;覆盖 GLTF 模型特定网格节点材质或阴影用 GltfNodeModifiers。
主要能力:Billboard 支持 BM_Y(仅 Y 轴,最常用且开销更低)、BM_ALL、BM_X、BM_Z、BM_NONE 模式,可用 targetEntity 改为朝向指定实体;朝向相机的 Billboard 按玩家本地计算,targetEntity 则对所有玩家一致。无 oppositeDirection 开关,若模型背面朝相机,需绕 Y 轴旋转 180°。TextShape 支持 fontSize、textColor、outlineColor/outlineWidth、九种 TextAlignMode 对齐。PBR 材质支持 metallic、roughness、透明(MTM_ALPHA_BLEND 与更廉价的 MTM_ALPHA_TEST)、emissiveColor(Color3)与 emissiveIntensity、漫反射/法线/自发光贴图、castShadows。GltfContainer 可用 visibleMeshesCollisionMask 与 invisibleMeshesCollisionMask 控制碰撞层。VisibilityComponent 支持 propagateToChildren,子级自带组件时以自身值为准。GltfNodeModifiers 以 path 定位节点,支持 pbr/unlit 覆盖、视频纹理、逐节点关闭阴影,createOrReplace 更新、deleteFrom 移除;传入不存在的路径会在控制台输出完整节点层级以便排查。贴图支持 TFM_POINT/BILINEAR/TRILINEAR 过滤与 TWM_REPEAT/CLAMP/MIRROR 包裹,Avatar 纹理可获取玩家头像缩略图,FlatMaterial 提供 getFlat/getFlatOrNull/getFlatMutable/getFlatMutableOrNull 以绕过嵌套联合结构。
适用场景与限制:适用于名牌、标牌、悬浮标签、自发光或透明表面、LOD 切换、节点级材质覆盖等。限制:TextShape 不宜承载长段说明文字,建议每块标牌一个要点、不超过 10 个词;alpha test 比 alpha blend 更省;节点路径须为 GLB 中真实存在的名称,目标节点缺少对应材质类型时覆盖可能被忽略;targetEntity 指向的实体不存在或被删除时朝向会冻结在最后朝向。具体用法参见各 API 与测试场景示例。