Avatar do Jogador

Aprenda como controlar o avatar do jogador

Existem várias maneiras de controlar o avatar do jogador e alterar a experiência de jogo para seus jogadores.

Para lidar com avatares que não são jogadores, veja NPC Avatars.

Mover jogador

💡 Dica: A maneira mais fácil de mover o jogador é usar o Scene Editor in Creator Hub. Use o no-code Mover jogador ou o Mover jogador aqui Actions, see Make any item smart.

Para alterar a posição do jogador na cena, use a movePlayerTo() função. Esta função recebe um objeto com três propriedades:

• newRelativePosition: Onde posicionar o jogador, expresso como um Vector3.

• cameraTarget: (opcional) A direção para a qual a câmera deve olhar, expressa como um Vector3 representando as coordenadas de um ponto no espaço para olhar. Se nenhum valor for fornecido, a câmera manterá a mesma rotação de antes do movimento.

• avatarTarget: (opcional) A direção para a qual o avatar deve olhar, expressa como um Vector3 representando as coordenadas de um ponto no espaço para olhar. Se nenhum valor for fornecido, o avatar manterá a mesma rotação de antes do movimento. Se o jogador estiver no modo de câmera em 1ª pessoa, a rotação da câmera e do avatar são as mesmas.

• duration: (opcional) Quanto tempo a transição deve levar, em segundos. Se nenhum valor for fornecido, a transição ocorrerá instantaneamente. Se uma duração for fornecida, o avatar caminhará ou correrá até essa nova posição.

📔 Observação: Durante a transição, o avatar não é afetado por colliders, então ele pode atravessar objetos.

import { movePlayerTo } from '~system/RestrictedActions'

// create entity
const myEntity = engine.addEntity()
MeshRenderer.setBox(myEntity)
MeshCollider.setBox(myEntity)

Transform.create(myEntity, {
	position: { x: 4, y: 1, z: 4 },
})

// give entity behavior
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	function () {
		// respawn player
		movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
		})
	}
)

O movimento do jogador ocorre instantaneamente, sem telas de confirmação ou transições de câmera.

📔 Observação: Jogadores só podem ser movidos se já estiverem dentro dos limites da cena, e só podem ser movidos para locais que estejam dentro dos limites da cena. Você não pode usar movePlayerTo() para transportar um jogador para outra cena. Para mover um jogador para outra cena, veja Teleports.

A movePlayerTo() função é awaitable, então se o movimento tiver duração, você pode usar await para esperar que o jogador alcance seu destino.

import { movePlayerTo } from '~system/RestrictedActions'

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	async function () {
		await movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
			duration: 2,
		})
	}
)

Se o jogador tentar se mover durante a duração da transição, a transição será interrompida e a movePlayerTo função nunca será resolvida. Você pode evitar esse comportamento desabilitando todas as entradas enquanto a transição estiver em andamento usando o InputModifier component, see Restrict locomotion.

import { movePlayerTo } from '~system/RestrictedActions'
import {InputModifier, engine} from '@dcl/sdk/ecs'

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	async function () {

		// disable all inputs
		InputModifier.create(engine.PlayerEntity, {
			mode: InputModifier.Mode.Standard({
				disableAll: true,
			}),
		})

		// move player
		await movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
			duration: 2,
		})

		// enable all inputs
		InputModifier.deleteFrom(engine.PlayerEntity)
	}
)

📔 Observação: Além disso, o resultado do await pode ser armazenado para avaliar sua success propriedade para saber se o movimento foi interrompido (por exemplo, por movimento de entrada) ou concluído com sucesso.

Reproduzir animações

Você pode fazer o jogador executar uma animação como parte do código da cena. Isso pode ajudar a proporcionar mais imersão e também ajudar a comunicar o que outros jogadores estão fazendo uns aos outros. As animações do avatar são vistas tanto pelo jogador (em visão 3ª pessoa) quanto por quaisquer outros jogadores ao redor.

Animações controladas pelo jogador são sobrescritas pelas animações de locomoção padrão, como caminhar e pular. Portanto, animações reproduzidas pela cena só tocam enquanto o jogador estiver parado. Se o jogador andar ou pular, quaisquer animações são interrompidas.

📔 Observação: Jogadores só podem ser animados se já estiverem dentro dos limites da cena, não se estiverem em uma cena vizinha. Smart wearables podem reproduzir animações em qualquer lugar.

Enquanto um jogador estiver executando uma animação, ele não é afetado por colisões e seus movimentos não são restritos pela física da cena. Observe também que se uma animação deslocar o jogador de sua posição original (por exemplo, se a animação envolve um salto), o componente Transform do jogador não será afetado por esse deslocamento.

Use o Scene Editor

A maneira mais fácil de fazer um jogador executar uma animação é usar o Scene Editor. Use o no-code Play Emote action para reproduzir uma animação padrão, ou a Play Custom Emote action para reproduzir uma animação a partir de um arquivo. Veja Make any item smart.

Default animations

Use a triggerEmote() função para executar uma das animações padrão que os jogadores podem reproduzir em qualquer lugar em Decentraland. Esta função recebe um objeto com uma única propriedade como argumento:

• predefinedEmote: Um nome de string para um emote existente.

import { triggerEmote } from '~system/RestrictedActions'

const emoter = engine.addEntity()
Transform.create(emoter, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(emoter)
MeshCollider.setBox(emoter)
pointerEventsSystem.onPointerDown(
	{
		entity: emoter,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Dance' },
	},
	() => {
		triggerEmote({ predefinedEmote: 'robot' })
	}
)

Os seguintes emotes mostram feedback sobre ações do jogador na sua cena, todos estes são valores válidos para o predefinedEmote field:

• buttonDown

• buttonFront

• getHit

• knockOut

• lever

• openChest

• openDoor

• punch

• push

• swingWeaponOneHand

• swingWeaponTwoHands

• throw

• sittingChair1

• sittingChair2

• sittingGround1

• sittingGround2

Estes emotes estão disponíveis para todos os jogadores em sua roda de emotes padrão e também podem ser usados em qualquer cena.

• wave

• fistpump

• robot

• raiseHand

• clap

• money

• kiss

• tik

• hammer

• tektonik

• dontsee

• handsair

• shrug

• disco

• dab

• headexplode

💡 Dica: Se um jogador andar ou pular enquanto a animação está sendo reproduzida, ele a interromperá. Se você não quiser que isso seja possível, pode congelar o avatar com Input Modifiers pela duração da animação do avatar.

Animações customizadas

Use a triggerSceneEmote() para fazer o jogador executar uma animação customizada, armazenada como um arquivo .glb como parte do asset da cena.

📔 Observação: O nome do arquivo must end in _emote.glb para funcionar como uma animação de avatar.

Esta função recebe um objeto com as seguintes propriedades:

• src: Uma string com o caminho para o arquivo do emote.

• loop: Se true, a animação irá se repetir continuamente até que o jogador se mova ou a animação seja parada. False por padrão.

import { triggerSceneEmote } from '~system/RestrictedActions'

const emoter = engine.addEntity()
Transform.create(emoter, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(emoter)
MeshCollider.setBox(emoter)
pointerEventsSystem.onPointerDown(
	{
		entity: emoter,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Make snowball' },
	},
	() => {
		triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false })
	}
)

💡 Dica: Se um jogador andar ou pular enquanto a animação está sendo reproduzida, ele a interromperá. Se você não quiser que isso seja possível, pode congelar o avatar com Input Modifiers pela duração da animação do avatar.

Restrict locomotion

Você pode restringir quais ações o jogador pode realizar na sua cena. Use isso para congelar o jogador ou para restringir formas específicas de locomoção, por exemplo, para impedir que o jogador pule ou corra.

Congelar o jogador

Você pode congelar o jogador para que nenhuma das teclas de entrada mova o avatar. Isso pode ser útil para muitas mecânicas de jogo. Também é uma boa prática congelar um jogador enquanto ele executa uma animação importante que não deve ser interrompida por movimento, ou enquanto uma Virtual Camera aponta para longe do avatar e você não quer que o jogador se mova às cegas.

Use a InputModifier component on the engine.PlayerEntity para impedir que as entradas do jogador afetem a locomoção do avatar. O avatar permanecerá imóvel, o jogador só poderá rotacionar a câmera.

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

InputModifier.create(engine.PlayerEntity, {
	mode: InputModifier.Mode.Standard({
		disableAll: true,
	}),
})

Tenha as seguintes considerações em mente:

• Enquanto as interações do jogador estiverem desabilitadas, seu avatar ainda é afetado por forças externas, como gravidade ou plataformas em movimento.

• A InputModifier component can only be used with the engine.PlayerEntity entity. It can only affect the current player, it can't affect other players.

• Este componente só afeta o jogador enquanto o avatar estiver dentro dos limites da sua cena. A locomoção deixa de ser restringida assim que eles saem da cena.

• Enquanto as interações do jogador estiverem desabilitadas, o jogador não pode realizar emotes livremente, mas a cena pode acionar animações no avatar.

• As entradas do jogador não afetam o avatar, mas os global input events ainda podem ser ouvidos pela cena. Você pode usá-los para controlar um veículo ou usar um Virtual Camera to follow another entity as it moves, treating it as an alternative avatar.

Restringindo tipos específicos de locomoção

Em vez de congelar completamente o jogador, você pode restringir certas formas específicas de locomoção do jogador. O InputModifier inclui as seguintes opções:

• disableWalk: O jogador não pode andar devagar (pressionando control). Se o jogador tentar andar, ele passará a trotar ou correr, se permitido.

• disableRun: O jogador não pode correr (pressionando shift). Se o jogador tentar correr, ele apenas trocará para trotar, se permitido.

• disableJog: O jogador não pode trotar (esta é a velocidade de movimento padrão). Se o jogador tentar trotar, ele correrá ou andará em vez disso, se permitido.

• disableJump: O jogador não pode pular.

• disableEmote: O jogador não pode executar emotes voluntariamente. A cena ainda pode acionar animações no avatar do jogador.

• disableAll: O jogador não pode realizar nenhuma das ações acima.

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

InputModifier.create(engine.playerEntity, {
	mode: InputModifier.Mode.Standard({
		disableAll: false,
		disableWalk: false,
		disableRun: true,
		disableJog: true,
		disableJump: true,
		disableEmote: true,
	}),
})

Sintaxe avançada

Para usar o componente sem quaisquer helpers, você pode usar a seguinte sintaxe:

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

InputModifier.createOrReplace(engine.PlayerEntity, {
	mode: {
		$case: 'standard',
		standard: {
			disableAll: false,
			disableWalk: false,
			disableRun: true,
			disableJog: true,
			disableJump: true,
			disableEmote: true,
		},
	},
})

Configurações de Locomoção

Você pode afetar a locomoção do jogador, como sua velocidade de corrida, altura do pulo e mais. Isso pode ser alterado dinamicamente, por exemplo, para permitir que um jogador colete um aumento temporário de velocidade ao interagir com um item, ou para desabilitar a habilidade do jogador de pular por um curto período.

Para fazer isso, adicione um AvatarLocomotionSettings component ao engine.PlayerEntity.

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

AvatarLocomotionSettings.create(engine.PlayerEntity, {
	runSpeed: 10,
	jumpHeight: 2,
})

As seguintes propriedades estão disponíveis:

• walkSpeed: A velocidade com que o jogador anda, em metros por segundo. No cliente desktop, jogadores andam pressionando a tecla control.

• jogSpeed: A velocidade com que o jogador trota, em metros por segundo. Esta é a forma padrão de movimento do jogador.

• runSpeed: A velocidade com que o jogador corre, em metros por segundo. No cliente desktop, jogadores correm pressionando a tecla shift.

• jumpHeight: A altura que o jogador alcança ao pular, em metros.

• runJumpHeight: A altura que o jogador alcança ao pular após correr, em metros.

• hardLandingCooldown: O cooldown após um pouso forte, em segundos. Este é o tempo que o jogador deve esperar antes de poder se mover novamente após aterrissar de uma queda alta.

Para referência, aqui estão os valores padrão dessas propriedades:

• walkSpeed: 1.5 m/s

• jogSpeed: 8 m/s

• runSpeed: 10 m/s

• jumpHeight: 1 m

• runJumpHeight: 1.5 m

• hardLandingCooldown: 0.75 s

💡 Dica: Nenhuma dessas propriedades pode ser menor que 0. Se você definir uma delas com valor negativo, ela será limitada a 0. Definir esses valores como zero terá o mesmo efeito que usar o InputModifier to block the use of certain keys.

Você só pode afetar a locomoção do jogador se ele estiver dentro dos limites da cena. Para afetar os avatares de outros jogadores, você deve executar o código que afeta a locomoção deles na própria instância deles.

Você pode criar um smart wearable que faz o jogador correr sempre mais rápido ou pular mais alto. Se tanto a cena quanto um smart wearable definirem valores diferentes para esses parâmetros, os valores da cena são sempre usados.

Para garantir que ninguém tenha vantagens injustas em uma cena de parkour, você pode impor os parâmetros padrão adicionando explicitamente seus valores padrão na sua cena:

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

AvatarLocomotionSettings.create(engine.PlayerEntity, {
	runSpeed: 10,
	walkSpeed: 1.5,
	jogSpeed: 8 ,
	jumpHeight: 1,
	runJumpHeight: 1.5,
	hardLandingCooldown: 0.75
})

Áreas de modificador de avatar

Avatares se comportam e parecem consistentemente em todo o Decentraland enquanto atravessam cenas. Entretanto, você pode adicionar um AvatarModifierArea a uma região da sua cena para afetar como os avatares dos jogadores se comportam quando entram nessa área.

❗Aviso Por favor, limite a quantidade de AvatarModifierAreas que você usa na sua cena a apenas algumas. Se você usar muitas delas, isso pode ter um impacto significativo no desempenho.

Colocando Avatar Modifier Areas

Adicione uma entidade com um AvatarModifierArea component e posicione essa entidade usando um Transform component.

const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})

Ao criar um AvatarModifierArea component, você deve fornecer o seguinte:

• area: Tamanho da área do modificador

• modifiers: Um array listando os modificadores a implementar na área. Esta propriedade usa valores do AvatarModifierType enum.

Os modificadores suportados são:

• AvatarModifierType.AMT_HIDE_AVATARS

• AvatarModifierType.AMT_DISABLE_PASSPORTS

Todos os efeitos de um AvatarModifierArea só acontecem dentro da região de sua área. Jogadores retornam ao normal quando saem da área.

Um AvatarModifierArea afeta apenas jogadores que estão dentro da área. Entrar na área não afeta como outros jogadores fora da área são percebidos.

Os efeitos de um AvatarModifierArea são calculados localmente para cada jogador. Você pode ter um AvatarModifierArea que está presente na cena apenas para alguns jogadores e não para outros. Por exemplo, você poderia criar um jogo de "marco polo", onde apenas um jogador na cena tem uma área de modificador que esconde todos os outros jogadores. Todos os outros jogadores que não têm essa área em sua versão local da cena são capazes de se ver normalmente.

Se a área esconde avatares, então os jogadores que não têm a área em sua versão local da cena verão todos os avatares normalmente, mesmo aqueles que se veem como ocultos. Jogadores que têm a área experimentarão a si mesmos e todos os outros avatares como afetados pela área quando entrarem nela.

📔 Observação: As áreas de modificador de avatar são afetadas pela position e rotation do componente Transform da entidade hospedeira, mas não são afetadas pela scale.

📔 Observação: O AvatarModifierAreacomponent deve ser importado via

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

Veja Imports para saber como lidar com estes facilmente.

Esconder avatares

Quando um jogador entra em uma AvatarModifierArea que possui o AvatarModifierType.AMT_HIDE_AVATARS modifier, o avatar do jogador deixa de ser renderizado. Isso se aplica tanto ao jogador em visão 3ª pessoa quanto quando outros jogadores entram na área.

const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})

Isso permite que você substitua o avatar padrão do Decentraland por qualquer avatar customizado que queira mostrar em sua cena. Observe que, se você quiser ver outros jogadores com avatares customizados, você deve lidar com a sincronização das posições dos jogadores você mesmo.

Desabilitar Popup do Passport

Quando um jogador entra em uma AvatarModifierArea que possui o AvatarModifierType.AMT_DISABLE_PASSPORTS modifier, clicar neles não abre mais a UI do passport que mostra bio do jogador, inventário, etc.

const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_DISABLE_PASSPORTS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})

Isso é especialmente útil em jogos onde abrir acidentalmente essa UI poderia interromper o fluxo do jogo, por exemplo em um jogo de tiro multiplayer.

Excluir Avatares

Você pode excluir uma lista de jogadores de serem afetados por uma área de modificador adicionando seus IDs de jogador a um array na excludeIds propriedade da área de modificador.

Este exemplo esconde todos os avatares em uma área, exceto aqueles de jogadores com IDs específicos. Você poderia usar isso, por exemplo, em um evento ao vivo, para mostrar apenas os anfitriões do evento no palco e esconder quaisquer outros jogadores que subam ao palco.

const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: ['0xx1...', '0xx2...'],
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})

📔 Observação: Certifique-se de que os IDs dos jogadores estejam todos escritos com letras minúsculas. Use .toLowerCase() se necessário.

As áreas de modificador são executadas localmente na instância de cada jogador. A lista de IDs excluídos pode ser diferente para cada jogador. No exemplo abaixo, cada jogador exclui seu próprio ID de um modificador que esconde avatares, para que cada um veja seu próprio avatar e nenhum outro.

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

export function main() {
	let userData = getPlayer()
	if (!userData) return

	const entity = engine.addEntity()

	AvatarModifierArea.create(entity, {
		area: Vector3.create(16, 5, 16),
		modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
		excludeIds: [userData.userId],
	})

	Transform.create(entity, {
		position: Vector3.create(8, 0, 8),
	})
}

❗Aviso Se a lista de IDs excluídos for alterada periodicamente (por exemplo, com base em jogadores entrando ou saindo de uma área), certifique-se de que a lista seja mantida em ordem. Faça um .sort() no array, para que a lista permaneça na mesma ordem cada vez que for passada. Dessa forma, apenas as alterações na lista são computadas. Caso contrário, isso pode ter um impacto significativo no desempenho da cena.

AvatarModifierArea.create(entity, {
	area: Vector3.create(16, 5, 16),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: [myAvatarList.sort()],
})

Depurar áreas de modificador

Pode ser difícil saber exatamente quais partes da cena suas áreas de modificador cobrem com base apenas no código. Feedback visual ajuda muito a confirmar que elas estão bem posicionadas.

Para verificar as posições de um AvatarModifierArea ou de um CameraModeArea, dê à entidade que o contém um MeshRenderer component com uma box shape, e defina o scale no mesmo tamanho que a area da área do modificador.

📔 Observação: Áreas de modificador não são afetadas pela scale property of the transform, their size is based on their area property.

const entity = engine.addEntity()
const areaSize = Vector3.create(8, 3, 8)

AvatarModifierArea.create(entity, {
	area: areaSize,
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
  	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
	scale: areaSize,
})

MeshRenderer.setBox(entity)
Material.setPbrMaterial(entity, {
	albedoColor: Color4.create(0.5, 0.5, 0.5, 0.5),
})

Para ativar os efeitos da área de modificador, a cabeça ou o torso do jogador deve entrar na área. Não terá efeito se apenas os pés do jogador estiverem na área. Certifique-se de que o jogador não consiga facilmente evitar a área pulando.

📔 Observação: A área completa deve caber dentro dos limites da sua cena.

Mudar a aparência de um avatar

Você não pode mudar quais wearables o avatar do jogador está usando, mas pode trocar o avatar do jogador por um avatar NPC que você pode personalizar totalmente.

Veja NPC Avatars for more details.

📔 Observação: Para permitir que o jogador tenha controle total sobre esse avatar, você deve escutar eventos de botão para detectar quando eles pressionam um botão e então acionar a animação correspondente no avatar NPC. Veja Button Events for more details.

A fluidez do controle pode não ser perfeita ao fazer isso; você pode querer usar isso apenas em casos muito específicos.