Avatar do player

Aprenda a controlar o avatar do player

Há várias formas de controlar o avatar do jogador e de alterar a experiência de gameplay para os seus jogadores.

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

Mover o jogador

💡 Dica: A forma mais fácil de mover o jogador é usar o Scene Editor no Creator Hub. Use o no-code Mover o jogador ou o Move player here Actions, veja Torne qualquer item smart.

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

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

• cameraTarget: (opcional) A direção para a qual fazer a camera olhar, expressa como um Vector3 que representa as coordenadas de um ponto no espaço para o qual olhar. Se nenhum valor for fornecido, a camera manterá a mesma rotação de antes de mover.

• avatarTarget: (opcional) A direção para a qual fazer o avatar olhar, expressa como um Vector3 que representa as coordenadas de um ponto no espaço para o qual olhar. Se nenhum valor for fornecido, o avatar manterá a mesma rotação de antes de mover. Se o jogador estiver no modo de camera em 1st person, a rotação da camera 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 for fornecida uma duração, o avatar caminhará ou correrá até esta nova posição.

📔 Nota: Durante a transição, o avatar não é afetado por colliders, por isso pode atravessar objetos.

import { movePlayerTo } from '~system/RestrictedActions'

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

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

// dar comportamento à entity
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	function () {
		// reaparecer o jogador
		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 ecrãs de confirmação nem transições de camera.

📔 Nota: Os jogadores só podem ser movidos se já estiverem dentro dos limites da scene, e só podem ser movidos para locais que estejam dentro dos limites da scene. Não pode usar movePlayerTo() para transportar um jogador para outra scene. Para mover um jogador para outra scene, veja Teleports.

O movePlayerTo() function é awaitable, por isso, se o movimento tiver duração, pode usar await para esperar que o jogador chegue ao 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 mover-se durante a duração da transição, a transição será interrompida e a movePlayerTo function nunca será resolvida. Pode prevenir este comportamento desativando todas as inputs enquanto a transição estiver em curso, usando o InputModifier component, veja Restringir locomoção.

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 () {

		// desativar todas as inputs
		InputModifier.create(engine.PlayerEntity, {
			mode: InputModifier.Mode.Standard({
				disableAll: true,
			}),
		})

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

		// ativar todas as inputs
		InputModifier.deleteFrom(engine.PlayerEntity)
	}
)

📔 Nota: Além disso, o resultado do await pode ser armazenado para avaliar a sua success property para saber se o movimento foi interrompido (por exemplo, por movimento por input) ou concluído com sucesso.

Reproduzir animações

Pode fazer com que o jogador execute uma animação como parte do code da scene. Isto pode ajudar a proporcionar mais imersão e também pode ajudar a comunicar o que os outros jogadores estão a fazer uns aos outros. As animações do avatar são vistas tanto pelo jogador (na vista em 3rd person) como por quaisquer outros jogadores nas proximidades.

As animações controladas pelo jogador são substituídas pelas animações de locomoção padrão, como caminhar e saltar. Portanto, as animações reproduzidas pela scene só são executadas enquanto o jogador estiver parado. Se o jogador caminhar ou saltar, quaisquer animações são interrompidas.

📔 Nota: Os jogadores só podem ser animados se já estiverem dentro dos limites da scene, e não se estiverem numa scene vizinha. Smart wearables podem reproduzir animações em qualquer lugar.

Enquanto um jogador estiver a executar uma animação, não é afetado por colisões e os seus movimentos não ficam ограничados pela física da scene. Note também que, se uma animação deslocar o jogador da sua posição original (por exemplo, se a animação envolver um salto), o component Transform do jogador não será afetado por este deslocamento.

Use o Scene Editor

A forma mais fácil de fazer um jogador executar uma animação é usar o Scene Editor. Use a 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 file. Veja Torne qualquer item smart.

Animações padrão

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

• predefinedEmote: Um nome em 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 scene; 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 na sua roda de emotes padrão, e também podem ser usados em qualquer scene.

• wave

• fistpump

• robot

• raiseHand

• clap

• money

• kiss

• tik

• hammer

• tektonik

• dontsee

• handsair

• shrug

• disco

• dab

• headexplode

💡 Dica: Se um jogador caminhar ou saltar enquanto a animação estiver a ser reproduzida, irá interrompê-la. Se não quiser que isso seja possível, pode congelar o avatar com Input Modifiers durante a duração da animação do avatar.

Animações personalizadas

Use o triggerSceneEmote() para fazer o jogador executar uma animação personalizada, armazenada como um file .glb como parte do asset da scene.

📔 Nota: O nome do file deve terminar em _emote.glb para funcionar como uma animação de avatar.

Esta function recebe um objeto com as seguintes propriedades:

• src: Uma string com um path para o file do emote.

• loop: Se true, a animação fará loop continuamente até o jogador se mover ou a animação ser interrompida. Por padrão, false.

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 caminhar ou saltar enquanto a animação estiver a ser reproduzida, irá interrompê-la. Se não quiser que isso seja possível, pode congelar o avatar com Input Modifiers durante a duração da animação do avatar.

Restringir locomoção

Pode restringir que ações o jogador pode realizar na sua scene. Use isto para congelar o jogador, ou para restringir formas específicas de locomoção, por exemplo, para impedir que o jogador salte ou corra.

Congelar o jogador

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

Use o InputModifier component no engine.PlayerEntity para impedir que as inputs do jogador afetem a locomoção do avatar. O avatar permanecerá parado; o jogador só poderá rodar a camera.

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

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

Tenha em mente as seguintes considerações:

• Enquanto as interações do jogador estiverem desativadas, o seu avatar continua a ser afetado por forças externas, como a gravidade ou plataformas em movimento.

• O InputModifier component só pode ser usado com a engine.PlayerEntity entity. Só pode afetar o jogador atual; não pode afetar outros jogadores.

• Este component só afeta o jogador enquanto o avatar estiver dentro dos limites da sua scene. A sua locomoção deixa de ser restringida assim que sair da scene.

• Enquanto as interações do jogador estiverem desativadas, o jogador não pode executar emotes livremente, mas a scene pode desencadear animações no avatar.

• As inputs do jogador não afetam o avatar, mas os eventos globais de input ainda podem ser escutados pela scene. Pode usar isto para controlar um veículo, ou usar um Virtual Camera para seguir outra entity à medida que se move, tratando-a como um avatar alternativo.

Restringir tipos específicos de locomoção

Em vez de congelar totalmente o jogador, pode restringir certas formas específicas de locomoção do jogador. Isto pode ser usado por razões de gameplay, por exemplo, para preservar a dificuldade de um platformer impedindo double-jump e glide. Estas habilidades até podem ser alternadas dinamicamente como mecânica de jogo, por exemplo, dando ao jogador uma barra de stamina e impedindo-o de correr quando esta se esgota. Também pode ser usado para definir o tom de uma scene, por exemplo, impedindo correr ou saltar num local que se pretende ser sereno. O InputModifier inclui as seguintes opções:

• disableWalk: O jogador não pode caminhar lentamente (premindo control). Se o jogador tentar caminhar, irá jogging ou correr em vez disso, se permitido.

• disableRun: O jogador não pode correr (premindo shift). Se o jogador tentar correr, irá jogging em vez disso, se permitido.

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

• disableJump: O jogador não pode saltar.

• disableEmote: O jogador não pode executar emotes voluntariamente. A scene consegue desencadear animações no avatar do jogador.

• disableDoubleJump: O jogador não pode fazer double-jump.

• disableGliding: O jogador não pode planar.

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,
		disableDoubleJump: true,
		disableGliding: true
	}),
})

Sintaxe avançada

Para usar o component sem quaisquer helpers, 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,
		},
	},
})

Definições de locomoção

Pode afetar a locomoção do jogador, como a sua velocidade de corrida, altura de salto e muito mais. Isto pode ser alterado dinamicamente, por exemplo, para permitir que um jogador recolha um aumento temporário de velocidade ao interagir com um item, ou para desativar a capacidade de saltar do jogador durante um curto período de tempo.

Para fazer isto, 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 a que o jogador caminha, em metros por segundo. No desktop client, os jogadores caminham premindo a tecla control.

• jogSpeed: A velocidade a que o jogador faz jogging, em metros por segundo. Esta é a forma padrão como o jogador se move.

• runSpeed: A velocidade a que o jogador corre, em metros por segundo. No desktop client, os jogadores correm premindo a tecla shift.

• jumpHeight: A altura a que o jogador salta, em metros.

• runJumpHeight: A altura a que o jogador salta depois de correr, em metros.

• hardLandingCooldown: O cooldown após uma aterragem forte, em segundos. Este é o tempo que o jogador tem de esperar antes de poder mover-se novamente após aterrar de uma queda alta.

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

• walkSpeed: 1,5 m/s

• jogSpeed: 8 m/s

• runSpeed: 10 m/s

• glideSpeed: 6 m/s

• jumpHeight: 1 m

• runJumpHeight: 1,5 m

• doubleJump: 2 m

• hardLandingCooldown: 0,75 s

💡 Dica: Nenhuma destas propriedades pode ser inferior a 0. Se definir uma delas com um valor negativo, será limitado a 0. Definir estes valores para zero terá o mesmo efeito que usar o InputModifier para bloquear o uso de certas teclas.

Só pode afetar a locomoção do jogador se ele estiver dentro dos limites da scene. Para afetar os avatares de outros jogadores, tem de executar o code que afeta a sua locomoção na própria instance deles.

Pode criar um smart wearable que faz com que o jogador corra sempre mais depressa ou salte mais alto. Se tanto a scene como um smart wearable definirem valores diferentes para estes parâmetros, os valores da scene são sempre os utilizados.

Para garantir que ninguém tem vantagens injustas numa scene de parkour, pode impor os parâmetros padrão adicionando explicitamente os seus valores padrão na sua scene:

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 Avatar modifier

Os avatares comportam-se e parecem consistentes ao longo de Decentraland à medida que caminham pelas scenes. No entanto, pode adicionar um AvatarModifierArea a uma região da sua scene para afetar a forma como os avatares dos jogadores se comportam quando entram nessa área.

❗Aviso Limite, por favor, a quantidade de AvatarModifierAreas que usa na sua scene a apenas algumas. Se usar demasiadas, isso pode ter um impacto significativo no desempenho.

Colocar Avatar Modifier Areas

Adicione uma entity com um AvatarModifierArea component e posicione esta entity 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, tem de fornecer o seguinte:

• area: Tamanho da área do modifier

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

Os modifiers suportados são:

• AvatarModifierType.AMT_HIDE_AVATARS

• AvatarModifierType.AMT_DISABLE_PASSPORTS

Todos os efeitos de um AvatarModifierArea só têm lugar dentro da região da sua área. Os jogadores voltam ao normal quando saem da área.

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

Os efeitos de um AvatarModifierArea são calculados localmente para cada jogador. Pode ter um AvatarModifierArea que só está presente na scene para alguns jogadores e não para outros. Por exemplo, poderia criar um jogo "marco polo", em que apenas um jogador na scene tem uma área de modifier que oculta todos os outros jogadores. Todos os outros jogadores que não têm esta área de modifier na sua versão local da scene podem ver-se uns aos outros normalmente.

Se a área ocultar avatares, então os jogadores que não têm a área na sua versão local da scene verão todos os avatares normalmente, até mesmo aqueles que se veem a si próprios como ocultos. Os jogadores que têm a área irão ver-se a si próprios e a todos os outros avatares como afetados pela área quando entrarem nela.

📔 Nota: As áreas de modifier de avatar são afetadas pelo position e rotation do component Transform da entity anfitriã, mas não são afetadas pelo scale.

📔 Nota: A AvatarModifierAreacomponent tem de ser importado via

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

Consulte Imports para saber como lidar com isso facilmente.

Ocultar avatares

Quando um jogador entra numa AvatarModifierArea que tem o modifier AvatarModifierType.AMT_HIDE_AVATARS o avatar do jogador deixa de ser renderizado. Isto aplica-se tanto ao jogador na vista em 3rd person como 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),
})

Isto permite substituir o avatar padrão de Decentraland por qualquer avatar personalizado que queira mostrar na sua scene. Note que, se quiser ver outros jogadores com avatares personalizados, deve tratar da sincronização das posições dos jogadores por si próprio.

Desativar Popup do Passport

Quando um jogador entra numa AvatarModifierArea que tem o modifier AvatarModifierType.AMT_DISABLE_PASSPORTS modifier, clicar neles deixa de abrir a UI do passport que mostra a bio do jogador, o inventory, 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),
})

Isto é especialmente útil em jogos em que abrir acidentalmente esta UI possa interromper o fluxo do jogo, por exemplo num jogo de tiro multiplayer.

Excluir Avatares

Pode excluir uma lista de jogadores de serem afetados por uma área de modifier adicionando os seus Ids de jogador a um array na excludeIds property da área de modifier.

Este exemplo oculta todos os avatares numa área, exceto os dos jogadores com IDs específicos. Poderia usar isto, por exemplo, num evento ao vivo, para mostrar apenas os anfitriões do evento no palco e ocultar quaisquer outros jogadores que subam para o 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),
})

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

As áreas de modifier funcionam localmente na instance de cada jogador. A lista de IDs excluídos pode ser diferente para cada jogador. No exemplo abaixo, cada jogador exclui o seu próprio ID de um modifier que oculta avatares, para que cada um veja o 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 que entram ou saem de uma área), certifique-se de que a lista é mantida em ordem. Faça um .sort() no array, para que a lista permaneça na mesma ordem de cada vez que for passada. Desta forma, apenas as alterações à lista são calculadas. Caso contrário, isso pode ter um impacto significativo no desempenho da scene.

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

Depurar áreas de modifier

Pode ser difícil saber exatamente que partes da scene as suas áreas de modifier abrangem com base no code. O feedback visual ajuda bastante a confirmar que estão bem colocadas.

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

📔 Nota: As áreas de modifier não são afetadas pela scale property do transform; o seu tamanho é baseado na sua 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 modifier, a cabeça ou o torso do jogador têm de 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 consegue contornar facilmente a área ao saltar.

📔 Nota: A área completa deve caber dentro dos limites da sua scene.

Alterar a aparência de um avatar

Não pode alterar quais os wearables que o avatar do jogador está a usar, mas pode em vez disso substituir o avatar do jogador por um NPC avatar que pode personalizar totalmente.

Consulte NPC Avatars para mais detalhes.

📔 Nota: Para permitir que o jogador tenha controlo total sobre esse avatar, deve escutar eventos de button para detetar quando premem um button e, em seguida, desencadear a animação correspondente no NPC avatar. Veja Button Events para mais detalhes.

A fluidez do controlo pode não ser perfeita ao fazer isto; talvez queira usar isto apenas em casos muito específicos.