Datos en tiempo de ejecución

Obtén datos del contexto en el que se ejecuta tu escena y de la propia escena.

Obtener la hora de Decentraland

Decentraland sigue un ciclo de día/noche que tarda 2 horas en completarse, por lo que hay 12 ciclos completos cada día. Los jugadores también pueden cambiar la configuración para experimentar una hora fija específica del día, por ejemplo, ver siempre Decentraland con un cielo nocturno de las 10 p. m. Por esta razón, la hora de Decentraland puede variar de un jugador a otro.

Usa getWorldTime() para obtener la hora del día que el jugador está experimentando dentro de Decentraland.

import { getWorldTime } from '~system/Runtime'

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

💡 Consejo: El getWorldTime() la función es asíncrona. Consulta Funciones asíncronas si no estás familiarizado con ellas.

getWorldTime() devuelve un objeto con una seconds propiedad. Esta propiedad indica cuántos segundos han pasado (en el tiempo de Decentraland) desde el inicio del día, suponiendo que el ciclo completo dura 24 horas. Divide el valor de los segundos entre 60 para obtener los minutos, y de nuevo entre 60 para obtener las horas transcurridas desde el inicio del día. Por ejemplo, si el seconds valor es 36000, corresponde a 10 a. m..

En el tiempo de Decentraland, el sol siempre sale a las 6:15 y se pone a las 19:50.

Podrías usar esta información para cambiar la escena en consecuencia, por ejemplo para reproducir sonidos de pájaros cuando hay luz del día y grillos cuando está oscuro, o para activar los materiales emisivos en las farolas cuando está oscuro.

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) {
    // noche
    console.log('reproduciendo sonidos de grillos')
  } else {
    // día
    console.log('reproduciendo sonidos de pájaros')
  }
})

Obtener datos del realm

Los jugadores en Decentraland existen en varios realms. Los jugadores en distintos realms no pueden verse, interactuar ni chatear entre sí, incluso si están de pie sobre los mismos parcels. Dividir así a los jugadores permite que Decentraland gestione una cantidad ilimitada de jugadores sin encontrarse con limitaciones. También empareja a los jugadores que están en regiones cercanas, para asegurar que los tiempos de ping entre los jugadores que interactúan sean aceptables.

Si tu escena envía datos a un servidor de terceros para sincronizar cambios entre jugadores en tiempo real, entonces suele ser importante que los cambios solo se sincronicen entre jugadores que estén en el mismo realm. Debes tratar todos los cambios que pertenecen a un realm como algo separado de los de otro realm distinto. De lo contrario, los jugadores verán que las cosas cambian de una manera extraña, sin que nadie haya hecho el cambio.

import { getRealm } from '~system/Runtime'

executeTask(async () => {
  const { realmInfo } = await getRealm({})
  if (!realmInfo) return
  console.log(`Estás en el realm: `, realmInfo.realmName)
})

💡 Consejo: El getRealm() la función es asíncrona. Consulta Funciones asíncronas si no estás familiarizado con ellas.

Decentraland gestiona sus comunicaciones entre jugadores (incluidas las posiciones de los jugadores, el chat, los mensajes de messageBus y los cambios de estado de los smart items) a través de una red descentralizada de servidores de comunicación, y cada uno de estos servidores se llama un Realm. Cada uno de estos servidores puede dar soporte a múltiples salas (también llamadas islas), cada una agrupando un conjunto diferente de jugadores que están cerca entre sí en el mapa de Decentraland.

La getRealm() La función devuelve la siguiente información:

• baseUrl: (string) El dominio del servidor del realm

• realmName: (string) El nombre del servidor del realm

• networkId: (number) La red de Ethereum

• commsAdapter: (string) Adaptador de comunicaciones, eliminando todos los parámetros de consulta (credenciales)

• isPreview: (boolean) True si la escena se está ejecutando como una vista previa local, en lugar de estar publicada en Decentraland.

• isConnectedSceneRoom: (boolean) True si el usuario está conectado a la sala de la escena.

📔 Nota: El layer la propiedad está obsoleta y debería evitarse.

A medida que los jugadores se mueven por el mapa, pueden cambiar de sala para agruparse con aquellos jugadores que ahora están más cerca de ellos. Las salas también desplazan sus bordes dinámicamente para ajustarse a un grupo manejable de personas, así que incluso si un jugador se queda quieto, a medida que los jugadores entran y salen del world, el jugador podría encontrarse en otra sala. Los jugadores en la misma sala se comunican y compartirán mensajes a través de MessageBus incluso si están demasiado lejos para verse entre sí. Los jugadores en el mismo servidor pero en distintas salas no se están comunicando actualmente, pero podrían empezar a comunicarse a medida que se mueven por el mapa y cambian de sala.

Para reaccionar a cambios relacionados con el realm o la sala del jugador, usa la onChange función en el RealmInfo componente, que el engine añade a engine.RootEntity. Este componente contiene los mismos campos que devuelve getRealm().

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

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

📔 Nota: Cuando la escena se carga por primera vez, puede que todavía no se haya asignado una sala al jugador. El Explorer terminará asignando una sala al jugador, pero a veces esto puede ocurrir un par de segundos después de que la escena se haya cargado.

Obtener la plataforma del jugador

Los jugadores pueden acceder a Decentraland a través de varias plataformas, incluida la aplicación oficial de escritorio, y las versiones web y de escritorio obsoletas, así como clientes experimentales alternativos construidos para otros engines.

Usa getExplorerInformation() para saber en qué plataforma está ejecutando Decentraland el jugador actual.

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

executeTask(async () => {
  let data = await getExplorerInformation({})
  console.log("PLATFORM: ", data.platform, " AGENT: ", data.agent)
})

Cuando se usa la aplicación oficial de escritorio de Decentraland, esta función debería devolver los siguientes datos:

{
    agent: unity-explorer,
    platform: desktop
}

Es probable que los jugadores que usan la aplicación oficial de escritorio de Decentraland tengan una experiencia mucho más fluida que los del navegador, ya que el navegador impone limitaciones de rendimiento sobre cuánta potencia de procesamiento de la máquina puede usar la pestaña del navegador. También les faltarán muchas funciones como el control de la cámara, luces dinámicas, congelar el movimiento del jugador, mejoras de UI, etc.

El componente EngineInfo

La EngineInfocomponente lleva un registro de los datos sobre el ciclo de vida de la escena, lo que a veces puede ser útil para saber cuándo está ocurriendo un evento, en relación con la inicialización de la escena.

Este componente se añade a 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--------------'
  )
})

Puedes usar sceneHidden para pausar el trabajo que consume muchos recursos mientras la escena no es visible:

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

  // La lógica normal del juego solo se ejecuta cuando la escena es visible
})

La EngineInfo componente contiene los siguientes datos:

• frameNumber: Contador de fotogramas del engine.

• totalRuntime: Tiempo total de ejecución de esta escena, en segundos.

• tickNumber: Contador de ticks de la escena según ADR-148.

• sceneHidden: true cuando la escena está oculta detrás de la UI de pantalla completa del Explorer (por ejemplo, una pantalla de carga o un menú de pantalla completa). Usa esto para pausar la jugabilidad, el audio o las animaciones mientras el jugador no pueda ver la escena ni interactuar con ella.

📔 Nota: El EngineInfo El componente debe importarse mediante

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

Ver Importaciones para saber cómo manejarlos fácilmente.

Reaccionar a la desaparición de la pantalla de carga

La scene_hidden el campo te indica si el jugador realmente puede ver tu escena, o si está cubierta por la UI de pantalla completa del Explorer. Mientras la pantalla de carga está activa, sceneHidden es trueen el momento en que la pantalla de carga desaparece y el jugador ve por primera vez el mundo, pasa a false.

Esta es la única manera de que una escena sepa cuándo ocurre esa primera revelación. Úsalo para retener cualquier cosa que, de otro modo, se desarrollaría detrás de la pantalla de carga y el jugador se perdería: cinemáticas de introducción, sonidos de bienvenida, un tween que solo funciona bien si se observa, una UI de apertura o un evento de analíticas que solo debería contarse cuando el jugador esté realmente allí.

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

function onSceneRevealed() {
  // Ahora el jugador está mirando la escena, inicia aquí la introducción
  console.log('La pantalla de carga acaba de desaparecer')
}

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

  // Ejecutar solo una vez
  engine.removeSystem(waitForSceneRevealed)
  onSceneRevealed()
})

📔 Nota: Tu escena sigue ejecutándose normalmente mientras sceneHidden es true, solo que no se muestra. No uses este campo para pausar la lógica de tu escena; úsalo para sincronizar lo que el jugador debe presenciar.

scene_hidden requiere una @dcl/sdk actualizada y una versión reciente del Decentraland Explorer. En clientes antiguos, el campo se mantiene en su valor predeterminado de false, así que una escena que espere a eso sigue ejecutándose — simplemente no estará sincronizada con la desaparición de la pantalla de carga.