用途:汇总 Decentraland SDK7 场景中通用的运行时 API,适合处理异步、网络、计时、身份、场景信息与玩家交互类需求。
主要能力:
- 异步:场景为单线程,异步工作需用 executeTask()(来自 @dcl/sdk/ecs)包装,否则裸 Promise 会被静默丢弃。
- HTTP:公开 API 用普通 fetch;signedFetch 用于向自建后端证明玩家身份,签名请求体为字符串,需自行 JSON.parse(response.body)。getHeaders() 可只取签名头。外部 HTTP 的权限名为 USE_FETCH,WebSocket 为 USE_WEBSOCKET,声明在 scene.json 的 requiredPermissions;资料称预览/Worlds 中对非媒体主机的普通/签名 fetch 实际未被硬性拦截,但仍建议声明。signedFetch 不要求玩家先交互。
- WebSocket:可用全局 WebSocket 连接,处理 onopen/onmessage/onclose。
- 运行环境信息:从 ~system/Runtime 导入 getSceneInformation、getRealm、getExplorerInformation、getWorldTime、readFile,可读取场景 URN、metadataJson、realmName、isPreview、网络 id、世界时间及场景部署的配置文件。
- 引擎状态:EngineInfo 组件挂在 engine.RootEntity,字段有 frameNumber、tickNumber、totalRuntime、sceneHidden。sceneHidden 在加载界面遮挡时为 true,是判断玩家首次真正看到场景的唯一信号,可用它延迟开场动画、音效或分析事件。
- 系统优先级:engine.addSystem(fn, priority?, name?) 每帧运行;优先级数值越大越先执行,默认 100000,与 Unity/Godot 相反,不要依赖同优先级系统之间的顺序。
- 计时器:用 @dcl/sdk/ecs 的 timers.setTimeout/setInterval,不要用原生 JS 全局计时器;参数顺序为 (callback, ms)。
- 受限操作:来自 ~system/RestrictedActions,需玩家先交互,包括 movePlayerTo、teleportTo、triggerEmote、openExternalUrl、openNftDialog、copyToClipboard、openExplorerUi 等;changeRealm 已弃用,建议用 teleportTo({ realm })。teleportTo 的 realm 支持 World 名或 realm URL,会先弹出确认对话框,切换需 @dcl/sdk 7.28.0+。
- 其它:Transform.onChange() 监听组件变化;engine.removeEntity() 返回布尔值表示实体是否被接受释放。
限制:资料未提供收费、价格、平台支持范围等其它信息。