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, vea Avatares NPC.

Mover al 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 al jugador o el Mover jugador aquí Acciones, vea Haz cualquier elemento inteligente.

Para cambiar la posición del jugador en la escena, usa la movePlayerTo() función. 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 debe mirar la cámara, expresada como un Vector3 que representa las coordenadas de un punto en el espacio a mirar. Si no se proporciona un 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 mirar. Si no se proporciona un valor, el avatar mantendrá la misma rotación que tenía antes de moverse. Si el jugador está en modo cámara en primera persona, la rotación de la cámara y del avatar es la misma.

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 () {
		// reaparecer 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 de forma instantánea, sin pantallas de confirmación ni transiciones de cámara.

📔 Nota: Los jugadores solo pueden ser movidos si ya se encuentran 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, vea Teleports.

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 las ve tanto el jugador (en vista en 3.ª persona) como 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 reproducen 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 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 este 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. Vea Haz cualquier elemento inteligente.

Animaciones predeterminadas

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 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 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 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 al avatar con Input Modifiers durante la duración de la animación del avatar.

Restringir la locomoción

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

Congelar al jugador

Puedes congelar al jugador de modo que ninguna de las teclas de entrada pueda mover al avatar. Esto puede ser útil para muchas mecánicas de juego. También es buena práctica congelar a un jugador mientras realiza una animación importante que no debe 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 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 las siguientes consideraciones:

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

• El InputModifier 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 tan pronto como abandone 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 de entrada globales aún pueden ser escuchados por la escena. Podrías usarlos 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 por defecto). 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 de forma voluntaria. 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 modificarse dinámicamente, por ejemplo para permitir que un jugador recoja un impulso de velocidad temporal al interactuar con un objeto, o para desactivar la capacidad del jugador de saltar por un corto período de tiempo.

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 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 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 tras un aterrizaje fuerte, en segundos. Este es el tiempo que el jugador debe esperar antes de poder moverse nuevamente después de aterrizar tras 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 menor que 0. Si estableces una de ellas en un valor negativo, se ajustará 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 este se encuentra dentro de los límites de la escena. Para afectar a 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 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 agregando explícitamente sus valores por defecto 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 forma consistente en todo Decentraland al caminar por las escenas. Sin embargo, puedes añadir 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

Añade una entidad con un AvatarModifierArea componente y posiciona esa 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 soportados 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 esté presente en la escena solo 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 tengan esta área modificadora en su versión local de la escena podrán verse entre sí con normalidad.

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 con normalidad, incluso aquellos que se experimentan a sí mismos como ocultos. Los jugadores que sí tengan el área experimentará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 entidad anfitriona, pero no se ven afectadas por la scale.

📔 Nota: El AvatarModifierAreacomponente debe importarse vía

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

Vea Imports para cómo manejarlos 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 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 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 de sincronizar las posiciones de los jugadores tú mismo.

Desactivar la ventana emergente del 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 de pasaporte que muestra la biografía 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 del juego, por ejemplo en un juego multijugador de disparos.

Excluir avatares

Puedes excluir una lista de jugadores de ser afectados por un área modificadora añadiendo sus Ids de jugador a un array en la propiedad excludeIds 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 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 siguiente, cada jugador excluye su propio ID de un modificador que oculta avatares, de modo que cada uno vea su propio avatar y ninguno más.

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 los jugadores entren o salgan de un área), asegúrate de que la lista se mantenga ordenada. Realiza un .sort() en el array, para que la lista permanezca en el mismo orden cada vez que se pase. De esta manera, solo se computan 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 solo 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 tendrá 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 el avatar del jugador, pero en su lugar puedes intercambiar el avatar del jugador por un avatar NPC que puedas personalizar por completo.

Vea Avatares NPC para más detalles.

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

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