> 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/fundamentos-del-contenido-3d/entity-positioning.md).

# Posicionamiento de entidades

Cómo establecer la posición, rotación y escala de una entidad en una escena

Puedes establecer la *posición*, *rotación* y *escala* de cualquier entidad mediante el componente `Transform` component. Esto puede usarse en cualquier entidad del espacio 3D y afecta al lugar donde se renderiza la entidad. Esto incluye formas primitivas (cubo, esfera, plano, etc.), formas de texto 3D, formas NFT y modelos 3D (`GltfContainer`).

## Usa Scene Editor en Creator Hub

Al añadir un elemento a tu escena mediante Scene Editor, este incluye implícitamente un componente **Transform** . Después, cambias implícitamente los valores del componente Transform de la entidad al modificar su posición, rotación o escala. También puedes usar la UI de Scene Editor para introducir valores numéricos con mayor precisión.

## Conceptos básicos del código

![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8bb43741efd4cdb7e001f4dca8acd7f21fbcb48e%2Fecs-simple-components-new.webp?alt=media)

```ts
// Crear una entidad nueva
const ball = engine.addEntity()

// Darle una forma a esta entidad para que sea visible
MeshRenderer.setSphere(ball)

// Darle a esta entidad un componente Transform
Transform.create(ball, {
	position: Vector3.create(5, 1, 5),
	scale: Vector3.create(1, 1, 1),
	rotation: Quaternion.Identity(),
})
```

Para mover, rotar o cambiar el tamaño de una entidad de tu escena a lo largo del tiempo, modifica gradualmente los valores de este componente, fotograma a fotograma. Consulta [Mover entidades](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/move-entities.md) para obtener más detalles y conocer las prácticas recomendadas.

Cualquier campo que omitas tendrá su valor predeterminado: posición `0, 0, 0`, sin rotación y una escala de `1, 1, 1`. Omite un campo en lugar de establecerlo en `undefined`. Un campo establecido explícitamente en `undefined`, por ejemplo, a partir de una variable sin asignar, reemplaza el valor predeterminado y la escena genera un error durante la siguiente actualización del motor, no en la línea que llamó a `Transform.create()`.

```ts
// ❌ Si savedRotation es undefined, la escena genera un error más adelante
Transform.create(ball, { position: Vector3.create(5, 1, 5), rotation: savedRotation })

// ✅ Usar un valor válido como alternativa
Transform.create(ball, { position: Vector3.create(5, 1, 5), rotation: savedRotation ?? Quaternion.Identity() })
```

{% hint style="warning" %}
**📔 Nota**: `Vector3` y `Quaternion` deben importarse mediante

> `import { Vector3, Quaternion } from "@dcl/sdk/math"`

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

## Posición

`position` es un *vector 3D*, establece la posición del centro de la entidad en los tres ejes: *x*, *y*, y *z*. Consulta [Tipos de geometría](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/special-types.md) para obtener más información.

```ts
// Crear una entidad nueva
const ball = engine.addEntity()

// Crear un Transform con una posición predefinida
Transform.create(ball, {
	  position: Vector3.create(5, 1, 5)
})

// Obtener una versión mutable del Transform
const mutableTransform = Transform.getMutable(ball)

// Establecer la posición con un objeto
mutableTransform.position = { x: 5, y: 1, z: 5 }

// Establecer la posición con un objeto (sintaxis alternativa)
mutableTransform.position = Vector3.create(2, 1, 4)

// Establecer cada eje individualmente
mutableTransform.position.x = 3
mutableTransform.position.y = 1
mutableTransform.position.z = 3
```

Al establecer una posición, ten en cuenta lo siguiente:

* Los números de un vector de posición representan *metros* (salvo que la entity sea hija de una entity escalada).
* Una scene compuesta por una sola parcel mide 16 m x 16 m. El centro de la scene, a nivel del suelo, se encuentra en `x:8, y:0, z:8`. Si la scene está compuesta por varias parcels, el centro variará en función de su disposición.
* `x:0, y:0, z:0` se refiere a la esquina *suroeste* de la parcel base de la scene, a nivel del suelo.

  > Consejo: Al ver una preview de la scene, aparece una brújula en el punto (0,0,0) de la scene con etiquetas para cada eje como referencia.

  > Nota: Puedes cambiar la parcel base de una scene editando el atributo `base` de *scene.json*.
* Para orientarte mejor, usa tu mano *izquierda* :
  * tu dedo índice (apuntando hacia delante) corresponde al eje *z* de coordenadas
  * tu dedo corazón (apuntando hacia un lado) corresponde al eje *x* de coordenadas
  * tu pulgar (apuntando hacia arriba) corresponde al eje *y* de coordenadas.
* Si una entity es hija de otra, `x:0, y:0, z:0` se refiere al centro de su entity padre, dondequiera que se encuentre en la scene.
* Todas las entities de tu scene deben permanecer en todo momento dentro de los límites de las parcels que ocupa la scene. Si una entity sale de esos límites, se producirá un error.

  > Consejo: Al ver una scene en modo preview, las entities que están fuera de los límites se resaltan en *rojo*.
* La altura de tu escena también está limitada. La altura máxima es de 330 metros para todas las escenas, independientemente de cuántos parcels ocupe. Las Entities ubicadas por encima de los 200 metros pueden tener problemas de sincronización en el modo Multiplayer. Consulta [limitaciones de las escenas](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/optimizacion/scene-limitations.md) para obtener más detalles.

## Rotación

`rotation` se almacena como un [*quaternion*](https://en.wikipedia.org/wiki/Quaternion), un sistema de cuatro números: *x*, *y*, *z* y *w*. Cada uno de estos números va de -1 a 1. Consulta [Tipos de geometría](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/special-types.md) para obtener más detalles.

```ts
// Crear una entidad nueva
const cube = engine.addEntity()

// Create transform with a predefined rotation of 0
Transform.create(cube, {
	  rotation: Quaternion.Identity()
})

// Obtener una versión mutable del Transform
const mutableTransform = Transform.getMutable(cube)

// Set the rotation with an object, from euler angles
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

// Set the rotation with an object
mutableTransform.rotation = { x: 0.1, y: 0.5, z: 0.5, w: 0 }

// Establecer cada eje individualmente
mutableTransform.rotation.x = 0
mutableTransform.rotation.y = 1
mutableTransform.rotation.z = 0.3
mutableTransform.rotation.w = 0
```

También puedes establecer el campo rotation con [*Euler* ángulos](https://en.wikipedia.org/wiki/Euler_angles), la notación más común de *x*, *y* y *z* con números que van de 0 a 360, con la que la mayoría de las personas está familiarizada. Para usar ángulos de Euler, emplea una de las siguientes notaciones:

```ts
// Create transform with a predefined rotation in Euler angles
Transform.create(cube, {
	  rotation: Quaternion.fromEulerDegrees(0, 90, 0)
})

// Obtener una versión mutable del Transform
const mutableTransform = Transform.getMutable(cube)

// Set the rotation with an object, from euler angles
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)
```

Al usar un *vector 3D* para representar los ángulos de Euler, *x*, *y* y *z* representan la rotación en ese eje, medida en grados. Un giro completo requiere 360 grados.

Al obtener la rotación de una Entity, se devuelve un quaternion de forma predeterminada. Para obtener la rotación expresada en ángulos de Euler, usa `Quaternion.toEulerAngles()`:

```ts
// Fetch a read-only version of the transform
const transform = Transform.get(cube)

// Obtener la rotación expresada en ángulos de Euler
const eulerAngle = Quaternion.toEulerAngles(transform.rotation)
```

## Obtener la posición y rotación globales de una Entity

Las `getWorldPosition` y `getWorldRotation` funciones devuelven la posición y rotación globales de una Entity. Es decir, devuelven la posición o rotación percibida en la que el jugador verá el elemento, sin tener en cuenta las jerarquías de entidades padre.

* `getWorldPosition(engine, entity: Entity): Vector3Type`: Esta función devuelve la posición global de una Entity, teniendo en cuenta todas las posiciones de sus entidades padre, si las tiene. Devuelve `{x: 0, y: 0, z: 0}` si la Entity no tiene Transform.

```ts
const worldPos = getWorldPosition(engine, childEntity)
console.log(`World position: ${worldPos.x}, ${worldPos.y}, ${worldPos.z}`)
```

* `getWorldRotation(engine, entity: Entity): QuaternionType`: Esta función devuelve la rotación global de una Entity, teniendo en cuenta todas las rotaciones de sus entidades padre, si las tiene. Devuelve un valor de tipo `Quaternion` y devuelve el cuaternión identidad `{x: 0, y: 0, z: 0, w: 1}` si la Entity no tiene Transform.

```ts
const worldRot = getWorldRotation(engine, childEntity)
console.log(`World rotation: ${worldRot.x}, ${worldRot.y}, ${worldRot.z}, ${worldRot.w}`)
```

{% hint style="info" %}
**Nota:** La posición global y la rotación global son relativas a las coordenadas dentro de la escena, no a Genesis City.
{% endhint %}

## Orientar hacia el jugador

Añade un componente *Billboard* a una Entity para que siempre rote hacia la cámara del jugador.

Los Billboards eran una técnica común en los juegos 3D de los años 90, en los que la mayoría de las entidades eran planos 2D que siempre miraban hacia el jugador. Esta misma idea también se puede usar para rotar un modelo 3D.

{% hint style="warning" %}
**📔 Nota**: Un Billboard mira hacia la **cámara**, no hacia el Avatar. En tercera persona, la cámara se encuentra detrás y por encima del Avatar, así que están en lugares distintos y un Billboard orientado hacia la cámara queda visiblemente apartado del Avatar. Para orientarlo hacia el Avatar, establece `targetEntity` en `engine.PlayerEntity`.
{% endhint %}

```ts
// Crear una entidad nueva
const cube = engine.addEntity()

// Darle una forma visible a la Entity
MeshRenderer.setBox(cube)

// Crear un Transform con una posición predefinida
Transform.create(cube, {
	  position: Vector3.create(5, 1, 5)
})

// Añadir un componente Billboard a la Entity
Billboard.create(cube, {})
```

Puedes configurar el comportamiento del Billboard con los siguientes parámetros:

* `billboardMode`: Usa un valor de `BillboardMode` para establecer qué ejes de rotación giran automáticamente para orientarse hacia el jugador:
  * `BillboardMode.BM_ALL`: La Entity gira para orientarse hacia el jugador en todos sus ejes de rotación. Si el jugador está muy por encima de la Entity, esta mirará hacia arriba.
  * `BillboardMode.BM_NONE`: La Entity no girará.
  * `BillboardMode.BM_X`: La Entity solo gira sobre su *x* eje de rotación.
  * `BillboardMode.BM_Y`: La entidad solo rota sobre su *y* eje de rotación. Solo rota hacia la izquierda y la derecha, no hacia arriba y abajo. Permanece perpendicular al suelo si el jugador está por encima o por debajo de la entidad.
  * `BillboardMode.BM_Z`: La entidad solo rota sobre su *z* eje de rotación.
* `targetEntity`: (opcional) Una entidad hacia la que gira el billboard, en lugar de orientarse hacia la cámara del jugador. Si la entidad referenciada no existe (por ejemplo, todavía no se ha creado o se ha eliminado), el billboard deja de rotar y conserva su última orientación hasta que la entidad vuelva a existir. Establecer este valor en `engine.CameraEntity` equivale a no establecerlo.

```ts
// billboard plano
const perpendicularPlane = engine.addEntity()

Transform.create(perpendicularPlane, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setPlane(perpendicularPlane)

Billboard.create(perpendicularPlane, {
	billboardMode: BillboardMode.BM_Y,
})

// etiqueta de texto
const textLabel = engine.addEntity()

Transform.create(textLabel, {
	position: Vector3.create(6, 1, 6),
})

TextShape.create(textLabel, {
	text: 'This text is always readable',
})

Billboard.create(textLabel)

// letrero que mira hacia otra entidad en lugar de hacia el jugador
const sphere = engine.addEntity()

Transform.create(sphere, {
	position: Vector3.create(4, 2, 4),
})

MeshRenderer.setSphere(sphere)

const sign = engine.addEntity()

Transform.create(sign, {
	position: Vector3.create(8, 1, 8),
})

TextShape.create(sign, {
	text: 'Watching the sphere',
})

Billboard.create(sign, {
	targetEntity: sphere,
})
```

{% hint style="info" %}
**💡 Consejo**: Los billboards son muy prácticos para añadir a las entidades de *texto* , ya que así siempre son legibles.
{% endhint %}

Establece `targetEntity` en `engine.PlayerEntity` para que siga al Avatar en lugar de a la cámara. Esto es lo que necesitas para una etiqueta con el nombre, un globo de diálogo o cualquier otro elemento que pertenezca al Avatar y no a la vista del jugador:

```ts
// Etiqueta que gira para mirar hacia el Avatar, no hacia la cámara
Billboard.create(label, {
	targetEntity: engine.PlayerEntity,
	billboardMode: BillboardMode.BM_Y,
})
```

La posición del Avatar está en sus pies, así que una etiqueta sobre su cabeza se inclinaría hacia abajo, en dirección a ellos. `BM_Y` mantiene la etiqueta derecha y solo la gira hacia la izquierda y la derecha.

### Hacia dónde mira un billboard

Un billboard apunta su **-Z** eje local hacia donde está mirando. Esto es importante cuando asignas otras entidades como hijas de un billboard:

* Una entidad hija con un desplazamiento local de **+Z** queda **detrás** del billboard, oculta por este.
* Una entidad hija con un desplazamiento local de **-Z** queda **delante**, más cerca del usuario.

Así que, para colocar un marco o un fondo detrás de una etiqueta con billboard, desplázalo en **+Z**. Para colocar un resaltado delante, desplázalo en **-Z**.

El valor de `rotation` del componente `Transform` de la entidad no cambia mientras el billboard sigue a los jugadores.

Si una entidad tiene tanto un componente `Billboard` como un componente `Transform` con valores de `rotation` , los jugadores verán la entidad rotar como un billboard. Si el billboard no afecta a todos los ejes, los ejes restantes rotarán según el componente `Transform` .

{% hint style="warning" %}
**📔 Nota**: Si hay varios jugadores presentes al mismo tiempo, cada uno verá las entidades orientadas hacia sí en modo billboard. Las rotaciones de los billboards se calculan localmente para cada jugador y no afectan lo que ven los demás. Esto no se aplica a los billboards con un `targetEntity`, ya que la posición del objetivo forma parte de la escena y todos los jugadores ven esos billboards orientados de la misma manera.
{% endhint %}

## Orientar hacia un conjunto de coordenadas

Para que la entidad A mire hacia la entidad B:

```
1) Resta la posición de la entidad A de la posición de la entidad B para obtener un vector que describa la distancia entre ellas.
2) Normaliza ese vector para que tenga una longitud de 1, conservando su dirección.
3) Usa `Quaternion.lookRotation` para obtener una rotación Quaternion que describa la rotación en esa dirección.
4) Establece ese Quaternion como la rotación de la entidad A
```

```ts
export function turn(entity: Entity, target: Vector3.ReadonlyVector3) {
	const transform = Transform.getMutable(entity)
	const difference = Vector3.subtract(target, transform.position)
	const normalizedDifference = Vector3.normalize(difference)
	transform.rotation = Quaternion.lookRotation(normalizedDifference)
}
```

## Escala

`scale` también es un *vector 3D*, almacenado como un `Vector3` objeto, incluido el factor de escala en el eje *x*, *y* y *z* . La forma de la entidad se escala en consecuencia, tanto si es una primitiva como si es un modelo 3D.

La escala predeterminada es 1, así que asigna un valor mayor que 1 para estirar una entidad o menor que 1 para reducirla.

```ts
// Crear una entidad nueva
const ball = engine.addEntity()

// Crear un Transform con una posición predefinida
Transform.create(ball, {
	  scale: Vector3.create(5, 5, 5)
})

// Obtener una versión mutable del Transform
const mutableTransform = Transform.getMutable(ball)

// Set the scale with a Vector3

mutableTransform.scale = Vector3.create(2, 2, 2)

// Establecer la posición con un objeto
mutableTransform.scale = { x: 5, y: 1, z: 5 }

// Establecer cada eje individualmente
mutableTransform.scale.x = 3
mutableTransform.scale.y = 3
mutableTransform.scale.z = 2
```

## Heredar transformaciones del padre

Cuando una entidad está anidada dentro de otra, las entidades hijas heredan componentes de sus padres. Esto significa que, si una entidad padre cambia de posición, escala o rotación, sus hijas también se ven afectadas. Los valores de posición, rotación y escala de las entidades hijas no reemplazan los de las entidades padre, sino que se combinan con ellos.

Se asigna una entidad como padre de otra estableciendo el campo `parent` en el componente `Transform` de la entidad hija.

Si una entidad padre cambia de escala, también se escalan todos los valores de posición de sus entidades hijas.

```ts
// Create entities
const parentEntity = engine.addEntity()
const childEntity = engine.addEntity()

// Create a transform for the parent
Transform.create(parentEntity, {
	position: Vector3.create(3, 1, 1),
	scale: Vector3.create(0.5, 0.5, 0.5),
})

// Create a transform for the child, and assign it as a child
Transform.create(childEntity, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity,
})
```

En este ejemplo, la escala de la entidad hija se reducirá a 0,5, ya que su padre tiene esa escala. La posición de la entidad hija también será relativa a la de su padre. Debemos sumar la posición del padre y la de la hija. En este caso, como el padre tiene la mitad de su tamaño original, la transformación de la hija también se reduce proporcionalmente. En términos absolutos, la hija se sitúa en `{ x: 3, y: 1.5, z: 1 }`. Si el padre tuviera una `rotation`, esto también afectaría a la posición final de la hija, ya que cambiaría el eje en el que se desplaza.

Si una entidad hija no tiene `position` en su Transform, el valor predeterminado es `0,0,0`, lo que la dejará en la misma posición que su padre.

Puedes usar como padre una entidad invisible sin un componente de forma para agrupar otras entidades. Esta entidad no será visible en la escena renderizada, pero se puede usar para agrupar a sus hijas y aplicarles una transformación a todas.

{% hint style="warning" %}
**📔 Nota**: Evita crear un bucle en la jerarquía en el que una entidad termine siendo su propio antepasado. El SDK detecta estos bucles y registra una advertencia con los nombres de las entidades implicadas. Las entidades afectadas no se posicionarán correctamente hasta que corrijas la relación padre-hija.
{% endhint %}

## Adjuntar una entidad a un avatar

Hay tres métodos para adjuntar una entidad al jugador:

* Convertirla en hija de la **Avatar Entity**
* Convertirla en hija de la **Camera Entity**
* Usar el componente **AvatarAttach**

La forma más sencilla de adjuntar una entidad al avatar es establecer como padre la [entidad reservada](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/arquitectura/entities-components.md#reserved-entities) `engine.PlayerEntity`. La entidad se moverá junto con la posición del jugador.

```ts
let childEntity = engine.addEntity()

MeshRenderer.setCylinder(childEntity)

Transform.create(childEntity, {
	scale: Vector3.create(0.2, 0.2, 0.2),
	position: Vector3.create(0, 0.4, 0),
	parent: engine.PlayerEntity,
})
```

También puedes asignar una entidad a la [entidad reservada](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/arquitectura/entities-components.md#reserved-entities) `engine.CameraEntity`. Al usar la entidad de la cámara en primera persona, la entidad adjunta seguirá los movimientos de la cámara. Esto es ideal para mantener algo siempre a la vista, por ejemplo, para que el modelo 3D del arma permanezca siempre a la vista, incluso cuando la cámara apunta hacia arriba.

```ts
let childEntity = engine.addEntity()

MeshRenderer.setCylinder(childEntity)

Transform.create(childEntity, {
	scale: Vector3.create(0.2, 0.2, 0.2),
	position: Vector3.create(0, 0.4, 0),
	parent: engine.CameraEntity,
})
```

Para adjuntar un objeto a uno de los huesos del avatar y hacer que se mueva junto con sus animaciones, añade un componente `AvatarAttach` a la entidad.

Puedes elegir distintos puntos de anclaje en el avatar. La mayoría están vinculados al armature del jugador y siguen sus animaciones. Por ejemplo, al usar el punto de anclaje de la mano derecha, la entidad adjunta se moverá cuando el avatar salude o balancee los brazos mientras corre, como si el jugador la sostuviera en la mano.

```ts
// Adjuntar al jugador principal; si no se establece avatarId, se usa engine.PlayerEntity de forma predeterminada
AvatarAttach.create(myEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Adjuntar a un jugador por ID
AvatarAttach.create(myEntity, {
	avatarId: '0xAAAAAAAAAAAAAAAAA',
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})
```

Al crear un componente `AvatarAttach` , pasa un objeto con los siguientes datos:

* `avatarId`: *Opcional* El ID del jugador al que se adjuntará la entidad. Para los jugadores conectados con una billetera Ethereum, coincide con su dirección de Ethereum. Si no se especifica, la entidad se adjunta al avatar del jugador local.
* `anchorPointId`: Punto de anclaje del esqueleto del avatar al que se adjuntará la entidad, usando un valor de la enumeración `AvatarAnchorPointType`.

{% hint style="warning" %}
**📔 Nota**: Si quieres que todos los jugadores de la escena vean un objeto adjunto al mismo jugador —por ejemplo, que todos vean que el jugador A recogió un objeto y lo sostiene con la mano izquierda—, debes proporcionar un valor para `avatarId`. Si no se especifica, cada jugador verá el objeto adjunto a su propio avatar.
{% endhint %}

El siguiente ejemplo coloca una entidad adjunta a un avatar específico, para que todos los demás jugadores la vean adjunta a ese mismo avatar.

```ts
import { getPlayer } from '@dcl/sdk/src/players'
import { AvatarAnchorPointType, AvatarAttach, engine, Entity } from '@dcl/sdk/ecs'
import { syncEntity } from '@dcl/sdk/network'

async function attachToPlayer(){

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

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

  let entity = engine.addEntity()

  AvatarAttach.create(entity, {
    avatarId: userData.userId,
    anchorPointId: AvatarAnchorPointType.AAPT_RIGHT_HAND,
  })

  // Otros componentes

  syncEntity(entity, [AvatarAttach.componentId])

}
```

Los siguientes puntos de anclaje están disponibles en la enumeración `AvatarAnchorPointType` :

* `AAPT_RIGHT_HAND`: Fijado a la mano derecha del jugador
* `AAPT_LEFT_HAND`: Fijado a la mano izquierda del jugador
* `AAPT_HEAD`: Fijado al centro de la cabeza del jugador.
* `AAPT_NECK`: Fijado a la base del cuello del jugador.
* `AAPT_SPINE`: Fijado a la sección superior de la columna vertebral.
* `AAPT_SPINE1`: Fijado a la sección media de la columna vertebral.
* `AAPT_SPINE2`: Fijado a la sección inferior de la columna vertebral.
* `AAPT_HIP`: Fijado al hueso de la cadera.
* `AAPT_LEFT_SHOULDER`: Fijado al hombro izquierdo.
* `AAPT_LEFT_ARM`: Fijado al primer hueso del brazo izquierdo, a la altura del hombro.
* `AAPT_LEFT_FOREARM`: Fijado al hueso del antebrazo izquierdo.
* `AAPT_LEFT_HAND_INDEX`: Fijado a la punta del dedo índice izquierdo.
* `AAPT_RIGHT_SHOULDER`: Fijado al hombro derecho.
* `AAPT_RIGHT_ARM`: Fijado al primer hueso del brazo derecho, a la altura del hombro.
* `AAPT_RIGHT_FOREARM`: Fijado al hueso del antebrazo derecho.
* `AAPT_RIGHT_HAND_INDEX`: Fijado a la punta del dedo índice derecho.
* `AAPT_LEFT_UP_LEG`: Fijado al hueso superior de la pierna izquierda.
* `AAPT_LEFT_LEG`: Fijado al hueso inferior de la pierna izquierda.
* `AAPT_LEFT_FOOT`: Fijado al tobillo de la pierna izquierda.
* `AAPT_LEFT_TOE_BASE`: Fijado a la punta del dedo del pie izquierdo.
* `AAPT_RIGHT_UP_LEG`: Fijado al hueso superior de la pierna derecha.
* `AAPT_RIGHT_LEG`: Fijado al hueso inferior de la pierna derecha.
* `AAPT_RIGHT_FOOT`: Fijado al tobillo de la pierna derecha.
* `AAPT_RIGHT_TOE_BASE`: Fijado a la punta del dedo del pie derecho.
* `.AAPT_NAME_TAG`: Flota justo encima de la etiqueta con el nombre del jugador y no se ve afectado por sus animaciones.

  > Nota: La altura de la etiqueta con el nombre se ajusta dinámicamente según la altura de los Wearables que lleve el jugador. Por eso, si un jugador lleva un sombrero alto, su etiqueta aparecerá un poco más arriba que las de los demás.
* `AAPT_POSITION` *OBSOLETO*: La posición general del jugador. Aparece a una altura de 0,8 por encima de los pies del jugador.

  >

{% hint style="warning" %}
\> \*\*📔 Nota\*\*: \`AAPT\_POSITION\` está obsoleto. Para seguir la posición general del jugador, lo mejor es hacer que la entidad sea hija de la Avatar Entity. Consulta el inicio de esta sección para ver un ejemplo. >
{% endhint %}

{% hint style="info" %}
**💡 Consejo**: Para usar estos valores, escribe `AvatarAnchorPointType.` y VS Code mostrará la lista completa de opciones en un menú desplegable.
{% endhint %}

![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-fb1011fbb03960300eef0fb4df2b5f2e9fe80ec8%2Favatar-attach-points.webp?alt=media)

La renderización de las entidades se determina localmente en cada instancia de la escena. Adjuntar una entidad a un jugador no la hace visible para otros jugadores que estén viendo a ese jugador. Si una entidad se adjunta al jugador local predeterminado, cada jugador verá la entidad adjunta a su propio avatar.

{% hint style="warning" %}
**📔 Nota**: Las entidades adjuntas a un avatar deben permanecer dentro de los límites de la escena para renderizarse. Si un jugador sale de la escena, las entidades adjuntas dejan de renderizarse hasta que el jugador vuelva a entrar. Los wearables inteligentes no tienen esta limitación.
{% endhint %}

El componente `AvatarAttach` sobrescribe los valores del componente `Transform` . Los valores que establezcas en el componente `Transform` se reemplazan por la posición relativa de la entidad respecto a la Transform del jugador. Estos valores se actualizan en cada fotograma a medida que el jugador se mueve y anima.

Si necesitas posicionar una entidad con un desplazamiento respecto al punto de anclaje del avatar, o con una rotación o escala diferentes, hazlo mediante una entidad principal.

1. Crea una entidad invisible que solo tenga un componente `Transform` y un componente `AvatarAttach` . Sus valores de `Transform` se sobrescribirán a medida que el jugador se mueva
2. Establece la entidad que quieras adjuntar como hija de esta entidad principal. Sus valores de `Transform` pueden describir el desplazamiento respecto al punto de anclaje.

```ts
// Create parent entity
const parentEntity = engine.addEntity()

// Attach parent entity to player
AvatarAttach.create(parentEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Create child entity
let childEntity = engine.addEntity()

MeshRenderer.setCylinder(childEntity)

Transform.create(childEntity, {
	scale: Vector3.create(0.2, 0.2, 0.2),
	position: Vector3.create(0, 0.4, 0),
	parent: parentEntity,
})
```

{% hint style="warning" %}
**📔 Nota**: Si la entidad adjunta tiene colliders, estos podrían bloquear el movimiento del jugador o causar efectos de vibración. Quizás quieras desactivar la capa de física de los colliders de la entidad adjunta. Consulta [Capas de colisión](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/colliders.md#collision-layers)
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Si tienes una entidad hija y quieres conocer su Position y/o Rotation globales, puedes usar las funciones `getWorldPosition` y `getWorldRotation` . Puedes consultarlas en la sección [Obtener la posición y la rotación globales](#getting-global-position-and-rotation-of-an-entity) .
{% endhint %}

### Adjuntar a otros jugadores

Puedes usar el componente `AvatarAttach` para adjuntar una entidad a otro jugador. Para hacerlo, debes conocer el ID del jugador.

Para adjuntar una entidad al avatar de otro jugador, debes proporcionar el ID del usuario en el campo `avatarId`. Hay [varias formas](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/user-data.md#get-player-data) de obtener estos datos.

{% hint style="warning" %}
**📔 Nota**: Para los jugadores conectados con una wallet de Ethereum, su `userId` es el mismo que su dirección de Ethereum.
{% endhint %}

Obtén el `userId` de todos los demás jugadores cercanos mediante `getPlayer()`

```ts
executeTask(async () => {
	for (const [entity, data] of engine.getEntitiesWith(PlayerIdentityData)) {
		console.log('Player id: ', data.address)
	}
})
```

Al usarlo junto con `AvatarAttach`, podrías usar el siguiente código para añadir un cubo flotando sobre la cabeza de cada uno de los demás jugadores de la escena:

```ts
executeTask(async () => {
        for (const [entity, data] of engine.getEntitiesWith(PlayerIdentityData)) {
            const myEntity = engine.addEntity()
            MeshRenderer.setBox(myEntity)
            AvatarAttach.create(myEntity, {
                anchorPointId: AvatarAnchorPointType.AAPT_LEFT_HAND,
                avatarId: data.address,
            })
        }
    })
```

Consulta otras formas de obtener los IDs de otros usuarios en [Obtener datos del jugador](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/user-data.md#get-player-data).

{% hint style="warning" %}
**📔 Nota**: No establezcas la entidad de otro jugador como el `parent` de tu entidad. El Engine escribe el `Transform` de esa entidad para que tu escena lo lea, pero no es un padre del que tu entidad pueda colgar, así que el elemento hijo vuelve a la raíz de la escena y permanece en el origen de esta. Usa `AvatarAttach` con la dirección del jugador en su lugar, como se muestra arriba.
{% endhint %}

Los IDs de las entidades de los jugadores se reutilizan cuando las personas se van y llegan, por lo que más adelante una misma entidad puede pertenecer a otra persona. Si mantienes un marcador por jugador, guarda la dirección para la que lo creaste y compárala en cada frame. Cuando cambia la dirección de una entidad, elimina el marcador anterior y crea uno nuevo:

```ts
import { AvatarAttach, AvatarAnchorPointType, engine, Entity, PlayerIdentityData } from '@dcl/sdk/ecs'

// dirección para la que se creó el marcador, para detectar si se reutilizó el ID de la entidad
const markers = new Map<Entity, { address: string; marker: Entity }>()

function markerSystem() {
	// elimina los marcadores de jugadores que se fueron o cuyo ID de entidad ahora pertenece a otra persona
	for (const [player, entry] of markers) {
		if (PlayerIdentityData.getOrNull(player)?.address === entry.address) continue
		engine.removeEntity(entry.marker)
		markers.delete(player)
	}

	for (const [player, data] of engine.getEntitiesWith(PlayerIdentityData)) {
		if (markers.has(player)) continue
		const marker = engine.addEntity()
		AvatarAttach.create(marker, {
			avatarId: data.address,
			anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
		})
		markers.set(player, { address: data.address, marker })
	}
}

engine.addSystem(markerSystem)
```

## Límites de las escenas

Todas las entidades de tu escena deben estar dentro de sus límites, ya que lo que queda fuera son parcelas de terreno propiedad de otros jugadores.

Si alguna parte de tus modelos se extiende más allá de estos límites durante una vista previa, esas partes quedarán recortadas y no se renderizarán, ni durante la vista previa ni en la escena publicada.

La posición de las entidades de tu escena se comprueba continuamente mientras se mueven. Si una entidad sale de la escena y luego vuelve, se eliminará y después volverá a renderizarse con normalidad.

Una cuadrícula en el suelo de la escena muestra sus límites, que de forma predeterminada van de 0 a 16 en el eje *x* y *z* y hasta 20 en el eje *y* eje. Puedes colocar Entities bajo tierra, por debajo de 0 en el *y* eje.

{% hint style="info" %}
**💡 Consejo**: Si tu Scene necesita más parcels, puedes añadirlos en el archivo `scene.json` . Consulta [Metadatos de la Scene](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/tipos-de-proyectos/scene-metadata.md) para ver las instrucciones. Una vez añadidos, deberías ver que la cuadrícula se amplía para cubrir los parcels adicionales.
{% 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/fundamentos-del-contenido-3d/entity-positioning.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.
