> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/npc-avatars.md).

# Avatares NPC

Muestra y controla el avatar NPC

Mostrar un avatar como entidad en una escena.

{% hint style="info" %}
**💡 Consejo**: Prueba la biblioteca [NPC Toolkit](https://github.com/decentraland-scenes/dcl-npc-toolkit) para facilitar el trabajo con NPC, especialmente si necesitas interactuar mediante un árbol de conversación.
{% endhint %}

## Crear un avatar

El siguiente fragmento crea un avatar con wearables y una forma corporal aleatorios, y con el nombre "NPC".

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

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

Al pasar datos para generar un `AvatarShape`, se requieren los siguientes campos:

* `id`: (obligatorio) Identificador interno del avatar. Los últimos 4 caracteres del `id` se muestran después del nombre del NPC, en texto atenuado, como el sufijo de la wallet de un jugador. Un `id` de menos de 4 caracteres se muestra `0000`. Asigna a cada NPC un `id` cuyo final se lea bien junto a su nombre, por ejemplo `'guide-0001'`.

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

* `name`: Nombre que se muestra sobre la cabeza del avatar. Valor predeterminado: "NPC". Asígnale una cadena vacía para no mostrar ningún nombre; esto resulta útil si solo quieres un [Avatar Nametag](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/avatar-nametags.md) sobre el NPC.
* `bodyShape`: Cadena que define qué forma corporal se usará. Las opciones válidas son 'urn:decentraland:off-chain:base-avatars:BaseMale' y 'urn:decentraland:off-chain:base-avatars:BaseFemale'.
* `wearables`: Matriz con la lista de URN de los wearables que lleva el avatar. Si hay wearables que entran en conflicto (por ejemplo, si dos son sombreros), el último de la lista reemplaza al otro.
* `emotes`: Matriz con la lista de URN de emotes NFT que el avatar puede reproducir
* `eyeColor`: *Color3* para el color de los ojos (se admite cualquier color)
* `skinColor`: *Color3* para el color de la piel (se admite cualquier color)
* `hairColor`: *Color3* para el color del cabello (se admite cualquier color)
* `talking`: Si *true*, se muestra un conjunto de barras verdes junto al nombre, como cuando los jugadores usan el chat de voz en el mundo.
* <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>💡 Consejo</strong>: Consulta <a href="https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/color-types.md">los tipos de color</a> para obtener más detalles sobre cómo definir los colores.</p></div>

{% hint style="warning" %}
**📔 Nota**: El `AvatarShape`componente debe importarse mediante

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

Consulta [Importaciones](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/coding-scenes.md#imports) para saber cómo gestionarlas fácilmente.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Los campos URN deben seguir el mismo formato que se usa para [NFTShapes](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/media/display-a-certified-nft.md): `urn:decentraland:<CHAIN>:<CONTRACT_STANDARD>:<CONTRACT_ADDRESS>:<TOKEN_ID>`
{% endhint %}

## Mover un NPC

Para mover un NPC, cambia la `position` de su `Transform`. El avatar no salta a la nueva posición: camina hasta allí desde donde está, a unos 4 metros por segundo, y se mueve más rápido cuando el objetivo está a 1,5 metros o más. Mientras se mueve, gira para mirar en la dirección en la que camina. La `rotation` que establezcas en el `Transform` solo se aplica cuando llega.

```ts
// El NPC camina desde su posición actual hasta la nueva
Transform.getMutable(myAvatar).position = Vector3.create(10, 0.25, 5)
```

Para controlar el movimiento por tu cuenta, usa un [Tween](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/move-entities.md). Un Tween en la posición sustituye esta caminata automática, y un Tween en la rotación impide que el NPC gire para mirar hacia donde camina. Una entidad solo puede tener un Tween a la vez, así que no puedes aplicar Tween a la posición y la rotación de la misma entidad simultáneamente.

## Animaciones

Los avatares reproducen animaciones predeterminadas de inactividad cuando están quietos.

Para reproducir animaciones en el avatar, establece la cadena `expressionTriggerId` con el nombre de la animación que quieres reproducir.

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

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

El campo `expressionTriggerId` admite todas las [animaciones predeterminadas](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/avatar-animations.md#default-animations), así como animaciones personalizadas [de un archivo de escena](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/avatar-animations.md#custom-animations), e incluso URN de emotes publicados en el Marketplace.

Para usar una animación personalizada, indica la ruta al archivo `_emote.glb` desde la carpeta raíz de tu proyecto, por ejemplo `'assets/animations/Cheer_emote.glb'`. Al igual que con [`triggerSceneEmote()`](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/avatar-animations.md#custom-animations), una ruta incorrecta no reproduce nada.

{% hint style="warning" %}
**📔 Nota**: `AvatarShape` no tiene el campo `mask` , así que un `expressionTriggerId` la animación siempre se reproduce en todo el cuerpo. [Animar solo la parte superior del cuerpo](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/avatar-animations.md#animate-only-the-upper-body) está disponible en el Avatar del propio jugador, no en los NPC.
{% endhint %}

### Mover un NPC mientras reproduce un emote

Escribir el `Transform.position`, o ejecutar un [Tween](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/move-entities.md) en él cancela el emote que se está reproduciendo. El Avatar vuelve a su ciclo de caminata, porque Decentraland determina qué animación de locomoción combinar según cuánto se haya movido el Avatar desde el fotograma anterior.

Para mover un NPC durante un emote, si el movimiento abarca un área pequeña, quizá quieras incorporar el movimiento a la propia animación, como movimiento de raíz o de cadera dentro del archivo `_emote.glb` .

### Animaciones en bucle

Las animaciones de un `AvatarShape` se reproducen una sola vez. Si quieres que el Avatar repita una animación en bucle, debes crear un sistema que le indique volver a reproducirla cada dos segundos aproximadamente.

La única excepción son los emotes predeterminados en bucle, `sittingChair1`, `sittingChair2`, `sittingGround1` y `sittingGround2`, que mantienen la pose en un `AvatarShape` sin necesidad de volver a reproducirlos. Una animación personalizada desde un archivo nunca se repite en un `AvatarShape`, aunque el clip esté marcado como cíclico, así que para mantener una pose personalizada hay que usar el patrón de repetición que aparece a continuación.

Usa `expressionTriggerTimestamp` para volver a reproducir el mismo emote. El valor de este campo es una [marca de tiempo de Lamport](https://en.wikipedia.org/wiki/Lamport_timestamp), lo que significa que no es un valor de tiempo, sino un índice que aumenta en 1 con cada repetición del emote.

Por lo tanto, la primera vez que reproduzcas un emote, establece `expressionTriggerTimestamp` en *0*. Para volver a reproducir el emote, debes actualizar este valor a 1. Así es como el Engine sabe que se trata de una instrucción nueva y no de una que ya ejecutó.

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

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

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

let clapTimer = 0
let emoteDuration = 2  // 2 seconds

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

{% hint style="info" %}
**💡 Consejo**: Debes conocer la duración del emote y establecer la duración del sistema en consecuencia. Si creas un emote que mantiene al Avatar inmóvil en la misma pose, se recomienda que la duración del emote sea mayor que la del sistema. Así te aseguras de que no haya artefactos al finalizar y reiniciar la animación.
{% endhint %}

## Añadir una etiqueta sobre el nombre

Usa el `AvatarNametag` component para mostrar una placa con texto personalizado sobre el nombre del NPC, por ejemplo, un rol como «Tendero» o «Jefe». Añádelo a la misma entidad que tiene el `AvatarShape`:

```ts
AvatarNametag.create(myAvatar, { label: 'Shopkeeper' })
```

Si el `AvatarShape` tiene un `name`vacío, solo se muestra la placa, sin una caja de etiqueta vacía debajo. Esto resulta útil para etiquetar un NPC solo con un título.

{% hint style="info" %}
**💡 Consejo**: Para crear una placa con un color específico y sin texto, asigna a `label` una cadena de espacios y elige un `backgroundColor`. Los espacios se conservan, así que cuantos más agregues, más ancha será la placa.

```ts
AvatarNametag.create(myAvatar, {
	label: '      ',
	backgroundColor: Color3.Red(),
})
```

{% endhint %}

Consulta [Avatar Nametags](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/avatar-nametags.md) para ver la lista completa de campos, incluidos los colores.

## Copiar los wearables del jugador

El siguiente fragmento cambia los wearables y otras características del avatar de un NPC para que coincidan con los que lleva puestos el jugador en ese momento. Esto se puede usar en una escena como maniquí para mostrar un wearable o un emote en particular junto con el atuendo actual del jugador.

```ts
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 los wearables

Usa el campo `showOnlyWearables` para mostrar solo los wearables enumerados de un avatar. El resto del cuerpo del avatar será invisible.

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

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

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

{% hint style="info" %}
**💡 Consejo**: Si un wearable es bastante pequeño, prueba a asignar un valor mayor a `scale` de `Transform` .
{% endhint %}

## Adjuntar una entidad a un NPC

Puedes usar el `AvatarAttach` permite fijar una entidad a uno de los huesos del Avatar de un NPC, por ejemplo, para que el NPC sostenga un objeto con la mano. La entidad se moverá junto con el Avatar cuando este se anime.

Para usar esta función, usa la `id` propiedad de `AvatarShape` para asignarle un ID arbitrario a este Avatar y, luego, hacer referencia a ese ID en `AvatarAttach`. El ID puede ser cualquier cadena que quieras.

```ts
// Crear NPC con un ID
const myAvatar = engine.addEntity()
Transform.create(myAvatar, {
  position: Vector3.create(8, 0.25, 8),
})
AvatarShape.create(myAvatar, {
  id: "my-avatar-id", 
  wearables: [],
  emotes: []
})

// Crear objeto para adjuntarlo al 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 componente `AvatarAttach` componente [aquí](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/entity-positioning.md#attach-an-entity-to-an-avatar).

## Reemplazar el Avatar del jugador

No puedes cambiar los Wearables que lleva el Avatar del jugador, pero puedes sustituir su Avatar por el Avatar de un NPC, que puedes personalizar por completo.

Para hacerlo, oculta el Avatar del jugador con un [Avatar Modifier Area](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/modifier-areas.md#hide-avatars) que use el modificador `AMT_HIDE_AVATARS` y muestra en su lugar una entidad `AvatarShape` en la posición del jugador.

{% hint style="warning" %}
**📔 Nota**: Para permitir que el jugador tenga control total sobre ese Avatar, debes escuchar los eventos de botones para detectar cuándo pulsa un botón y, luego, activar la animación correspondiente en el Avatar del NPC. Consulta [Eventos de botones](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/system-based-events.md) para obtener más detalles.

Es posible que el control no sea del todo fluido al hacerlo; quizá quieras reservar esta opción para casos muy específicos.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/npc-avatars.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
