用途:在 Decentraland 场景中实现多人同步。场景默认各玩家独立交互,环境变化不会共享,需借助 SDK7 的 CRDT 同步机制。
主要能力与选型:syncEntity 用于所有玩家(含后加入者)都需看到的共享状态,如门、开关、记分板、电梯;状态在场景内至少有一名玩家时保留,场景清空即重置。MessageBus 用于瞬时事件,如聊天、音效、粒子触发,后加入者收不到历史消息。fetch/REST 用于外部服务器读写;signedFetch 附带钱包身份证明;WebSocket 用于与服务端的实时双向通信。可组合使用。
用法要点:syncEntity(entity, componentIds[], syncId?),预定义单例实体应使用枚举分配稳定 syncId,玩家动态创建的实体可省略。自定义组件用 engine.defineComponent 与 Schemas 定义,时间戳等大数用 Schemas.Int64。父子同步关系用 parentEntity() 而非 Transform.parent。用 isStateSyncronized()(注意 SDK 拼写)等待同步就绪。MessageBus 通过 on/emit 收发;高频或大负载可用 sendBinary 发送 Uint8Array。网络调用须放在 executeTask 内。
限制:运行在 QuickJS 沙箱,无 Node.js API(fs、http、path、process),用 fetch 与 WebSocket。CRDT 为最后写入胜出。MessageBus 在权威服务器场景不可用,需在客户端分支构造。远程玩家 Transform 为世界坐标,本地为场景坐标,比较时需减去 basePos * 16。AvatarNametag 等为客户端本地,不会自动共享。固定 ID 实体不可在同一帧删除后重建。