Funções Depreciadas

Funções legadas

As seguintes funções são todas legadas e devem ser evitadas. Elas ainda funcionam, mas no futuro podem deixar de ser suportadas. Todos estes exemplos incluem links para formas alternativas de obter a mesma informação ou alcançar os mesmos resultados.

Jogador entra ou sai da cena

📔 Nota: O onEnterSceneObservable e onLeaveSceneObservable eventos estão obsoletos no SDK 7.x. Use onEnterScene em vez disso, veja Jogador entra ou sai da cena.

Sempre que um avatar entra ou sai dos terrenos que compõem sua cena, ou teleporta para dentro ou fora, isso cria um evento ao qual você pode escutar. Este evento é acionado por todos os avatares, incluindo o do jogador.

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 evento responde apenas a jogadores que estão sendo renderizados localmente. Em cenas grandes, onde o tamanho da cena excede o alcance visual, jogadores que entram no canto oposto podem não ser registrados. Se o número de jogadores na região exceder as capacidades de uma ilha nos servidores da Decentraland, jogadores que não estão compartilhando a mesma ilha não são visíveis e também não são rastreados por esses eventos.

Os observables onEnterScene e onLeaveScene importados de '@dcl/sdk/observables' também estão obsoletos. As funções corretas têm o mesmo nome, mas são importadas de '@dcl/sdk/src/players' em vez disso. No exemplo abaixo você pode ver ambas as variações, primeiro a versão obsoleta, depois a correta.

// DEPRECATED - imported from 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)
})

// CURRENT - imported as a player function
import { onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

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

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

Jogador conecta ou desconecta

📔 Nota: O getConnectedPlayers função e o onPlayerConnectedObservable e onPlayerDisconnectedObservable eventos estão obsoletos no SDK 7.x. Use onEnterScene em vez disso, veja Jogador entra ou sai da cena. Cada cena agora é uma ilha de comunicação distinta, tornando o mesmo estar conectado ou estar na mesma cena.

Obtenha a lista completa de jogadores atualmente conectados de getConnectedPlayers.

import { getConnectedPlayers } from '~system/Players'

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

Sempre que outro jogador começa ou deixa de ser renderizado pelo motor local, isso cria um evento ao qual você pode escutar. Jogadores podem ou não estar na mesma cena que você, mas devem estar dentro do alcance visual (não necessariamente à vista). O onPlayerConnectedObservable detecta tanto quando um jogador se conecta recentemente nas proximidades quanto quando fica suficientemente próximo para estar no alcance visual, da mesma forma o onPlayerDisconnectedObservable detecta quando um jogador termina sua sessão ou se afasta.

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)
})

Tenha em mente que se outros jogadores já estão sendo renderizados nos arredores antes que o jogador tenha carregado sua cena, este evento não notificará a cena recém-carregada sobre os jogadores já existentes. Se você precisa acompanhar todos os jogadores atuais, você pode consultar os jogadores existentes ao carregar a cena e então escutar este evento para atualizações.

Consulta todos os jogadores na cena

📔 Nota: O getPlayersInScene função está obsoleta no SDK 7.x. Em vez disso, itere sobre todos os jogadores com um PlayerIdentityData componente. Veja Buscar todos os jogadores.

Você também pode obter a lista completa de jogadores que estão atualmente na sua cena e sendo renderizados chamando getPlayersInScene().

import { getPlayersInScene } from '~system/Players'

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

Jogador executa animação

📔 Nota: O onPlayerExpressionObservable evento está obsoleto no SDK 7.x. Use o AvatarEmoteCommand componente em vez disso, veja Jogador executa animação.

Sempre que o jogador executar um emote (dança, palmas, aceno, etc), você pode detectar este evento.

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

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

O evento inclui as seguintes informações:

• expressionId: Nome do emote executado (por exemplo: wave, clap, kiss)

📔 Nota: Este evento é acionado sempre que o jogador fizer um emote e a cena estiver carregada. O jogador pode estar em uma cena próxima quando isso acontecer.

Jogador altera perfil

📔 Nota: O onProfileChanged evento está obsoleto no SDK 7.x. Use o AvatarEquippedData componente em vez disso, veja Jogador altera perfil.

Sempre que o jogador faz uma alteração em seu perfil, o onProfileChanged evento é chamado. Essas mudanças podem incluir vestir wearables diferentes, alterar nome, descrição, ativar experiências portáteis, etc.

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

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

Os dados do evento incluem apenas o ID do jogador e um número de versão para o perfil desse avatar, de acordo com o servidor catalyst. Toda vez que uma mudança é propagada, o número da versão aumenta em 1.

Quando este evento é acionado, você pode então usar o getUserData() função para buscar a versão mais recente dessa informação, incluindo a lista de wearables que o jogador está usando. Pode ser necessário adicionar um pequeno atraso antes de chamar getUserData() para garantir que a versão retornada por essa função esteja atualizada.

💡 Tip: Ao testar em preview com o web explorer legado, para evitar usar um avatar aleatório, execute a cena no navegador conectado com sua carteira Metamask.

📔 Nota: Este evento é acionado apenas por mudanças no jogador atual, não por alterações nos perfis de outros jogadores próximos.

Cena terminou de carregar

📔 Nota: O onSceneReadyObservable evento está obsoleto a partir do SDK v7.x. Esta função não é mais relevante. Você pode garantir que algo seja executado após a cena terminar de carregar executando-o dentro da função Main() Veja Ciclo de vida da cena

Quando a cena termina de carregar, o onSceneReadyObservable é chamado. Isso funciona tanto se o jogador carregar diretamente na cena, quanto se o jogador se aproximar da cena vindo de outro lugar. Quando todo o conteúdo da cena terminou seu carregamento inicial, incluindo modelos pesados, etc., este evento é chamado.

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

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

Métodos de dados de jogador obsoletos

📔 Nota: O getUserData() e getPlayerData() funções estão obsoletas a partir do SDK v7.4.x. Use getPlayer() em vez disso. Veja Dados do usuário.

Para obter informações do jogador atual que está executando a cena, use getUserData().

O exemplo abaixo importa o namespace ~system/UserIdentity e executa getUserData().

import { getUserData } from '~system/UserIdentity'

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

Você pode obter dados de outros jogadores que estão próximos, chamando getPlayerData(), passando o id de uma conta Decentraland.

import { getPlayerData } from '~system/Players'

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

Ambos getUserData() e getPlayerData() retornam a mesma estrutura de dados disponível via a content API. Veja Dados de qualquer jogador

getPlayerData() só podem buscar dados de jogadores que estão atualmente próximos. Eles não precisam necessariamente estar na mesma cena, mas no alcance visual, isso porque essa informação é buscada do motor local que está renderizando esses avatares. Para testar isso em preview, abra uma segunda aba e faça login com uma conta diferente.

📔 Nota: Os IDs de usuário devem sempre estar em letras minúsculas. Se copiar um endereço de carteira, certifique-se de que todos os caracteres estejam em minúsculas.

O getUserPublicKey() e getUserAccount() funções também estão obsoletas. Por favor, use getPlayer() em vez disso. Veja Dados do usuário.

Obter hora do skybox

📔 Nota: O getDecentralandTime() função está obsoleta a partir do SDK v7.x.x. Use getWorldTime() em vez disso. Veja Obter Decentraland Time.

import { getDecentralandTime } from '~system/EnvironmentApi'

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

Obter realm

📔 Nota: O getCurrentRealm() função está obsoleta a partir do SDK v7.x.x. Use getRealm() em vez disso. Veja Obter dados do Realm.

import { getCurrentRealm } from '@decentraland/EnvironmentAPI'

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

	console.log(playerRealm.domain)
}

fetchPlayerData()

Está em modo preview

📔 Nota: O isPreviewMode() função está obsoleta a partir do SDK v7.x.x. Use getRealm() em vez disso, que contém uma preview propriedade. Veja Obter dados do Realm.

import { isPreviewMode } from '~system/EnvironmentAPI'

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

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

Jogador clica em outro jogador

Sempre que o jogador clica em outro jogador, você pode detectar um evento.

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

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

📔 Nota: O onPlayerClickedObservable evento está obsoleto a partir do SDK v7.x. Versões futuras permitirão uma abordagem mais orientada a dados, baseada em consultar dados regularmente em vez de eventos.

Como alternativa, você pode anexar um collider invisível ao jogador e detectar cliques contra este.

📔 Nota: Tanto o jogador que realiza o clique quanto o jogador clicado devem estar dentro dos terrenos da cena. Este listener detecta apenas eventos do jogador atual clicando em outros jogadores, não os cliques realizados por outros jogadores.

O evento inclui os seguintes dados:

• userId: O id do jogador clicado

• ray: Dados sobre o raio traçado pelo clique

  • campo: espera um Um Vector3 normalizado que representa a direção do ponto de origem do clique até o ponto de impacto do clique.

  • distance: maxDistance A distância em metros do ponto de origem até o ponto de impacto.

  • origin: espera um O ponto de origem do clique, a posição do jogador que fez o clique, relativa à cena.

💡 Tip: O comportamento padrão de clicar em outro jogador é abrir o passaporte do jogador, onde você pode ver informações adicionais sobre esse jogador, adicioná‑lo como amigo, etc. Você pode desabilitar a abertura dessa UI para que ela não atrapalhe a experiência que você quer construir adicionando uma Avatar Modifier Area.

Jogador trava/destrava cursor

📔 Nota: O onPointerLockedStateChange evento está obsoleto a partir do SDK v7.x. Veja Listeners de eventos para uma alternativa não obsoleta.

Jogadores podem alternar entre dois modos de cursor: cursor travado modo para controlar a câmera ou cursor destravado modo para mover o cursor livremente sobre a UI.

Jogadores destravam o cursor clicando o Botão direito do mouse ou pressionando a tecla Esc e travam o cursor de volta clicando em qualquer lugar na tela.

Este onPointerLockedStateChange evento é ativado cada vez que um jogador alterna entre esses dois modos, enquanto perto da cena.

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 evento é acionado mesmo se o jogador não estiver diretamente dentro da cena.

Jogador muda de realm ou ilha

Jogadores na Decentraland existem em realms, e em islands separadas dentro de cada realm. Jogadores em realms ou islands diferentes não conseguem se ver, interagir ou conversar entre si, mesmo se estiverem nos mesmos terrenos.

Cada vez que o jogador muda de realm ou island, o onRealmChangedObservable evento é chamado.

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

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

📔 Nota: O onRealmChangedObservable evento está obsoleto a partir do SDK v7.x. Versões futuras permitirão uma abordagem mais orientada a dados, baseada em consultar dados regularmente em vez de eventos.

Este evento inclui os seguintes campos:

• serverName: string; O nome do servidor catalyst.

• room: string; O nome da island.

• displayName: string; O nome do servidor catalyst seguido de um - e o nome da island. Por exemplo unicorn-x011.

• domain: string; A URL do servidor catalyst sendo usado.

Conforme os jogadores se movem pelo mapa, eles podem trocar de island para serem agrupados com aqueles jogadores que estão agora mais próximos. As islands também ajustam seus limites dinamicamente para encaixar um grupo manejável de pessoas em cada uma. Então mesmo que um jogador fique parado, ele pode ser trocado de island conforme outros entram e saem das cenas ao redor.

Se sua cena depende de um servidor de terceiros para sincronizar mudanças entre jogadores em tempo real, então você pode querer compartilhar dados apenas entre jogadores que estão agrupados em um mesmo realm+island, por isso é uma boa prática trocar de sala no servidor de terceiros sempre que os jogadores mudarem de island.

Funções de cripto

📔 Nota: As funções requirePayment(), signMessage(), convertMessageToObject() estão obsoletas. Use a sendAsync() função em vez disso. Veja Operações de blockchain da cena. Também existem bibliotecas que podem ajudar a simplificar alguns casos de uso comuns com essas funções.

Eventos de vídeo

📔 Nota: O onVideoEvent evento está obsoleto a partir do SDK v7.x. Veja Listeners de eventos para uma alternativa não obsoleta.

Quando um vídeo muda seu estado de reprodução, o onVideoEvent observable recebe um evento.

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

A entrada de um evento de vídeo contém as seguintes propriedades:

• videoClipId ( string): O ID da entidade que mudou de estado.

• componentId (string): O ID da entidade que mudou de estado.

• currentOffset (maxDistance): O valor atual da propriedade seek . Esta propriedade mostra segundos após o começo original do vídeo. -1 por padrão.

• totalVideoLength (maxDistance ): O comprimento em segundos de todo o vídeo. -1 se o comprimento for desconhecido.

• videoStatus: O valor para o novo status do vídeo do VideoTexture, expresso como um valor do enum VideoStatus . Este enum pode conter os seguintes valores possíveis:

• VideoStatus.NONE = 0,

• VideoStatus.ERROR = 1,

• VideoStatus.LOADING = 2,

• VideoStatus.READY = 3,

• VideoStatus.PLAYING = 4,

• VideoStatus.BUFFERING = 5