运行时数据

从场景运行所在的上下文以及场景本身获取数据。

获取 Decentraland 时间

Decentraland 遵循昼夜循环，完整完成一次需要 2 小时，因此每天共有 12 个完整循环。玩家也可以更改设置以体验某个固定的时刻，例如始终看到晚上 10 点的夜空版 Decentraland。因此，不同玩家看到的 Decentraland 时间可能不同。

使用 getWorldTime() 用于获取玩家在 Decentraland 中所处的时刻。

import { getWorldTime } from '~system/Runtime'

executeTask(async () => {
  let time = await getWorldTime({})
  console.log(time.seconds)
})

💡 提示：该 getWorldTime() 函数是异步的。参见异步函数如果你不熟悉这些。

getWorldTime() 会返回一个带有 seconds 属性表示自一天开始以来已经过去了多少秒（按 Decentraland 时间计算），假设完整循环持续 24 小时。将 seconds 值除以 60 可得到分钟，再除以 60 可得到自当天开始以来的小时数。例如，如果 seconds 值为 36000，则对应于 上午 10 点.

在 Decentraland 时间中，太阳总是在 6:15 升起，19:50 落下。

你可以利用这些信息相应地调整场景，例如在白天播放鸟叫声、在天黑时播放蟋蟀声，或者在天黑时打开路灯的自发光材质。

import { getWorldTime } from '~system/Runtime'

executeTask(async () => {
  let time = await getWorldTime({})
  console.log(time.seconds)
  if (time.seconds < 6.25 * 60 * 60 || time.seconds > 19.85 * 60 * 60) {
    // 夜间
    console.log('播放蟋蟀声')
  } else {
    // 白天
    console.log('播放鸟叫声')
  }
})

获取 Realm 数据

Decentraland 中的玩家分布在多个彼此分离的领域。不同 Realm 中的玩家无法互相看见、互动或聊天，即使他们站在同一地块上也不行。这样划分玩家使 Decentraland 能够处理无限数量的玩家而不会遇到任何限制。它还会将彼此接近区域中的玩家配对，以确保互动玩家之间的 ping 时间可接受。

如果你的场景向一个第三方服务器用于在玩家之间实时同步变化，那么通常很重要的是，这些变化只在同一 Realm 的玩家之间同步。你应将属于某个 Realm 的所有变化与属于其他 Realm 的变化分开处理。否则，玩家会看到事物以一种诡异的方式变化，而没人实际做出这些更改。

import { getRealm } from '~system/Runtime'

executeTask(async () => {
  const { realmInfo } = await getRealm({})
  if (!realmInfo) return
  console.log(`你所在的 realm: `, realmInfo.realmName)
})

💡 提示：该 getRealm() 函数是异步的。参见异步函数如果你不熟悉这些。

Decentraland 通过一个去中心化的通信服务器网络来处理玩家之间的通信（包括玩家位置、聊天、messageBus 消息以及智能物品状态更改），其中每一台服务器称为一个 Realm。这些服务器中的每一台都可以支持多个独立的房间（也称为岛屿），每个房间会将 Decentraland 地图上彼此接近的一组不同玩家分在一起。

该 getRealm() 函数返回以下信息：

baseUrl: （字符串） realm 服务器的域名
realmName: （字符串） realm 服务器的名称
networkId: （数字） 以太坊网络
commsAdapter: （字符串） 通信适配器，会移除所有查询参数（凭证）
isPreview: （布尔值） 如果场景作为本地预览运行，而不是发布在 Decentraland 中，则为 True。
isConnectedSceneRoom: （布尔值） 如果用户已连接到场景房间，则为 True。

📔 注意：该 layer 该属性已弃用，应避免使用。

随着玩家在地图中移动，他们可能会切换房间，以便与现在离他们最近的玩家分到一起。房间边界也会动态调整，以容纳一个可管理的人群，因此即使玩家站着不动，随着其他玩家进入和离开世界，该玩家也可能发现自己被分到了另一个房间。同一个 room 会进行通信，并且即使彼此远到看不见，也会通过 MessageBus 共享消息。同一服务器但处于不同房间的玩家目前不会通信，但随着他们在地图中移动并更换房间，他们可能会建立通信。

要响应与玩家的 realm 或房间相关的变化，请使用 onChange 在……上的函数 RealmInfo 组件，运行时会将其添加到 engine.RootEntity。该组件包含与 getRealm().

import { engine, RealmInfo } from '@dcl/sdk/ecs'

export function main() {
	RealmInfo.onChange(engine.RootEntity, (realmInfo) => {
		if (!realmInfo) return
		console.log('Realm 已更改：', realmInfo.realmName)
	})
}

📔 注意：当场景首次加载时，可能还没有为玩家分配房间。Explorer 最终会为玩家分配一个房间，但这有时会在场景加载后几秒钟才发生。

获取玩家平台

玩家可以通过各种平台访问 Decentraland，包括官方桌面应用、已弃用的网页和桌面版本，以及其他实验性客户端，以及为其他引擎构建的客户端。

使用 getExplorerInformation() 以了解当前玩家正在通过哪个平台运行 Decentraland。

import { getExplorerInformation } from '~system/Runtime';

executeTask(async () => {
  let data = await getExplorerInformation({})
  console.log("平台: ", data.platform, " 代理: ", data.agent)
})

使用官方 Decentraland 桌面应用时，此函数应返回以下数据：

{
    agent: unity-explorer,
    platform: desktop
}

使用官方 Decentraland 桌面应用的玩家通常会比浏览器中的玩家体验更流畅得多，因为浏览器会限制浏览器标签页可使用的机器处理能力。它们还会缺少许多功能，例如摄像机控制、动态光照、冻结玩家移动、UI 增强等。

EngineInfo 组件

该 EngineInfo组件会跟踪有关场景生命周期的数据，这有时可用于判断某个事件相对于场景初始化是在何时发生的。

该组件会被添加到 engine.RootEntity.

engine.addSystem((deltaTime) => {
  const engineInfo = EngineInfo.getOrNull(engine.RootEntity)
  if (!engineInfo) return

  console.log(
    '--------------' +
      '\nframeNumber: ' +
      engineInfo.frameNumber +
      '\ntickNumber: ' +
      engineInfo.tickNumber +
      '\ntotalRuntime: ' +
      engineInfo.totalRuntime +
      '\nsceneHidden: ' +
      engineInfo.sceneHidden +
      '\n--------------'
  )
})

你可以使用 sceneHidden 用于在场景不可见时暂停资源密集型工作：

engine.addSystem((deltaTime) => {
  const engineInfo = EngineInfo.getOrNull(engine.RootEntity)
  if (engineInfo?.sceneHidden) return

  // 正常的游戏逻辑仅在场景可见时运行
})

该 EngineInfo 组件包含以下数据：

frameNumber：引擎的帧计数器。
totalRuntime：该场景的总运行时间，单位为秒。
tickNumber：场景的 tick 计数器，依据 ADR-148.
sceneHidden: true 当场景被 Explorer 的全屏 UI 遮挡时。包括加载界面，以及地图、背包和设置菜单。可用它在玩家看不到场景时静音音频并暂停高负载工作。

📔 注意：该 EngineInfo 组件必须通过以下方式导入：

import { EngineInfo } from "@dcl/sdk/ecs"

参见导入，了解如何轻松处理这些内容。

响应加载界面淡出

该 scene_hidden 字段会告诉你玩家是否真的能看到你的场景，或者它是否被 Explorer 的全屏 UI 覆盖。在加载界面显示期间， sceneHidden 为 true。当加载界面淡出、玩家首次看到世界的那一刻，它会变为 false.

它会变为 true ，之后当全屏 Explorer UI 再次遮挡场景时也会如此，例如地图、背包或设置菜单。这使它成为静音的好时机音频并暂停耗资源的系统，然后在它恢复为 false.

这是场景得知首次露出发生的唯一方式。可用它来延后任何原本会在加载界面后方播放、从而被玩家错过的内容：开场过场动画、欢迎音效、只有被观看时才看得懂的 tween、开场 UI，或只应在玩家真正进入后才计数的分析事件。

import { engine, EngineInfo } from '@dcl/sdk/ecs'

function onSceneRevealed() {
  // 玩家现在正在看场景，在这里开始开场
  console.log('加载界面刚刚淡出')
}

engine.addSystem(function waitForSceneRevealed() {
  const engineInfo = EngineInfo.getOrNull(engine.RootEntity)
  if (!engineInfo || engineInfo.sceneHidden) return

  // 仅运行一次
  engine.removeSystem(waitForSceneRevealed)
  onSceneRevealed()
})

📔 注意：你的场景在 sceneHidden 为 true期间会继续正常运行，

scene_hidden 需要最新的 @dcl/sdk 以及较新版本的 Decentraland Explorer。对于旧客户端，该字段会保持其默认值 false，因此等待它的场景仍会运行——只是不会与加载界面的淡出同步。

上一页射线投射

下一页天空盒控制

最后更新于 2天前