Avatar do Jogador

Aprenda como controlar o avatar do jogador

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

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

Mover jogador

💡 Dica: A forma mais fácil de mover o jogador é usar o Scene Editor no Creator Hub. Use o no-code Mover jogador ou o Move player here Actions, veja Make any 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 onde fazer a câmera 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 câmera manterá a mesma rotação de antes do movimento.

• avatarTarget: (opcional) A direção para onde 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 do movimento. Se o jogador estiver no modo de câmara em 1.ª pessoa, a rotação da câmera e do avatar é a mesma.

• duration: (opcional) Quanto tempo a transição deve demorar, em segundos. Se nenhum valor for fornecido, a transição ocorrerá instantaneamente. Se for fornecida uma duration, o avatar vai andar 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 entidade
const myEntity = engine.addEntity()
MeshRenderer.setBox(myEntity)
MeshCollider.setBox(myEntity)

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

// dar comportamento à entidade
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	function () {
		// reaparecer 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 ou transições de câmera.

📔 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.

A movePlayerTo() function é awaitable, por isso, se o movimento tiver uma duration, 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 duration da transição, a transição será interrompida e a movePlayerTo function nunca será resolvida. Pode evitar este comportamento desativando todas as entradas enquanto a transição está em progresso, 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 entradas
		InputModifier.create(engine.PlayerEntity, {
			mode: InputModifier.Mode.Standard({
				disableAll: true,
			}),
		})

		// mover 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 entradas
		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 de entrada) ou concluído com sucesso.

Reproduzir animações

Pode fazer com que o jogador execute uma animação como parte do código da scene. Isso pode ajudar a proporcionar mais imersão e também pode ajudar a comunicar o que os outros jogadores estão a fazer entre si. As animações do avatar são vistas tanto pelo jogador (em vista de 3.ª pessoa) como por quaisquer outros jogadores à volta.

As animações controladas pelo jogador são substituídas pelas animações de locomoção padrão, como andar e saltar. Por isso, as animações reproduzidas pela scene só são reproduzidas enquanto o jogador estiver parado. Se o jogador andar ou saltar, quaisquer animações serã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 são limitados 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 componente Transform do jogador não será afetado por esse deslocamento.

Usar o Scene Editor

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

Animações padrão

Use a 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 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 as ações do jogador na sua scene; todos estes são valores válidos para o predefinedEmote campo:

• 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 no seu seletor 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 andar 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 a triggerSceneEmote() para fazer com que o jogador execute uma animação personalizada, armazenada como um ficheiro .glb como parte do asset da scene.

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

Esta function recebe um objeto com as seguintes propriedades:

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

• loop: Se true, a animação fará loop continuamente até o jogador se mover ou a animação ser interrompida. False por defeito.

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 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 executar 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 consiga mover o avatar. Isto pode ser útil para muitos mecanismos 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 a InputModifier component no engine.PlayerEntity para impedir que as entradas do jogador afetem a locomoção do avatar. O avatar permanecerá parado; o jogador só poderá rodar a câmera.

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

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

Tenha em conta as seguintes considerações:

• Enquanto as interações do jogador estão desativadas, o seu avatar ainda é afetado por forças externas, como a gravidade ou plataformas em movimento.

• A InputModifier component só pode ser usado com a entidade engine.PlayerEntity . 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 locomoção deixa de ser restringida assim que ele sai da scene.

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

• As entradas do jogador não afetam o avatar, mas os global input events ainda podem ser escutados pela scene. Pode usá-los para controlar um veículo, ou usar um Virtual Camera para seguir outra entidade à medida que esta se move, tratando-a como um avatar alternativo.

Restringir tipos específicos de locomoção

Em vez de congelar completamente o jogador, pode restringir 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 capacidades poderiam até ser ativadas ou desativadas dinamicamente como mecanismo de jogo, por exemplo dando ao jogador uma barra de stamina e impedindo-o de correr quando esta se esgota. Também poderia ser usado para definir o tom de uma scene, por exemplo impedir correr ou saltar num local que pretende ser sereno. O InputModifier inclui as seguintes opções:

• disableWalk: O jogador não pode andar devagar (premindo control). Se o jogador tentar andar, irá trotar ou correr em vez disso, se for permitido.

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

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

• disableJump: O jogador não pode saltar.

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

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

• disableGliding: O jogador não pode fazer glide.

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 velocidade de corrida, a altura do 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 do jogador de saltar 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 anda, em metros por segundo. No cliente desktop, os jogadores andam premindo a tecla control.

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

• runSpeed: A velocidade a que o jogador corre, em metros por segundo. No cliente desktop, 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 pesada, em segundos. Este é o tempo que o jogador tem de esperar antes de poder mover-se novamente depois de aterrar de uma queda alta.

Como referência, aqui estão os valores padrão para essas 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 para 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 código que afeta a locomoção deles na sua própria instância.

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 usados.

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 modificador de avatar

Os avatares comportam-se e têm uma aparência consistente ao longo de Decentraland enquanto atravessam 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 Por favor limite a quantidade de AvatarModifierAreas que usa na sua scene a apenas algumas. Se usar demasiadas, pode ter um impacto significativo no desempenho.

Colocar Avatar Modifier Areas

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

• area: Tamanho da área do modificador

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

Os modificadores suportados são:

• AvatarModifierType.AMT_HIDE_AVATARS

• AvatarModifierType.AMT_DISABLE_PASSPORTS

Todos os efeitos de um AvatarModifierArea só ocorrem 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 fazer um jogo de "marco polo", em que apenas um jogador na scene tem uma área de modificador que esconde todos os outros jogadores. Todos os outros jogadores que não têm esta área de modificador na sua versão local da scene podem ver-se mutuamente normalmente.

Se a área esconder avatares, então os jogadores que não tiverem a área na sua versão local da scene verão todos os avatares normalmente, mesmo aqueles que se experienciam como escondidos. Os jogadores que tiverem a área experienciar-se-ão a si próprios e a todos os outros avatares como afetados pela área quando entrarem nela.

📔 Nota: As áreas de modificador de avatar são afetadas pela position e rotation do componente Transform da sua entidade anfitriã, mas não são afetadas pelo scale.

📔 Nota: O AvatarModifierAreacomponent deve ser importado via

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

Veja Imports para saber como lidar facilmente com isto.

Ocultar avatares

Quando um jogador entra num AvatarModifierArea que tem o modificador AvatarModifierType.AMT_HIDE_AVATARS , o avatar do jogador deixa de ser renderizado. Isto aplica-se tanto ao jogador em vista de 3.ª pessoa 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-lhe 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, deverá tratar da sincronização das posições dos jogadores por conta própria.

Desativar janela pop-up do Passport

Quando um jogador entra num AvatarModifierArea que tem o modificador AvatarModifierType.AMT_DISABLE_PASSPORTS modificador, clicar neles já não abre a UI do passport que mostra a bio do jogador, o 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),
})

Isto é especialmente útil em jogos onde abrir acidentalmente esta UI pode interromper o fluxo do jogo, por exemplo num jogo de tiro multijogador.

Excluir Avatares

Pode excluir uma lista de jogadores de serem afetados por uma área de modificador adicionando os seus player Ids a um array na propriedade excludeIds da área de modificador.

Este exemplo oculta todos os avatares numa área, exceto os de 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 saltem 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 player IDs estão todos escritos com letras minúsculas. Use .toLowerCase() se necessário.

As áreas de modificador correm 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 o seu próprio ID de um modificador 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. Execute um .sort() no array, para que a lista permaneça na mesma ordem sempre que for passada. Desta forma, apenas as alterações à lista são calculadas. Caso contrário, isto 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 modificador

Pode ser difícil saber exatamente que partes da scene as suas áreas de modificador cobrem com base no código. O feedback visual ajuda bastante a confirmar que 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 forma de box e defina a scale com o mesmo tamanho que a area da área do modificador.

📔 Nota: As áreas de modificador não são afetadas pela scale property da transform, o seu tamanho baseia-se 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 modificador, a cabeça ou o tronco do jogador devem 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 evitar facilmente a área saltando.

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

Alterar a aparência de um avatar

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

Veja NPC Avatars para mais detalhes.

📔 Nota: Para permitir que o jogador tenha controlo total sobre esse avatar, deve ouvir eventos de botão para detetar quando premem um botão e, em seguida, desencadear a animação correspondente no avatar do NPC. 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.