Avatar del jugador

Aprende a controlar el avatar del jugador

Hay varias maneras en que puedes controlar el avatar del jugador y cambiar la experiencia de juego para tus jugadores.

Para tratar con avatares que no son jugadores, consulta Avatares NPC.

Mover al jugador

💡 Consejo: La forma más sencilla de mover al jugador es usar el Scene Editor en Creator Hub. Usa el Mover al jugador sin código o el Mover al jugador aquí Acciones, consulta.

Convierte cualquier item en smart movePlayerTo() function. Esta función recibe un objeto con tres propiedades:

• newRelativePosition: Dónde posicionar al jugador, expresado como un Vector3.

• cameraTarget: (opcional) La dirección hacia la que hacer que mire la cámara, expresada como un Vector3 que representa las coordenadas de un punto en el espacio al que mirar. Si no se proporciona ningún valor, la cámara mantendrá la misma rotación que antes de moverse.

• avatarTarget: (opcional) La dirección hacia la que hacer que mire el avatar, expresada como un Vector3 que representa las coordenadas de un punto en el espacio al que mirar. Si no se proporciona ningún valor, el avatar mantendrá la misma rotación que antes de moverse. Si el jugador está en modo de cámara en primera persona, la rotación de la cámara y del avatar es la misma.

• duration: (opcional) Cuánto debe durar la transición, en segundos. Si no se proporciona ningún valor, la transición ocurrirá instantáneamente. Si se proporciona una duración, el avatar caminará o correrá hasta esta nueva posición.

📔 Nota: Durante la transición, el avatar no se ve afectado por colliders, así que puede atravesar objetos.

import { movePlayerTo } from '~system/RestrictedActions'

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

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

// darle comportamiento a la entity
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	function () {
		// reaparecer al jugador
		movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
		})
	}
)

El movimiento del jugador ocurre instantáneamente, sin pantallas de confirmación ni transiciones de cámara.

📔 Nota: Los jugadores solo pueden ser movidos si ya están dentro de los límites de la escena, y solo pueden ser movidos a ubicaciones que estén dentro de los límites de la escena. No puedes usar movePlayerTo() para transportar a un jugador a otra escena. Para mover a un jugador a otra escena, consulta Teleports.

La movePlayerTo() function es awaitable, así que si el movimiento tiene una duración, puedes usar await para esperar a que el jugador llegue a su 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,
		})
	}
)

Si el jugador intenta moverse durante la duración de su transición, la transición se interrumpirá y la movePlayerTo function nunca se resolverá. Puedes evitar este comportamiento deshabilitando todas las entradas mientras la transición está en curso usando el InputModifier component, consulta Restringir locomoción.

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

		// deshabilitar todas las entradas
		InputModifier.create(engine.PlayerEntity, {
			mode: InputModifier.Mode.Standard({
				disableAll: true,
			}),
		})

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

		// habilitar todas las entradas
		InputModifier.deleteFrom(engine.PlayerEntity)
	}
)

📔 Nota: Además, el resultado del await puede almacenarse para evaluar su éxito property y saber si el movimiento fue interrumpido (por ejemplo, por el movimiento de entrada) o completado con éxito.

Reproducir animaciones

Puedes hacer que el jugador realice una animación como parte del código de la escena. Esto puede ayudar a proporcionar más inmersión, y también puede ayudar a comunicar lo que otros jugadores están haciendo entre sí. Las animaciones del avatar son vistas tanto por el jugador (en vista de tercera persona) como por cualquier otro jugador alrededor.

Las animaciones controladas por el jugador son anuladas por las animaciones de locomoción predeterminadas, como caminar y saltar. Por lo tanto, las animaciones reproducidas por la escena solo se ejecutan mientras el jugador está quieto. Si el jugador camina o salta, cualquier animación se interrumpe.

📔 Nota: Los jugadores solo pueden ser animados si ya están dentro de los límites de la escena, no si están en una escena vecina. Los smart wearables pueden reproducir animaciones en cualquier lugar.

Mientras un jugador está realizando una animación, no se ve afectado por colisiones y sus movimientos no están restringidos por la física de la escena. Ten en cuenta también que si una animación desplaza al jugador desde su posición original (por ejemplo, si la animación implica un salto), el componente Transform del jugador no se verá afectado por este desplazamiento.

Usa el Scene Editor

La forma más sencilla de hacer que un jugador realice una animación es usar el Scene Editor. Usa la acción sin código Play Emote para reproducir una animación predeterminada, o la Play Custom Emote para reproducir una animación desde un archivo. Consulta Acciones, consulta.

Animaciones predeterminadas

Usa la triggerEmote() function para ejecutar una de las animaciones predeterminadas que los jugadores pueden reproducir en cualquier parte de Decentraland. Esta función recibe un objeto con una sola propiedad como argumento:

• predefinedEmote: Un nombre de cadena para un 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' })
	}
)

Los siguientes emotes muestran retroalimentación sobre las acciones del jugador en tu escena; todos estos son valores válidos para el predefinedEmote campo:

• buttonDown

• buttonFront

• getHit

• knockOut

• lever

• openChest

• openDoor

• punch

• push

• swingWeaponOneHand

• swingWeaponTwoHands

• throw

• sittingChair1

• sittingChair2

• sittingGround1

• sittingGround2

Estos emotes están disponibles para todos los jugadores en su rueda de emotes predeterminada, y también pueden usarse en cualquier escena.

• wave

• fistpump

• robot

• raiseHand

• clap

• money

• kiss

• tik

• hammer

• tektonik

• dontsee

• handsair

• shrug

• disco

• dab

• headexplode

💡 Consejo: Si un jugador camina o salta mientras reproduce la animación, la interrumpirá. Si no quieres que eso sea posible, puedes congelar el avatar con Input Modifiers durante la duración de la animación del avatar.

Animaciones personalizadas

Usa la triggerSceneEmote() para hacer que el jugador realice una animación personalizada, almacenada como un archivo .glb como parte del asset de la escena.

📔 Nota: El nombre del archivo debe terminar en _emote.glb para funcionar como una animación del avatar.

Esta función recibe un objeto con las siguientes propiedades:

• src: Una cadena con la ruta al archivo del emote.

• loop: Si es true, la animación se repetirá continuamente hasta que el jugador se mueva o la animación se detenga. False por defecto.

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

💡 Consejo: Si un jugador camina o salta mientras reproduce la animación, la interrumpirá. Si no quieres que eso sea posible, puedes congelar el avatar con Input Modifiers durante la duración de la animación del avatar.

Restringir locomoción

Puedes restringir qué acciones puede realizar el jugador en tu escena. Úsalo para congelar al jugador, o para restringir formas específicas de locomoción, por ejemplo para impedir que el jugador salte o corra.

Congelar al jugador

Puedes congelar al jugador para que ninguna de las teclas de entrada pueda mover el avatar. Esto puede ser útil para muchas mecánicas de juego. También es una buena práctica congelar a un jugador mientras realiza una animación importante que no debería ser interrumpida por el movimiento, o mientras una Virtual Camera apunta lejos del avatar y no quieres que el jugador se mueva a ciegas.

Usa la InputModifier component en el engine.PlayerEntity para impedir que las entradas del jugador afecten la locomoción del avatar. El avatar permanecerá quieto, el jugador solo podrá rotar la cámara.

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

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

Ten en cuenta las siguientes consideraciones:

• Mientras las interacciones del jugador están deshabilitadas, su avatar sigue viéndose afectado por fuerzas externas, como la gravedad o las plataformas móviles.

• La InputModifier component solo puede usarse con la engine.PlayerEntity entity. Solo puede afectar al jugador actual, no puede afectar a otros jugadores.

• Este component solo afecta al jugador mientras el avatar esté dentro de los límites de tu escena. Su locomoción deja de estar restringida en cuanto salen de la escena.

• Mientras las interacciones del jugador están deshabilitadas, el jugador no puede realizar emotes libremente, pero la escena puede activar animaciones en el avatar.

• Las entradas del jugador no afectan al avatar, pero los eventos globales de entrada siguen pudiendo ser escuchados por la escena. Podrías usar estos para controlar un vehículo, o usar un Virtual Camera para seguir a otra entity mientras se mueve, tratándola como un avatar alternativo.

Restringir tipos específicos de locomoción

En lugar de congelar por completo al jugador, puedes restringir ciertas formas específicas de locomoción del jugador. Esto podría usarse por razones de gameplay, por ejemplo para preservar la dificultad de un juego de plataformas impidiendo el doble salto y el planeo. Estas habilidades incluso podrían activarse o desactivarse dinámicamente como una mecánica de juego, por ejemplo dando al jugador una barra de resistencia e impidiéndole correr cuando se agote. También podría usarse para establecer el tono de una escena, por ejemplo impidiendo correr o saltar en un lugar que se supone que es sereno. El InputModifier incluye las siguientes opciones:

• disableWalk: El jugador no puede caminar lentamente (presionando control). Si el jugador intenta caminar, en su lugar trotarán o correrán, si está permitido.

• disableRun: El jugador no puede correr (presionando shift). Si el jugador intenta correr, en su lugar trotarán, si está permitido.

• disableJog: El jugador no puede trotar (esta es la velocidad de movimiento predeterminada). Si el jugador intenta trotar, en su lugar correrá o caminará, si está permitido.

• disableJump: El jugador no puede saltar.

• disableEmote: El jugador no puede realizar emotes voluntariamente. La escena puede activar animaciones en el avatar del jugador.

• disableDoubleJump: El jugador no puede realizar un doble salto.

• disableGliding: El jugador no puede planear.

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

Sintaxis avanzada

Para usar el component sin ningún helper, puedes usar la siguiente sintaxis:

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

Configuración de locomoción

Puedes afectar la locomoción del jugador, como su velocidad al correr, la altura del salto y más. Esto puede alterarse dinámicamente, por ejemplo para permitir que un jugador recoja un aumento temporal de velocidad al interactuar con un item, o para deshabilitar la capacidad del jugador de saltar durante un breve período de tiempo.

Para hacer esto, agrega un AvatarLocomotionSettings component al engine.PlayerEntity.

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

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

Las siguientes propiedades están disponibles:

• walkSpeed: La velocidad a la que el jugador camina, en metros por segundo. En el cliente de escritorio, los jugadores caminan presionando la tecla control.

• jogSpeed: La velocidad a la que el jugador trota, en metros por segundo. Esta es la forma predeterminada en que se mueve el jugador.

• runSpeed: La velocidad a la que el jugador corre, en metros por segundo. En el cliente de escritorio, los jugadores corren presionando la tecla shift.

• jumpHeight: La altura a la que el jugador salta, en metros.

• runJumpHeight: La altura a la que el jugador salta después de correr, en metros.

• hardLandingCooldown: El tiempo de espera después de un aterrizaje brusco, en segundos. Es el tiempo que el jugador debe esperar antes de poder moverse de nuevo después de aterrizar tras una caída alta.

Como referencia, aquí están los valores predeterminados de esas propiedades:

• 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

💡 Consejo: Ninguna de estas propiedades puede ser inferior a 0. Si estableces una de ellas con un valor negativo, se limitará a 0. Establecer estos valores en cero tendrá el mismo efecto que usar el InputModifier para bloquear el uso de ciertas teclas.

Solo puedes afectar la locomoción del jugador si está dentro de los límites de la escena. Para afectar los avatares de otros jugadores, debes ejecutar el código que afecta a su locomoción en su propia instancia.

Puedes crear un smart wearable que haga que el jugador siempre corra más rápido o salte más alto. Si tanto la escena como un smart wearable definen valores distintos para estos parámetros, siempre se usan los valores de la escena.

Para asegurarte de que nadie tenga ventajas injustas en una escena de parkour, puedes imponer los parámetros predeterminados añadiendo explícitamente sus valores predeterminados en tu escena:

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

Los avatares se comportan y se ven de manera consistente en todo Decentraland mientras caminan por las escenas. Sin embargo, puedes agregar un AvatarModifierArea a una región de tu escena para afectar cómo se comportan los avatares de los jugadores cuando entran en esa área.

❗Advertencia Por favor, limita la cantidad de AvatarModifierAreas que uses en tu escena a solo un par. Si usas demasiadas, puede tener un impacto significativo en el rendimiento.

Colocar Avatar Modifier Areas

Agrega una entity con un AvatarModifierArea component y posiciona esta entity usando un 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),
})

Al crear un AvatarModifierArea component, debes proporcionar lo siguiente:

• area: Tamaño del área modificadora

• modifiers: Un array que enumera los modificadores a implementar en el área. Esta propiedad usa valores del AvatarModifierType enum.

Los modificadores admitidos son:

• AvatarModifierType.AMT_HIDE_AVATARS

• AvatarModifierType.AMT_DISABLE_PASSPORTS

Todos los efectos de un AvatarModifierArea solo tienen lugar dentro de la región de su área. Los jugadores vuelven a la normalidad cuando salen del área.

Un AvatarModifierArea solo afecta a los jugadores que están dentro del área. Entrar en el área no afecta a cómo se percibe a otros jugadores fuera del área.

Los efectos de un AvatarModifierArea se calculan localmente para cada jugador. Puedes tener un AvatarModifierArea que solo esté presente en la escena para algunos jugadores y no para otros. Por ejemplo, podrías hacer un juego de "marco polo", donde solo un jugador en la escena tiene un área modificadora que oculta a todos los demás jugadores. Todos los demás jugadores que no tienen esta área modificadora en su versión local de la escena pueden verse entre sí normalmente.

Si el área oculta avatares, entonces los jugadores que no tengan el área en su versión local de la escena verán todos los avatares normalmente, incluso aquellos que se perciben a sí mismos como ocultos. Los jugadores que sí tengan el área se percibirán a sí mismos y a todos los demás avatares como afectados por el área cuando entren en ella.

📔 Nota: Las áreas modificadoras de avatar se ven afectadas por la position y rotation del componente Transform de su entity anfitriona, pero no se ven afectadas por la scale.

📔 Nota: El AvatarModifierAreacomponent debe importarse mediante

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

Consulta Imports para ver cómo manejar esto fácilmente.

Ocultar avatares

Cuando un jugador entra en un AvatarModifierArea que tiene el AvatarModifierType.AMT_HIDE_AVATARS modifier, el avatar del jugador deja de renderizarse. Esto se aplica tanto para el jugador en vista de tercera persona como cuando otros jugadores entran en el á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),
})

Esto te permite reemplazar el avatar predeterminado de Decentraland por cualquier avatar personalizado que quieras mostrar en tu escena. Ten en cuenta que si quieres ver a otros jugadores con avatares personalizados, debes encargarte tú mismo de la sincronización de las posiciones de los jugadores.

Deshabilitar el popup de Passport

Cuando un jugador entra en un AvatarModifierArea que tiene el AvatarModifierType.AMT_DISABLE_PASSPORTS modifier, al hacer clic en ellos ya no se abre la UI de passport que muestra la bio del jugador, el inventario, 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),
})

Esto es especialmente útil en juegos donde abrir accidentalmente esta UI podría interrumpir el flujo de la partida, por ejemplo en un juego de disparos multijugador.

Excluir avatares

Puedes excluir una lista de jugadores de verse afectados por un área modificadora agregando sus Ids de jugador a un array en la excludeIds propiedad del área modificadora.

Este ejemplo oculta todos los avatares en un área, excepto los de jugadores con IDs específicos. Podrías usar esto, por ejemplo, en un evento en vivo, para mostrar solo a los anfitriones del evento en el escenario y ocultar a cualquier otro jugador que suba al escenario.

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: Asegúrate de que todos los IDs de jugador estén escritos con letras minúsculas. Usa .toLowerCase() si es necesario.

Las áreas modificadoras se ejecutan localmente en la instancia de cada jugador. La lista de IDs excluidos puede ser diferente para cada jugador. En el ejemplo de abajo, cada jugador excluye su propio ID de un modificador que oculta avatares, de modo que cada uno vea su propio avatar y ningún otro.

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

❗Advertencia Si la lista de IDs excluidos va a cambiar periódicamente (por ejemplo, según entren o salgan jugadores de un área), asegúrate de que la lista se mantenga en orden. Realiza un .sort() en el array, para que la lista permanezca en el mismo orden cada vez que se pasa. De esta manera, solo se calculan los cambios en la lista. De lo contrario, esto puede tener un impacto significativo en el rendimiento de la escena.

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

Depurar áreas modificadoras

Puede ser difícil saber exactamente qué partes de la escena cubren tus áreas modificadoras basándote en el código. La retroalimentación visual ayuda mucho a confirmar que están bien colocadas.

Para verificar las posiciones de un AvatarModifierArea o un CameraModeArea, dale a la entity que lo contiene un MeshRenderer component con una forma de box y establece la escala al mismo tamaño que el area del área modificadora.

📔 Nota: Las áreas modificadoras no se ven afectadas por la scale propiedad de la transformación, su tamaño se basa en su area propiedad.

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 activar los efectos del área modificadora, la cabeza o el torso del jugador deben entrar en el área. No surtirá efecto si solo los pies del jugador están en el área. Asegúrate de que el jugador no pueda evadir fácilmente el área saltando.

📔 Nota: El área completa debe caber dentro de los límites de tu escena.

Cambiar la apariencia de un avatar

No puedes cambiar qué wearables lleva puesto el avatar del jugador, pero en su lugar puedes sustituir el avatar del jugador por un avatar NPC que puedes personalizar por completo.

Consulta Avatares NPC para más detalles.

📔 Nota: Para permitir que el jugador tenga control total sobre ese avatar, deberías escuchar los eventos de botones para detectar cuándo presionan un botón y luego activar la animación correspondiente en el avatar NPC. Consulta Eventos de botones para más detalles.

La fluidez del control puede no ser perfecta al hacer esto; quizá quieras usarlo solo en casos muy específicos.