Listeners de eventos

Eventos que a cena pode rastrear, relacionados às ações do player e às mudanças na cena.

Há vários eventos aos quais a scene pode se inscrever para saber as ações do player enquanto estiver na scene ou perto dela.

Para eventos de botão e clique executados pelo player, veja Eventos de botão.

Player entra ou sai da scene

Sempre que um avatar entra ou sai dos parcels de terra que compõem sua scene, ou teleporta para dentro ou para fora, isso cria um evento que você pode escutar.

Esse evento é disparado por todos os avatares, incluindo o do player.

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

export function main() {
	onEnterScene((player) => {
		if (!player) return
		console.log('ENTROU NA SCENE', player)
	})

	onLeaveScene((userId) => {
		if (!userId) return
		console.log('SAIU DA SCENE', userId)
	})
}

Na onEnterScene evento, a função pode acessar todos os dados retornados por obter dados do player via a player propriedade. No evento onLeaveScene a função só tem acesso ao ID do player.

Apenas o player atual

Você pode filtrar os eventos disparados para reagir apenas ao avatar do player, em vez de outros avatares que possam estar por perto.

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

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

	onEnterScene((player) => {
		if (!player) return
		console.log('ENTROU NA SCENE', player)

		if (myPlayer && player.userId == myPlayer.userId) {
			console.log('EU ENTREI')
		}
	})

	onLeaveScene((userId) => {
		if (!userId) return
		console.log('SAIU DA SCENE', userId)

		if (myPlayer && userId == myPlayer.userId) {
			console.log('EU SAÍ')
		}
	})
}

Este exemplo primeiro obtém o id do player, depois se inscreve nos eventos e compara o userId retornado pelo evento com o do player.

Consultar todos os players na scene

Percorra a lista completa de players que estão atualmente na sua scene iterando sobre todas as entities com um PlayerIdentityData component.

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

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

Player muda o modo da câmera

Saber o modo da câmera pode ser muito útil para ajustar melhor a mecânica da sua scene ao que for mais confortável usando esse modo. Por exemplo, alvos pequenos são mais difíceis de clicar quando está em terceira pessoa.

O seguinte trecho usa a onChange função para disparar um evento toda vez que a câmera muda. Ele também dispara um evento quando a scene carrega, com o modo inicial da câmera do player.

export function main() {
	CameraMode.onChange(engine.CameraEntity, (cameraComponent) => {
		if (!cameraComponent) return
		console.log('Modo da câmera alterado', cameraComponent?.mode)
		// 0 = primeira pessoa
		// 1 = terceira pessoa
	})
}

Consulte Verificar o modo da câmera do player.

Player reproduz animação

Use o onChange função no AvatarEmoteCommand component para disparar um evento toda vez que o player reproduz um emote. Isso inclui tanto emotes base (dance, clap, wave etc.) quanto emotes de tokens.

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

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

O evento inclui as seguintes informações:

• emoteUrn: Nome do emote executado (ou seja: wave, clap, kiss)

• loop: Se o emote está em loop ou sendo reproduzido uma vez

• timestamp: Quando o emote foi disparado.

Você também pode detectar emotes de outros players na scene, basta passar uma referência ao outro player em vez de engine.PlayerEntity.

Player muda o perfil

Use o onChange função no AvatarEquippedData component para disparar um evento toda vez que o player altera um de seus wearables, ou seus emotes listados na roda de acesso rápido. Da mesma forma, use o onChange função no AvatarBase para disparar um evento toda vez que o player altera as propriedades base do seu avatar, como cor do cabelo, cor da pele, forma do avatar ou nome.

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

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

	AvatarBase.onChange(engine.PlayerEntity, (body) => {
		if (!body) return
		console.log('Nova cor dos olhos: ', body.eyesColor)
		console.log('Nova cor da pele: ', body.skinColor)
		console.log('Nova cor do cabelo: ', body.hairColor)
		console.log('Novo URN do corpo: ', body.bodyShapeUrn)
	})
}

O evento em AvatarEquippedData inclui as seguintes informações:

• wearableUrns: A lista de wearables que o player tem atualmente equipados.

• emoteUrns: A lista de emotes que o player tem atualmente equipados na roda de acesso rápido.

O evento em AvatarBase inclui as seguintes informações:

• name: O nome do player.

• bodyShapeUrn: Os ids correspondentes ao tipo de corpo masculino ou feminino.

• skinColor: Cor da pele do player como um Color4

• eyeColor: Cor dos olhos do player como um Color4

• hairColor: Cor do cabelo do player como um Color4

Você também pode detectar mudanças em wearables ou avatares de outros players na scene, basta passar uma referência ao outro player em vez de engine.PlayerEntity.

💡 Dica: Ao testar em preview com o editor web legado, para evitar usar um avatar aleatório, execute a scene no navegador conectado com sua wallet Metamask.

Você também pode detectar mudanças nos perfis de outros players na scene, basta passar uma referência ao outro player em vez de engine.PlayerEntity.

Player bloqueia ou desbloqueia o cursor

Os players podem alternar entre dois modos de cursor: modo de cursor bloqueado para controlar a câmera ou modo de cursor desbloqueado para mover o cursor livremente pela UI.

Os players desbloqueiam o cursor clicando no botão direito do mouse ou pressionando a tecla Esc , e bloqueiam o cursor novamente clicando em qualquer lugar da tela.

Adicione um PointerLock component ao engine.CameraEntity entity na sua scene, e use o onChange função no PointerLock component para disparar um evento toda vez que o player alterna entre os dois modos de cursor.

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

export function main() {
    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    // Mostrar dica sobre o modo do cursor
		   }
	})
}

Você pode usar essa informação para orientar o player de forma sutil, como mostrar um popup de UI dizendo que este jogo é melhor com o cursor desbloqueado. Ou também pode forçar o modo do cursor do player alterando o isPointerLocked no component. O exemplo a seguir sempre define o modo do cursor como 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
		   }
	})
}