Funciones obsoletas

Funciones heredadas

Las siguientes funciones son todas legacy y deben evitarse. Todavía funcionan, pero en el futuro podrían dejar de ser compatibles. Todos estos ejemplos incluyen enlaces a formas alternativas de obtener la misma información o lograr los mismos resultados.

El jugador entra o sale de la escena

📔 Nota: La onEnterSceneObservable y onLeaveSceneObservable los events están obsoletos en SDK 7.x. Usa onEnterScene en su lugar, consulta El jugador entra o sale de la escena.

Cada vez que un avatar entra o sale de los parcels de land que componen tu scene, o hace teleport hacia dentro o fuera, esto crea un event que puedes escuchar. Este event se activa con todos los avatars, incluido el del player.

import {
	onEnterSceneObservable,
	onLeaveSceneObservable,
} from '@dcl/sdk/observables'

onEnterSceneObservable.add((player) => {
	console.log('player entered scene: ', player.userId)
})

onLeaveSceneObservable.add((player) => {
	console.log('player left scene: ', player.userId)
})

📔 Nota: Este event solo responde a los players que actualmente se están renderizando localmente. En scenes grandes donde el tamaño de la scene supera el rango visual, los players que entren por la esquina opuesta podrían no registrarse. Si el número de players en la región supera las capacidades de una isla en los servers de Decentraland, los players que no compartan la misma island no son visibles y tampoco son rastreados por estos events.

Las observables onEnterScene y onLeaveScene importadas desde '@dcl/sdk/observables' también están obsoletas. Las funciones correctas tienen el mismo nombre, pero se importan desde '@dcl/sdk/src/players' en su lugar. En el ejemplo de abajo puedes ver ambas variantes, primero la versión obsoleta y luego la correcta.

// OBSOLETO - importado desde observables
import { onEnterScene, onLeaveScene } from '@dcl/sdk/observables'

onEnterScene.add((player) => {
	console.log('player entered scene: ', player.userId)
})

onLeaveScene.add((player) => {
	console.log('player left scene: ', player.userId)
})

// ACTUAL - importado como una función de player
import { onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

export function main() {
	onEnterScene((player) => {
		if (!player) return
		console.log('ENTRÓ EN LA ESCENA', player)
	})

	onLeaveScene((userId) => {
		if (!userId) return
		console.log('SALIÓ DE LA ESCENA', userId)
	})
}

Player se conecta o desconecta

📔 Nota: La getConnectedPlayers function y la onPlayerConnectedObservable y onPlayerDisconnectedObservable los events están obsoletos en SDK 7.x. Usa onEnterScene en su lugar, consulta El jugador entra o sale de la escena. Ahora cada scene es una island de comunicaciones distinta, lo que hace que estar conectado o estar en la misma scene sea lo mismo.

Obtén la lista completa de players actualmente conectados desde getConnectedPlayers.

import { getConnectedPlayers } from '~system/Players'

executeTask(async () => {
	let connectedPlayers = await getConnectedPlayers({})
	connectedPlayers.players.forEach((player) => {
		console.log('player was already here: ', player.userId)
	})
})

Cada vez que otro player empieza o deja de renderizarse por el engine local, esto crea un event que puedes escuchar. Los players pueden o no estar en la misma scene que tú, pero deben estar dentro del rango visual (no necesariamente a la vista). La onPlayerConnectedObservable detecta tanto cuando un player se conecta cerca por primera vez como cuando se acerca lo suficiente para estar en rango visual, del mismo modo la onPlayerDisconnectedObservable detecta cuando un player termina su sesión o se aleja demasiado.

import {
	onPlayerConnectedObservable,
	onPlayerDisconnectedObservable,
} from '@dcl/sdk/observables'

onPlayerConnectedObservable.add((player) => {
	console.log('player entered: ', player.userId)
})

onPlayerDisconnectedObservable.add((player) => {
	console.log('player left: ', player.userId)
})

Ten en cuenta que, si otros players ya se están renderizando en los alrededores antes de que el player cargue tu scene, este event no notificará a la scene recién cargada sobre los players que ya existían. Si necesitas hacer seguimiento de todos los players actuales, puedes consultar los players existentes al cargar la scene y luego escuchar este event para recibir actualizaciones.

Consultar todos los jugadores en la escena

📔 Nota: La getPlayersInScene function está obsoleta en SDK 7.x. En su lugar, itera sobre todos los players con un PlayerIdentityData component. Consulta Obtener todos los players.

También puedes obtener la lista completa de players que actualmente están en tu scene y se están renderizando llamando a getPlayersInScene().

import { getPlayersInScene } from '~system/Players'

executeTask(async () => {
	let connectedPlayers = await getPlayersInScene({})
	connectedPlayers.players.forEach((player) => {
		console.log('player was already here: ', player.userId)
	})
})

El jugador reproduce una animación

📔 Nota: La onPlayerExpressionObservable event está obsoleto en SDK 7.x. Usa el AvatarEmoteCommand component en su lugar, consulta El jugador reproduce una animación.

Cada vez que el player ejecuta un emote (baile, aplauso, saludo, etc.), puedes detectar este event.

import { onPlayerExpressionObservable } from '@dcl/sdk/observables'

onPlayerExpressionObservable.add(({ expressionId }) => {
	console.log('Expression: ', expressionId)
})

El evento incluye la siguiente información:

• expressionId: Nombre del emote realizado (es decir: wave, clap, kiss)

📔 Nota: Este event se activa cada vez que el player hace un emote y la scene está cargada. El player podría estar de pie en una scene cercana cuando esto ocurre.

El jugador cambia de perfil

📔 Nota: La onProfileChanged event está obsoleto en SDK 7.x. Usa el AvatarEquippedData component en su lugar, consulta El jugador cambia de perfil.

Cada vez que el player hace un cambio en su perfil, se llama al onProfileChanged event. Estos cambios pueden incluir ponerse diferentes wearables, cambiar el nombre, la descripción, activar experiencias portátiles, etc.

import { onProfileChanged } from '@dcl/sdk/observables'

onProfileChanged.add((profileData) => {
	console.log('Own profile data is ', profileData)
})

Los datos del event incluyen solo el ID del player y un número de versión para el perfil de ese avatar, según el catalyst server. Cada vez que se propaga un cambio, el número de versión aumenta en 1.

Cuando se activa este event, puedes usar la getUserData() function para obtener la versión más reciente de esta información, incluida la lista de wearables que lleva el player. Puede que necesites añadir un pequeño retraso antes de llamar a getUserData() para asegurarte de que la versión que devuelve esta function esté actualizada.

💡 Consejo: Al probar en preview con el legacy web explorer, para evitar usar un avatar aleatorio, ejecuta la scene en el navegador conectado con tu wallet de Metamask.

📔 Nota: Este event solo se activa por cambios en el player actual, no por cambios en los perfiles de otros players cercanos.

Scene finished loading

📔 Nota: La onSceneReadyObservable event está obsoleto desde SDK v7.x. Esta function ya no es relevante. Puedes asegurarte de que algo se ejecute después de que la scene termine de cargar ejecutándolo dentro de la Main() function. Consulta Ciclo de vida de la scene

Cuando la scene termina de cargar, se llama a onSceneReadyObservable . Esto funciona tanto si el player entra directamente en la scene como si camina hasta ella desde otro lugar. Cuando todo el contenido de la scene ha terminado su carga inicial, incluidos los modelos pesados, etc., se llama a este event.

import { onSceneReadyObservable } from '@dcl/sdk/observables'

onSceneReadyObservable.add(() => {
	console.log('SCENE LOADED')
})

Métodos obsoletos de datos del player

📔 Nota: La getUserData() y getPlayerData() functions están obsoletas desde SDK v7.4.x. Usa getPlayer() en su lugar. Consulta Datos del usuario.

Para obtener información del player actual que está ejecutando la scene, usa getUserData().

El ejemplo de abajo importa el ~system/UserIdentity namespace y ejecuta getUserData().

import { getUserData } from '~system/UserIdentity'

executeTask(async () => {
	let userData = await getUserData({})
	console.log(userData.data)
})

Puedes obtener datos de otros players cercanos llamando a getPlayerData(), pasando el id de una cuenta de Decentraland.

import { getPlayerData } from '~system/Players'

executeTask(async () => {
	let userData = await getPlayerData({ userId: '0x….' })
	console.log(userData)
})

Ambas getUserData() y getPlayerData() devuelven la misma estructura de datos disponible a través de la content API. Consulta Datos de cualquier player

getPlayerData() solo puede obtener datos de players que estén actualmente cerca. No tienen que estar necesariamente en la misma scene, pero sí dentro del rango visual; esto se debe a que esta información se obtiene del engine local que está renderizando estos avatars. Para probarlo en preview, abre una segunda pestaña e inicia sesión con una cuenta diferente.

📔 Nota: Los IDs de usuario siempre deben estar en minúsculas. Si copias una dirección de wallet, asegúrate de que todos los caracteres estén en minúsculas.

El getUserPublicKey() y getUserAccount() functions también están obsoletas. Por favor usa getPlayer() en su lugar. Consulta Datos del usuario.

Obtener hora de skybox

📔 Nota: La getDecentralandTime() function está obsoleta desde SDK v7.x.x. Usa getWorldTime() en su lugar. Consulta Obtener hora de Decentraland.

import { getDecentralandTime } from '~system/EnvironmentApi'

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

Obtener realm

📔 Nota: La getCurrentRealm() function está obsoleta desde SDK v7.x.x. Usa getRealm() en su lugar. Consulta Obtener datos del Realm.

import { getCurrentRealm } from '@decentraland/EnvironmentAPI'

async function fetchPlayerData() {
	const playerRealm = await getCurrentRealm()

	console.log(playerRealm.domain)
}

fetchPlayerData()

Es modo preview

📔 Nota: La isPreviewMode() function está obsoleta desde SDK v7.x.x. Usa getRealm() en su lugar, que contiene una preview property. Consulta Obtener datos del Realm.

import { isPreviewMode } from '~system/EnvironmentAPI'

executeTask(async () => {
	const preview: boolean = await isPreviewMode({})

	if (preview) {
		console.log('Running in preview')
	}
})

Player hace clic en otro player

Cada vez que el player hace clic en otro player, puedes detectar un event.

import { onPlayerClickedObservable } from '@dcl/sdk/observables'

onPlayerClickedObservable.add((clickEvent) => {
	console.log('Clicked ', clickEvent.userId, ' details: ', clickEvent.ray)
})

📔 Nota: La onPlayerClickedObservable event está obsoleto desde SDK v7.x. Las versiones futuras permitirán un enfoque más orientado a datos, basado en consultar datos regularmente en lugar de usar events.

Como alternativa, puedes adjuntar un collider invisible al player y detectar clics contra él.

📔 Nota: Tanto el player que realiza el clic como el player al que se hace clic deben estar dentro de los parcels de la scene. Este listener solo detecta events del player actual haciendo clic en otros players, no los clics realizados por otros players.

El event incluye los siguientes datos:

• userId: El id del player sobre el que se hizo clic

• ray: Datos sobre el ray trazado por el clic

  • direction: Vector3 Un Vector3 normalizado que representa la dirección desde el punto de origen del clic hasta el punto de impacto del clic.

  • distance: number La distancia en metros desde el punto de origen hasta el punto de impacto.

  • origin: Vector3 El punto de origen del clic, la posición del player que hizo el clic, relativa a la scene.

💡 Consejo: El comportamiento predeterminado al hacer clic en otro player es abrir el passport del player, donde puedes ver información adicional sobre ese player, añadirlo como amigo, etc. Puedes desactivar la apertura de esta UI para que no interfiera con la experiencia que quieres construir añadiendo un Avatar Modifier Area.

Player bloquea/desbloquea el cursor

📔 Nota: La onPointerLockedStateChange event está obsoleto desde SDK v7.x. Consulta Event listeners para una alternativa no obsoleta.

Los jugadores pueden alternar entre dos modos de cursor: cursor bloqueado modo para controlar la cámara o cursor desbloqueado modo para mover el cursor libremente por la UI.

Los jugadores desbloquean el cursor haciendo click en el botón derecho del mouse o presionando la tecla Esc y vuelven a bloquear el cursor haciendo click en cualquier parte de la pantalla.

Este onPointerLockedStateChange event se activa cada vez que un player cambia entre estos dos modos, mientras está cerca de la scene.

import { onPointerLockedStateChange } from '@dcl/sdk/observables'

onPointerLockedStateChange.add(({ locked }) => {
	if (locked) {
		console.log('Pointer has been locked')
	} else {
		console.log('Pointer has been unlocked')
	}
})

📔 Nota: Este event se activa incluso si el player no está de pie directamente dentro de la scene.

Player cambia de realm o island

Los players en Decentraland existen en realmsseparados, y en islands separadas dentro de cada realm. Los players en diferentes realms o islands no pueden verse, interactuar ni chatear entre sí, incluso si están de pie sobre los mismos parcels.

Cada vez que el player cambia de realms o island, el onRealmChangedObservable event se llama.

import { onRealmChangedObservable } from '@dcl/sdk/observables'

onRealmChangedObservable.add((realmChange) => {
	console.log('PLAYER CHANGED ISLAND TO ', realmChange.room)
})

📔 Nota: La onRealmChangedObservable event está obsoleto desde SDK v7.x. Las versiones futuras permitirán un enfoque más orientado a datos, basado en consultar datos regularmente en lugar de usar events.

Este event incluye los siguientes campos:

• serverName: string; El nombre del catalyst server.

• room: string; El nombre de la island.

• displayName: string; El nombre del catalyst server seguido de un - y el nombre de la island. Por ejemplo unicorn-x011.

• domain: string; La url del catalyst server que se está usando.

A medida que los players se mueven por el mapa, pueden cambiar de island para agruparse con aquellos players que están más cerca de ellos. Las islands también desplazan sus fronteras dinámicamente para acomodar un grupo manejable de personas en cada una. Así que incluso si un player permanece quieto, podría cambiar de island a medida que otros entren y salgan de las scenes cercanas.

Si tu scene depende de un servidor de 3rd party para sincronizar cambios entre players en tiempo real, entonces quizá quieras compartir datos solo entre players agrupados en la misma realm+island, así que es una buena práctica cambiar rooms en el servidor de 3rd party cada vez que los players cambian de island.

Funciones de criptografía

📔 Nota: Las functions requirePayment(), signMessage(), convertMessageToObject() están obsoletas. Usa la sendAsync() function en su lugar. Consulta Operaciones blockchain de la scene. También hay libraries que pueden ayudar a simplificar algunos casos de uso comunes con estas functions.

Eventos de Video

📔 Nota: La onVideoEvent event está obsoleto desde SDK v7.x. Consulta Event listeners para una alternativa no obsoleta.

Cuando un Video cambia su estado de reproducción, la onVideoEvent observable recibe un event.

onVideoEvent.add((data) => {
	log('New Video Event ', data)
})

La entrada de un event de Video contiene las siguientes properties:

• videoClipId ( string): El ID de la entity que cambió de estado.

• componentId (string): El ID de la entity que cambió de estado.

• currentOffset (number): El valor actual de la property seek en el Video. Este valor muestra los segundos transcurridos desde el inicio original del Video. -1 por defecto.

• totalVideoLength (number ): La duración en segundos de todo el Video. -1 si la duración es desconocida.

• videoStatus: El valor del nuevo estado de Video de la VideoTexture, expresado como un valor de la VideoStatus enum. Este enum puede contener los siguientes valores posibles:

• VideoStatus.NONE = 0,

• VideoStatus.ERROR = 1,

• VideoStatus.LOADING = 2,

• VideoStatus.READY = 3,

• VideoStatus.PLAYING = 4,

• VideoStatus.BUFFERING = 5