用途:在 Decentraland 场景里创建非玩家角色(NPC),按需求选择两种方案。
方案一:NPC Toolkit(基于 GLB)。适用于需要 GLB 模型、对话、行走和状态机行为的 NPC。安装:npm i dcl-npc-toolkit。基本用法为从 'dcl-npc-toolkit' 静态导入,定义 dialogs 数组(如 [{ text: 'Hello there!', isEndOfDialog: true }]),调用 npc.create(transform, { type、model、idleAnim、walkingAnim、hoverText、onlyExternalTrigger、onActivate }) 创建,在 onActivate 中调用 npc.talk(npcEntity, dialogs)。完整对话、移动路径、状态机与配置见参考文档 npc-library.mdc。
已知限制(Toolkit):按钮标签会被视觉截断(固定宽度约 217px、默认字号 16 时约 15 字符后无省略号直接裁掉),应使用“Yes”“No thanks”等短标签,或降低 fontSize/size;对非 create 创建的实体开对话需 addDialog 并设置最小 npcDataComponent;气泡需先 createDialogBubble;单独调用 createDialogWindow 需补设 npcDataComponent 否则报 theme 未定义;faceUser 为 true 时不要将固定世界对象作为其子实体,应改为不挂父级的计算世界坐标;Toolkit 必须在入口静态导入,因为其在模块加载期调用 engine.defineComponent,动态 await import 会因引擎已封闭而报错。
方案二:AvatarShape。适用于需要呈现 Decentraland 化身外观的 NPC。使用 AvatarShape.create,需提供必填唯一 id、name(置空字符串可隐藏名牌)、bodyShape(BaseMale/BaseFemale)、wearables、hairColor、skinColor。必须包含 eyebrows、mouth、eyes 否则不渲染面部。修改 Transform 位置会让其行走而非瞬移;可用 Tween/TweenSequence 规划路径,持续追踪用 Tween.setMoveContinuous。用 expressionTriggerId + expressionTriggerTimestamp 播放表情,可为内置表情名或场景表情 .glb 路径。showOnlyWareables(原文 showOnlyWearables)为 true 时用于展示可穿戴物的模特模式。克隆玩家外观可读取 getPlayer() 的 wearables/emotes,但首帧可能为空需轮询。
交互:AvatarShape 实体无碰撞体、不可直接点击。可为同一实体添加 MeshCollider(如 MeshCollider.setCylinder)后用 pointerEventsSystem.onPointerDown;或写系统按玩家与 NPC 距离触发交互。示例场景包括 4,20、4,19、4,21、4,22。官方文本未提供,部分字段细节需查阅所引用参考文档。