Avatares NPC

Mostrar y controlar avatar NPC

Mostrar un avatar como una entidad en una escena.

💡 Consejo: Prueba el librería NPC Toolkit para una experiencia más sencilla al tratar con NPCs, especialmente si necesitas interactuar mediante un árbol de conversación.

Crear un avatar

El siguiente fragmento crea un avatar con wearables y forma de cuerpo aleatorios, y nombre "NPC".

const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar)

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})

Al pasar datos para generar un AvatarShape, los siguientes campos son obligatorios:

• id: (requerido) Identificador interno para el Avatar

También están disponibles los siguientes campos opcionales:

• name: Nombre para mostrar sobre la cabeza del Avatar. Predeterminado: "NPC".

• bodyShape: Cadena que define qué forma de cuerpo usar. Las opciones válidas son 'urn:decentraland:off-chain:base-avatars:BaseMale' y 'urn:decentraland:off-chain:base-avatars:BaseFemale'.

• wearables: Array con la lista de URNs de wearables que el avatar lleva puestos actualmente. Si los wearables entran en conflicto (por ejemplo, dos son sombreros), el último en la lista reemplaza al otro.

• emotes: Array con la lista de URNs de emotes NFT que el avatar puede reproducir

• eyeColor: Color3 para el color de los ojos (cualquier color es válido)

• skinColor: Color3 para el color de la piel (cualquier color es válido)

• hairColor: Color3 para el color del cabello (cualquier color es válido)

• talking: Si true, muestra un conjunto de barras verdes junto al nombre, como cuando los jugadores usan chat de voz en el mundo.

• 💡 Consejo: Ver tipos de color para más detalles sobre cómo configurar colores.

📔 Nota: El AvatarShapecomponente debe importarse vía

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

Vea Imports para ver cómo manejar estos fácilmente.

📔 Nota: Los campos URN deben seguir el mismo formato usado para NFTShapes: urn:decentraland:<CHAIN>:<CONTRACT_STANDARD>:<CONTRACT_ADDRESS>:<TOKEN_ID>

Animations

Los avatares reproducen animaciones inactivas predeterminadas mientras están quietos.

Para reproducir animaciones en el avatar, establece el expressionTriggerId string al nombre de la animación que quieras reproducir.

const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
	id: '',
	emotes: [],
	wearables: [],
	expressionTriggerId: 'robot',
})

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})

El expressionTriggerId el campo admite todas las animaciones predeterminadas, así como animaciones personalizadas desde un archivo de escena, e incluso URNs de emotes que estén publicados en el Marketplace.

Animaciones en bucle

Las animaciones en un AvatarShape se reproducen una vez; si quieres que el avatar continúe repitiendo una animación, deberías crear un sistema que le indique reproducir la animación nuevamente cada un par de segundos.

Usa la expressionTriggerTimestamp para volver a reproducir el mismo emote. El valor de este campo es un timestamp lamport, lo que significa que no es un valor de tiempo, sino un índice que se incrementa en 1 por cada repetición del emote.

Así que la primera vez que reproduces un emote, estableces expressionTriggerTimestamp a 0. Para reproducir el emote otra vez, debes actualizar este valor a 1. Así es como el engine sabe que se trata de una instrucción nueva, y no de una instrucción que ya procesó.

El siguiente fragmento crea un sistema que ejecuta el mismo emote cada 2 segundos:

const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
	id: '',
	emotes: [],
	wearables: [],
	expressionTriggerId: 'clap',
    expressionTriggerTimestamp: 0
})

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})

let clapTimer = 0
let emoteDuration = 2  // 2 segundos

// system
engine.addSystem((dt: number) => {
    clapTimer += dt
      
    if (clapTimer >= emoteDuration) {
        // Trigger the clap emote
        AvatarShape.getMutable(wearable).expressionTriggerTimestamp =+ 1 
        
        clapTimer = 0 // Reset timer
    }
})

💡 Consejo: Debes conocer la duración del emote y hacer que esa sea la duración del sistema. Si creas un emote que mantiene al avatar inmóvil en una misma pose, es recomendable que la duración del emote sea más larga que la del sistema. De esa manera, puedes asegurarte de que no haya artefactos al terminar y reiniciar la animación.

Copiar wearables del jugador

El siguiente fragmento cambia los wearables y otras características de un avatar NPC para que coincidan con los que el jugador lleva puestos actualmente. Esto podría usarse en una escena como un maniquí, para mostrar un wearable o emote en particular combinado con el atuendo actual del jugador.

import { getPlayer } from '@dcl/sdk/src/players'


export function swapAvatar(avatar: Entity) {

  let userData = getPlayer()
  console.log(userData)

  if (!userData || !userData.wearables) return

  const mutableAvatar = AvatarShape.getMutable(avatar)

  mutableAvatar.wearables = userData.wearables
  mutableAvatar.bodyShape = userData.avatar?.bodyShapeUrn
  mutableAvatar.eyeColor = userData.avatar?.eyesColor
  mutableAvatar.skinColor = userData.avatar?.skinColor
  mutableAvatar.hairColor = userData.avatar?.hairColor
  
}

Mostrar solo wearables

Usa la show_only_wearables campo para mostrar solo los wearables listados de un avatar. El resto del cuerpo del avatar será invisible.

const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
	id: '',
	emotes: [],
	wearables: [
    'urn:decentraland:matic:collections-v2:0x90e5cb2d673699be8f28d339c818a0b60144c494:0'
  ],
	show_only_wearables: true,
})

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})

Esto es útil para mostrar wearables, por ejemplo en una tienda.

💡 Consejo: Si un wearable es bastante pequeño, intenta configurar el scale del Transform a un valor más grande.

Adjuntar una entidad a un NPC

Puedes usar la AvatarAttach para fijar una entidad a uno de los huesos de un avatar NPC, por ejemplo para que el NPC sostenga un objeto en la mano. La entidad se moverá junto con el avatar cuando éste se anime.

Para usar esta función, usa la id propiedad en el AvatarShape para asignar un id arbitrario a este avatar, y luego referencia ese id en el AvatarAttach. El id puede ser cualquier cadena que desees.

// Create NPC, with an ID
const myAvatar = engine.addEntity()
Transform.create(myAvatar, {
  position: Vector3.create(8, 0.25, 8),
})
AvatarShape.create(myAvatar, {
  id: "my-avatar-id", 
  wearables: [],
  emotes: []
})

// Create object to attach to NPC
const attachedEntity = engine.addEntity()
Transform.create(attachedEntity, {
    position: Vector3.create(4, 2, 4),
    scale: Vector3.create(0.15,0.15,0.15)
})
MeshRenderer.setBox(attachedEntity)
Material.setBasicMaterial(attachedEntity, { diffuseColor: Color4.Blue() })
AvatarAttach.create(attachedEntity, {
    avatarId: "my-avatar-id",
    anchorPointId: AvatarAnchorPointType.AAPT_LEFT_HAND
})

Obtén más información sobre el AvatarAttach componente aquí.