Avatar del jugador

Aprende cómo controlar el avatar del jugador

Hay varias formas de controlar el avatar del jugador y cambiar la experiencia de juego para tus jugadores.

Para tratar con avatares que no son jugadores, ver NPC Avatars.

Mover jugador

💡 Consejo: La forma más fácil de mover al jugador es usar el Scene Editor in Creator Hub. Usa la opción sin código Mover jugador o el Mover jugador aquí Actions, ver Make any item smart.

Para cambiar la posición del jugador en la escena, usa la movePlayerTo() función. Esta función toma un objeto con tres propiedades:

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

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

• avatarTarget: (opcional) La dirección hacia la que debe mirar el avatar, expresada como un Vector3 que representa las coordenadas de un punto en el espacio a la que mirar. Si no se proporciona ningún valor, el avatar mantendrá la misma rotación que tenía 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 la nueva posición.

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

import { movePlayerTo } from '~system/RestrictedActions'

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

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

// dar comportamiento a la entidad
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Click' },
	},
	function () {
		// reaparición del 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, ver Teleports.

La movePlayerTo() función es awaitable, por lo que si el movimiento tiene una duración, puedes usar await para esperar a que el jugador alcance 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 función nunca se resolverá. Puedes prevenir este comportamiento deshabilitando todas las entradas mientras la transición está en curso usando el InputModifier componente, ver 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 () {

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

		// mover 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 success propiedad para saber si el movimiento fue interrumpido (por ejemplo, por movimiento de entrada) o se completó 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 en 3.ª persona) como por cualquier otro jugador alrededor.

Las animaciones controladas por el jugador son sobrescritas por las animaciones de locomoción predeterminadas, como caminar y saltar. Por lo tanto, las animaciones reproducidas por la escena solo se reproducen mientras el jugador esté inmóvil. Si el jugador camina o salta, cualquier animación se interrumpirá.

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

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

Usa el Scene Editor

La forma más fácil de hacer que un jugador realice una animación es usar el Scene Editor. Usa la opción sin código Play Emote acción para reproducir una animación predeterminada, o la Play Custom Emote acción para reproducir una animación desde un archivo. Ver Make any item smart.

Default animations

Usa la triggerEmote() función para ejecutar una de las animaciones predeterminadas que los jugadores pueden reproducir en cualquier lugar de Decentraland. Esta función toma 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 al 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 de avatar.

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

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

• loop: Si es true, la animación se reproducirá en bucle 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 al avatar con Input Modifiers durante la duración de la animación del avatar.

Restrict locomotion

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 del jugador, por ejemplo para evitar que el jugador salte o corra.

Congelar al jugador

Puedes congelar al jugador para que ninguna de las teclas de entrada pueda mover al 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 debe ser interrumpida por movimiento, o mientras una Virtual Camera apunta lejos del avatar y no quieres que el jugador se mueva a ciegas.

Usa la InputModifier componente en el engine.PlayerEntity para evitar que las entradas del jugador afecten la locomoción del avatar. El avatar permanecerá inmóvil, 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 lo siguiente:

• Mientras las interacciones del jugador estén deshabilitadas, su avatar sigue siendo afectado por fuerzas externas, como la gravedad o plataformas en movimiento.

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

• Este componente 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 global input events todavía pueden ser escuchados por la escena. Podrías usar estos para controlar un vehículo, o usar un Virtual Camera para seguir a otra entidad mientras se mueve, tratándola como un avatar alternativo.

Restringir tipos específicos de locomoción

En lugar de congelar completamente al jugador, puedes restringir ciertas formas específicas de locomoción del jugador. El InputModifier incluye las siguientes opciones:

• disableWalk: El jugador no puede caminar despacio (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.

• disableAll: El jugador no puede realizar ninguna de las acciones anteriores.

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

Sintaxis avanzada

Para usar el componente 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 de carrera, altura de salto y más. Esto puede alterarse dinámicamente, por ejemplo para permitir que un jugador obtenga un impulso de velocidad temporal al interactuar con un objeto, o para deshabilitar la capacidad del jugador de saltar por un breve periodo.

Para hacer esto, añade un AvatarLocomotionSettings componente 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 la que el jugador se mueve.

• 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 salta el jugador, en metros.

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

• hardLandingCooldown: El tiempo de enfriamiento después de una caída fuerte, en segundos. Este es el tiempo que el jugador debe esperar antes de poder moverse nuevamente tras aterrizar desde una caída alta.

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

• walkSpeed: 1.5 m/s

• jogSpeed: 8 m/s

• runSpeed: 10 m/s

• jumpHeight: 1 m

• runJumpHeight: 1.5 m

• hardLandingCooldown: 0.75 s

💡 Consejo: Ninguna de estas propiedades puede ser inferior a 0. Si configuras 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 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 diferentes para estos parámetros, siempre se usarán los valores de la escena.

Para asegurarte de que nadie tenga ventajas injustas en una escena de parkour, puedes imponer los parámetros predeterminados agregando 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.

Colocación de Avatar Modifier Areas

Agrega una entidad con un AvatarModifierArea componente y posiciona esta entidad usando un Transform componente.

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 componente, 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 compatibles 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 afecta solo a los jugadores que están dentro del área. Entrar en el área no afecta cómo son percibidos 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 tienen el área en su versión local de la escena verán todos los avatares normalmente, incluso aquellos que se experimentan a sí mismos como ocultos. Los jugadores que sí tienen el área experimentarán que ellos mismos y todos los demás avatares están 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 entidad anfitriona, pero no se ven afectadas por la scale.

📔 Nota: El AvatarModifierAreacomponente debe importarse vía

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

Ver Imports para cómo manejarlas fácilmente.

Ocultar avatares

Cuando un jugador entra en un AvatarModifierArea que tiene el AvatarModifierType.AMT_HIDE_AVATARS modificador, el avatar del jugador deja de renderizarse. Esto se aplica tanto para el jugador en vista en 3.ª persona, como para 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 con 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 sincronizar las posiciones de los jugadores.

Deshabilitar el popup de pasaporte

Cuando un jugador entra en un AvatarModifierArea que tiene el AvatarModifierType.AMT_DISABLE_PASSPORTS modificador, al hacer clic en ellos ya no se abre la UI del pasaporte que muestra la biografía del jugador, 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 del juego, por ejemplo en un juego multijugador de disparos.

Excluir avatares

Puedes excluir una lista de jugadores de verse afectados por un área modificadora añadiendo 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 salte 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 las IDs de los jugadores estén escritas 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 excluidas puede ser diferente para cada jugador. En el ejemplo abajo, cada jugador excluye su propia 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 excluidas va a cambiar periódicamente (por ejemplo, basado en jugadores que entran o salen de un área), asegúrate de que la lista se mantenga en orden. Realiza un .sort() en el array, de modo que la lista permanezca en el mismo orden cada vez que se pase. De esta forma, 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 para confirmar que están bien ubicadas.

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

📔 Nota: Las áreas modificadoras no se ven afectadas por la scale propiedad del transform, 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 debe 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 intercambiar el avatar del jugador por un avatar NPC que puedas personalizar por completo.

Ver NPC Avatars para más detalles.

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

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