Escuchadores de eventos

Eventos que la escena puede seguir, relacionados con acciones del jugador y cambios de la escena.

Hay varios eventos a los que la escena puede suscribirse para conocer las acciones del jugador mientras está en la escena o cerca de ella.

Para los eventos de botón y clic realizados por el jugador, consulta Eventos de botón.

El jugador entra o sale de la escena

Cada vez que un avatar entra o sale de las parcelas de terreno que componen tu escena, o se teletransporta dentro o fuera, esto crea un evento que puedes escuchar.

Este evento se activa para todos los avatares, incluido el del jugador.

import { onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

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

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

En el onEnterScene evento, la función puede acceder a todos los datos devueltos por obtener datos del jugador a través de la player propiedad. En el onLeaveScene evento, la función solo tiene acceso al ID del jugador.

Solo el jugador actual

Puedes filtrar los eventos activados para reaccionar solo al avatar del jugador, en lugar de a otros avatares que puedan estar cerca.

import { getPlayer, onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

export function main() {
	let myPlayer = getPlayer()

	onEnterScene((player) => {
		if (!player) return
		console.log('ENTRÓ A LA ESCENA', player)

		if (myPlayer && player.userId == myPlayer.userId) {
			console.log('HE ENTRADO')
		}
	})

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

		if (myPlayer && userId == myPlayer.userId) {
			console.log('HE SALIDO')
		}
	})
}

Este ejemplo primero obtiene el id del jugador, luego se suscribe a los eventos y compara el userId devuelto por el evento con el del jugador.

Consultar todos los jugadores en la escena

Recorre la lista completa de jugadores que están actualmente en tu escena iterando sobre todas las entities con un PlayerIdentityData component.

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

export function main() {
	for (const [entity, data, transform] of engine.getEntitiesWith(
		PlayerIdentityData,
		Transform
	)) {
		console.log('JUGADOR: ', { entity, data, transform })
	}
}

El jugador cambia el modo de cámara

Conocer el modo de cámara puede ser muy útil para ajustar con precisión la mecánica de tu escena y adaptarla mejor a lo que resulta más cómodo usando este modo. Por ejemplo, es más difícil hacer clic en objetivos pequeños cuando estás en tercera persona.

El siguiente fragmento usa la onChange función para disparar un evento cada vez que cambia la cámara. También dispara un evento cuando la escena carga, con el modo de cámara inicial del jugador.

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

export function main() {
	CameraMode.onChange(engine.CameraEntity, (cameraComponent) => {
		if (!cameraComponent) return
		console.log('El modo de cámara cambió', cameraComponent?.mode)
		// 0 = primera persona
		// 1 = tercera persona
	})
}

Ver Comprobar el modo de cámara del jugador.

El jugador reproduce una animación

Usa la onChange función en el AvatarEmoteCommand component para disparar un evento cada vez que el jugador reproduce un emote. Esto incluye tanto emotes base (dance, clap, wave, etc.) como emotes de tokens.

import { AvatarEmoteCommand } from '@dcl/sdk/ecs'

export function main() {
	AvatarEmoteCommand.onChange(engine.PlayerEntity, (emote) => {
		if (!emote) return
		console.log('Emote reproducido: ', emote.emoteUrn)
	})
}

El evento incluye la siguiente información:

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

• loop: Si el emote se reproduce en bucle o una sola vez

• timestamp: Cuándo se activó el emote.

• state: Un valor del EmoteState enum que describe el evento del ciclo de vida: ES_STARTED (el emote se inició; también es el valor cuando el campo está ausente, en clientes antiguos), ES_FINISHED (se reprodujo un emote no cíclico hasta su final), o ES_INTERRUPTED (el emote se interrumpió por movimiento, teletransporte, otro emote, una parada explícita o al salir de la escena). Ver Detectar cuándo termina un emote.

También puedes detectar emotes de otros jugadores en la escena pasando una referencia al otro jugador en lugar de engine.PlayerEntity.

El jugador cambia de perfil

Usa la onChange función en el AvatarEquippedData component para disparar un evento cada vez que el jugador cambia una de sus wearables, o sus emotes listados en la rueda de acceso rápido. Del mismo modo, usa la onChange función en el AvatarBase para disparar un evento cada vez que el jugador cambia las propiedades básicas de su avatar, como el color del pelo, el color de la piel, la forma del avatar o el nombre.

import { AvatarEquippedData, AvatarBase } from '@dcl/sdk/ecs'

export function main() {
	AvatarEquippedData.onChange(engine.PlayerEntity, (equipped) => {
		if (!equipped) return
		console.log('Nueva lista de wearables: ', equipped.wearableUrns)
		console.log('Nueva lista de emotes: ', equipped.emoteUrns)
	})

	AvatarBase.onChange(engine.PlayerEntity, (body) => {
		if (!body) return
		console.log('Nuevo color de ojos: ', body.eyesColor)
		console.log('Nuevo color de piel: ', body.skinColor)
		console.log('Nuevo color de pelo: ', body.hairColor)
		console.log('Nuevo URN del cuerpo: ', body.bodyShapeUrn)
	})
}

El evento en AvatarEquippedData incluye la siguiente información:

• wearableUrns: La lista de wearables que el jugador tiene equipados actualmente.

• emoteUrns: La lista de emotes que el jugador tiene equipados actualmente en la rueda de acceso rápido.

El evento en AvatarBase incluye la siguiente información:

• name: El nombre del jugador.

• bodyShapeUrn: Los ids correspondientes al tipo de cuerpo masculino o femenino.

• skinColor: Color de piel del jugador como un Color3

• eyesColor: Color de ojos del jugador como un Color3

• hairColor: Color de pelo del jugador como un Color3

También puedes detectar cambios en wearables o avatares de otros jugadores en la escena; simplemente pasa una referencia al otro jugador en lugar de engine.PlayerEntity.

También puedes detectar cambios en los perfiles de otros jugadores en la escena; simplemente pasa una referencia al otro jugador en lugar de engine.PlayerEntity.

El jugador bloquea o desbloquea el cursor

Los jugadores pueden cambiar 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 clic en el botón derecho del ratón o presionando la tecla Esc y vuelven a bloquear el cursor haciendo clic en cualquier parte de la pantalla.

Añade un PointerLock component a la engine.CameraEntity entity en tu escena, y usa el onChange función en el PointerLock component para disparar un evento cada vez que el jugador cambia entre los dos modos de cursor.

import {PointerLock} from '@dcl/sdk/ecs'

export function main() {
    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    // Mostrar un hint sobre el modo de cursor
		   }
	})
}

Puedes usar esta información para dar un pequeño aviso al jugador, como mostrar un popup de UI que diga que este juego se disfruta mejor con un cursor desbloqueado. O también puedes forzar el modo de cursor del jugador cambiando el isPointerLocked en el component. El siguiente ejemplo siempre establece el modo de cursor en desbloqueado:

import {PointerLock} from '@dcl/sdk/ecs'

export function main() {
    PointerLock.createOrReplace(engine.CameraEntity, {isPointerLocked: false});
    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    PointerLock.getMutable(engine.CameraEntity).isPointerLocked = false
		   }
	})
}

Abrir paneles del Explorer

Tu escena puede abrir los paneles de pantalla completa integrados del Explorer (mapa, ajustes, mochila, etc.) usando la openExplorerUi restricted action. Esto es útil para dirigir a los jugadores a funciones específicas del Explorer desde la UI de tu escena.

import { openExplorerUi } from '~system/RestrictedActions'
import { ExplorerUi } from '@dcl/sdk/ecs'

// Abrir el panel del mapa
await openExplorerUi({ ui: ExplorerUi.EU_MAP })

El ExplorerUi enum tiene los siguientes valores:

• EU_SETTINGS (0)

• EU_MAP (1)

• EU_BACKPACK (2)

• EU_CAMERA_REEL (3)

• EU_COMMUNITIES (4)

• EU_PLACES (5)

• EU_EVENTS (6)

Nota: Al igual que otras restricted actions (movePlayerTo, triggerEmote), openExplorerUi solo funciona mientras el jugador esté de pie dentro de las parcelas de la escena.

Observar cuándo se abren o cierran paneles

Usa la ExplorerUiEventsResult component para detectar cuándo se abren o cierran paneles del Explorer. Este es un component de solo crecimiento en engine.RootEntity, similar a PointerEventsResult. Transmite eventos cada vez que se abre o cierra un panel.

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

engine.addSystem(() => {
	// Iterar sobre los eventos nuevos desde el último frame
	for (const event of ExplorerUiEventsResult.get(engine.RootEntity)) {
		if (event.event?.$case === 'opened') {
			console.log('Panel abierto:', event.ui)
		}
		if (event.event?.$case === 'closed') {
			console.log('Panel cerrado:', event.ui)
		}

		// Comprobar qué panel específico
		if (event.ui === ExplorerUi.EU_MAP && event.event?.$case === 'closed') {
			console.log('El jugador cerró el mapa')
		}
	}
})

Cada evento contiene:

• ui: Qué panel es el que trata el evento (un valor de ExplorerUi ).

• timestamp: Un contador monótono de cuándo ocurrió el evento.

• event: Ya sea { $case: 'opened' } o { $case: 'closed' }.

💡 Consejo: Para un ejemplo funcional de eventos de reproducción de emotes, consulta la 4,23-emote-finish escena de prueba, que registra cada AvatarEmoteCommand entrada añadida a la entity del jugador como STARTED, FINISHED o INTERRUPTED — reproduce un emote completo para ver FINISHED, o aléjate a mitad de la reproducción para ver INTERRUPTED.