> 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-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md).

# Posicionamento de Entity

Como definir a posição, rotação e escala de uma Entity numa cena

Pode definir a *posição*, *rotação* e *escala* de qualquer entidade usando o componente `Transform` Este componente pode ser usado em qualquer entidade no espaço 3D, afetando o local onde a entidade é renderizada. Isto inclui formas primitivas (cubo, esfera, plano, etc.), formas de texto 3D, formas NFT e modelos 3D (`GltfContainer`).

## Use o Scene Editor no Creator Hub

Quando adiciona um item à sua cena através do Scene Editor, este inclui implicitamente um componente **Transform** . Em seguida, altera implicitamente os valores do componente Transform da entidade ao modificar a posição, rotação ou escala de uma entidade. Também pode usar a UI do Scene Editor para introduzir valores numéricos com maior precisão.

## Noções essenciais de código

![](https://2402076176-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
// Create a new entity
const ball = engine.addEntity()

// Give this entity a shape, to make it visible
MeshRenderer.setSphere(ball)

// Give this entity a Transform component
Transform.create(ball, {
	position: Vector3.create(5, 1, 5),
	scale: Vector3.create(1, 1, 1),
	rotation: Quaternion.Identity(),
})
```

Para mover, rodar ou redimensionar uma entidade na sua cena ao longo de um período, altere os valores deste componente de forma incremental, frame a frame. Consulte [Mover entidades](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md) para mais detalhes e boas práticas.

Qualquer campo que omita recebe o valor predefinido: posição `0, 0, 0`, sem rotação e escala de `1, 1, 1`. Omita um campo em vez de o definir como `undefined`. Um campo definido explicitamente como `undefined`, por exemplo, a partir de uma variável que não foi definida, substitui o valor predefinido, e a cena gera então um erro durante a atualização seguinte do engine, não na linha que chamou `Transform.create()`.

```ts
// ❌ If savedRotation is undefined, the scene throws an error later
Transform.create(ball, { position: Vector3.create(5, 1, 5), rotation: savedRotation })

// ✅ Fall back to a real value
Transform.create(ball, { position: Vector3.create(5, 1, 5), rotation: savedRotation ?? Quaternion.Identity() })
```

{% hint style="warning" %}
**📔 Nota**: `Vector3` e `Quaternion` têm de ser importados através de

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

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

## Posição

`position` é um *vetor 3D*, define a posição do centro da entidade nos três eixos, *x*, *y*, e *z*. Consulte [Tipos de geometria](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/special-types.md) para obter mais detalhes.

```ts
// Create a new entity
const ball = engine.addEntity()

// Criar um transform com uma posição predefinida
Transform.create(ball, {
	  position: Vector3.create(5, 1, 5)
})

// Obter uma versão mutável do transform
const mutableTransform = Transform.getMutable(ball)

// Definir a posição com um objeto
mutableTransform.position = { x: 5, y: 1, z: 5 }

// Definir a posição com um objeto (sintaxe alternativa)
mutableTransform.position = Vector3.create(2, 1, 4)

// Definir cada eixo individualmente
mutableTransform.position.x = 3
mutableTransform.position.y = 1
mutableTransform.position.z = 3
```

Ao definir uma posição, tenha em conta as seguintes considerações:

* Os números num vetor de posição representam *metros* (a menos que a entidade seja filha de uma entidade escalada).
* Uma cena constituída por uma única parcela mede 16 m x 16 m. O centro da cena (ao nível do solo) fica em `x:8, y:0, z:8`. Se a cena for constituída por várias parcelas, o centro varia consoante a disposição delas.
* `x:0, y:0, z:0` refere-se ao *canto sudoeste* da parcela base da cena, ao nível do solo.

  > Dica: ao ver uma pré-visualização da cena, aparece uma bússola no ponto (0,0,0) da cena, com as etiquetas de cada eixo como referência.

  > Nota: pode alterar a parcela base de uma cena editando `base` atributo de *scene.json*.
* Para se orientar melhor, use a sua *esquerda* mão:
  * o seu dedo indicador (apontado para a frente) é o eixo *z* do
  * o seu dedo médio (apontado para o lado) é o eixo *x* eixo
  * o seu polegar (apontado para cima) é o *y* .
* Se uma entidade for filha de outra, então `x:0, y:0, z:0` refere-se ao centro da entidade principal, onde quer que ela esteja na cena.
* Todas as entidades da sua cena têm de estar sempre posicionadas dentro dos limites dos parcels que ocupam. Se uma entidade ultrapassar esses limites, será gerado um erro.

  > Sugestão: ao visualizar uma cena no modo de pré-visualização, as entidades que estiverem fora dos limites são destacadas a *vermelho*.
* A sua cena também tem um limite de altura. A altura máxima é de 330 metros para qualquer cena, independentemente do número de parcelas que ocupa. As Entities colocadas acima dos 200 metros podem ter problemas de sincronização no multiplayer. Consulte [limitações da cena](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md) para mais detalhes.

## Rotação

`rotation` é armazenada como um [*quaternion*](https://en.wikipedia.org/wiki/Quaternion), um sistema de quatro números: *x*, *y*, *z* e *w*. Cada um destes números varia entre -1 e 1. Consulte [Tipos de geometria](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/special-types.md) para mais detalhes.

```ts
// Create a new entity
const cube = engine.addEntity()

// Cria um transform com uma rotação predefinida de 0
Transform.create(cube, {
	  rotation: Quaternion.Identity()
})

// Obter uma versão mutável do transform
const mutableTransform = Transform.getMutable(cube)

// Define a rotação com um objeto, usando ângulos de Euler
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

// Define a rotação com um objeto
mutableTransform.rotation = { x: 0.1, y: 0.5, z: 0.5, w: 0 }

// Definir cada eixo individualmente
mutableTransform.rotation.x = 0
mutableTransform.rotation.y = 1
mutableTransform.rotation.z = 0.3
mutableTransform.rotation.w = 0
```

Também pode definir o campo rotation com [*Euler* ângulos](https://en.wikipedia.org/wiki/Euler_angles), a notação mais comum de *x*, *y* e *z* com números entre 0 e 360, à qual a maioria das pessoas está familiarizada. Para usar ângulos de Euler, use uma das seguintes notações:

```ts
// Cria um transform com uma rotação predefinida em ângulos de Euler
Transform.create(cube, {
	  rotation: Quaternion.fromEulerDegrees(0, 90, 0)
})

// Obter uma versão mutável do transform
const mutableTransform = Transform.getMutable(cube)

// Define a rotação com um objeto, usando ângulos de Euler
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)
```

Ao usar um *vector3* para representar ângulos de Euler, *x*, *y* e *z* representam a rotação em cada eixo, medida em graus. Uma volta completa corresponde a 360 graus.

Quando obtém a rotação de uma Entity, esta é devolvida como quaternion por predefinição. Para obter a rotação expressa em ângulos de Euler, use `Quaternion.toEulerAngles()`:

```ts
// Obtém uma versão só de leitura do transform
const transform = Transform.get(cube)

// Obter a rotação expressa em ângulos de Euler
const eulerAngle = Quaternion.toEulerAngles(transform.rotation)
```

## Obter a posição e a rotação globais de uma Entity

As `getWorldPosition` e `getWorldRotation` funções devolvem a posição e a rotação globais de uma Entity. Isto significa que devolvem a posição ou rotação percebida pelo jogador, ignorando qualquer hierarquia de entidades parent.

* `getWorldPosition(engine, entity: Entity): Vector3Type`: Esta função devolve a posição global de uma Entity, tendo em conta todas as posições das entidades parent, caso existam, e devolve `{x: 0, y: 0, z: 0}` se a Entity não tiver um Transform.

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

* `getWorldRotation(engine, entity: Entity): QuaternionType`: Esta função devolve a rotação global de uma Entity, tendo em conta todas as rotações das entidades parent, caso existam. Devolve um tipo `Quaternion` e devolve o quaternion identidade `{x: 0, y: 0, z: 0, w: 1}` se a Entity não tiver um Transform.

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

{% hint style="info" %}
**Nota:** A posição e a rotação globais são relativas às coordenadas dentro da Scene, não às de Genesis City.
{% endhint %}

## Virar-se para o jogador

Adicione um componente *Billboard* a uma Entity para que esta rode sempre na direção da câmara do jogador.

Os Billboards eram uma técnica comum nos jogos 3D dos anos 90, em que a maioria das entidades eram planos 2D que estavam sempre virados para o jogador. A mesma ideia também pode ser usada para rodar um modelo 3D.

{% hint style="warning" %}
**📔 Nota**: um Billboard fica virado para a **câmara**, não para o Avatar. Na terceira pessoa, a câmara fica atrás e acima do Avatar, por isso estão em locais diferentes e um Billboard direcionado para a câmara fica visivelmente virado para o lado oposto ao Avatar. Para ficar virado para o Avatar, defina `targetEntity` como `engine.PlayerEntity`.
{% endhint %}

```ts
// Create a new entity
const cube = engine.addEntity()

// Dar uma forma visível à Entity
MeshRenderer.setBox(cube)

// Criar um transform com uma posição predefinida
Transform.create(cube, {
	  position: Vector3.create(5, 1, 5)
})

// Adicionar um componente Billboard à Entity
Billboard.create(cube, {})
```

Pode configurar o comportamento do Billboard com os seguintes parâmetros:

* `billboardMode`: Usa um valor de `BillboardMode` para definir quais os eixos de rotação que rodam automaticamente para ficarem virados para o jogador:
  * `BillboardMode.BM_ALL`: A Entity roda em todos os seus eixos de rotação para ficar virada para o jogador. Se o jogador estiver muito acima da Entity, esta ficará virada para cima.
  * `BillboardMode.BM_NONE`: A Entity não roda.
  * `BillboardMode.BM_X`: A Entity só roda no seu *x* eixo de rotação.
  * `BillboardMode.BM_Y`: A entidade só roda em torno do seu *y* eixo de rotação. Só roda para a esquerda e para a direita, não para cima e para baixo. Mantém-se perpendicular ao chão se o jogador estiver acima ou abaixo da entidade.
  * `BillboardMode.BM_Z`: A entidade só roda em torno do seu *z* eixo de rotação.
* `targetEntity`: (opcional) Uma entidade para a qual o billboard roda, em vez de se orientar para a câmara do jogador. Se a entidade referenciada não existir (por exemplo, se ainda não tiver sido criada ou tiver sido removida), o billboard deixa de rodar e mantém a última orientação até a entidade voltar a existir. Definir este valor como `engine.CameraEntity` equivale a deixá-lo sem definir.

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

// rótulo 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)

// placa voltada para outra entidade em vez do jogador
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" %}
**💡 Sugestão**: Os billboards são muito úteis quando adicionados a entidades de *texto* , pois fazem com que o texto esteja sempre legível.
{% endhint %}

Defina `targetEntity` como `engine.PlayerEntity` para seguir o avatar em vez da câmara. É o que deve fazer para uma etiqueta com o nome, um balão de fala ou qualquer outro elemento que pertença ao avatar, e não à perspetiva do jogador:

```ts
// Um rótulo que se vira para o avatar, não para a câmara
Billboard.create(label, {
	targetEntity: engine.PlayerEntity,
	billboardMode: BillboardMode.BM_Y,
})
```

A posição do avatar fica nos pés, por isso um rótulo acima da cabeça inclinar-se-ia para baixo, na direção do avatar. `BM_Y` mantém o rótulo na vertical e só o roda para a esquerda e para a direita.

### Para que lado fica virado um billboard

Um billboard aponta o seu eixo local **-Z** na direção para a qual está voltado. Isso é importante quando associa outras entidades a um billboard:

* Uma entidade filha com um deslocamento local de **+Z** fica **atrás** do billboard, ocultada por ele.
* Uma entidade filha com um deslocamento local de **-Z** fica **à frente**, mais perto do observador.

Assim, para colocar uma moldura ou um fundo atrás de um rótulo com billboard, aplique um deslocamento em **+Z**. Para colocar um destaque à frente dele, aplique um deslocamento em **-Z**.

O valor de `rotation` do componente `Transform` da entidade não muda quando o billboard acompanha os jogadores.

Se uma entidade tiver um componente `Billboard` e um componente `Transform` com valores de `rotation` ao mesmo tempo, os jogadores verão a entidade a rodar como um billboard. Se o billboard não afetar todos os eixos, os eixos restantes serão rodados de acordo com o `Transform` componente.

{% hint style="warning" %}
**📔 Nota**: Se houver vários jogadores presentes ao mesmo tempo, cada um verá as entidades com modo billboard voltadas para si. As rotações do billboard são calculadas localmente para cada jogador e não afetam o que os outros veem. Isto não se aplica a billboards com um `targetEntity`: como a posição do alvo faz parte da cena, todos os jogadores veem esses billboards voltados na mesma direção.
{% endhint %}

## Voltar-se para um conjunto de coordenadas

Para que a entidade A olhe para a entidade B:

```
1) Subtraia a posição da entidade A da posição da entidade B para obter um vetor que descreva a distância entre elas.
2) Normalize esse vetor para que tenha comprimento 1, mantendo a sua direção.
3) Use `Quaternion.lookRotation` para obter uma rotação Quaternion que descreva a rotação nessa direção.
4) Defina esse Quaternion como a rotação da entidade 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` também é um *vetor 3D*, armazenado como um `Vector3` objeto, incluindo o fator de escala no *x*, *y* e *z* eixo. A forma da entidade é dimensionada em conformidade, quer seja uma primitiva ou um modelo 3D.

A escala predefinida é 1. Por isso, atribua um valor superior a 1 para alongar uma entidade ou inferior a 1 para a reduzir.

```ts
// Create a new entity
const ball = engine.addEntity()

// Criar um transform com uma posição predefinida
Transform.create(ball, {
	  scale: Vector3.create(5, 5, 5)
})

// Obter uma versão mutável do transform
const mutableTransform = Transform.getMutable(ball)

// Set the scale with a Vector3

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

// Definir a posição com um objeto
mutableTransform.scale = { x: 5, y: 1, z: 5 }

// Definir cada eixo individualmente
mutableTransform.scale.x = 3
mutableTransform.scale.y = 3
mutableTransform.scale.z = 2
```

## Herdar transformações do elemento principal

Quando uma entidade está aninhada noutra, as entidades filhas herdam componentes das entidades principais. Isto significa que, se uma entidade principal for posicionada, dimensionada ou rodada, as respetivas entidades filhas também são afetadas. Os valores de posição, rotação e escala das entidades filhas não substituem os das entidades principais; em vez disso, são combinados.

Para atribuir uma entidade como elemento principal de outra, defina o campo `parent` na entidade filha, no componente `Transform` .

Se uma entidade principal for dimensionada, todos os valores de posição das respetivas entidades filhas também serão dimensionados.

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

Neste exemplo, a escala da entidade filha será reduzida para 0,5, uma vez que essa é a escala da entidade principal. A posição da entidade filha também será relativa à entidade principal. Temos de somar a posição da entidade principal à da entidade filha. Neste caso, como a entidade principal tem metade do tamanho original, a transformação da entidade filha também é reduzida proporcionalmente. Em termos absolutos, a entidade filha está posicionada em `{ x: 3, y: 1.5, z: 1 }`. Se a entidade principal tivesse uma `rotation`, isso também afetaria a posição final da entidade filha, uma vez que altera o eixo ao longo do qual a entidade filha é deslocada.

Se uma entidade filha não tiver uma `position` no seu Transform, o valor predefinido é `0,0,0`, o que a manterá posicionada no mesmo local que a entidade principal.

Pode usar uma entidade invisível, sem componente de forma, como elemento principal para agrupar outras entidades. Esta entidade não será visível na cena renderizada, mas pode ser usada para agrupar as entidades filhas e aplicar uma transformação a todas elas.

{% hint style="warning" %}
**📔 Nota**: Evite criar um ciclo na hierarquia, no qual uma entidade acaba por ser antepassada de si própria. O SDK deteta estes ciclos e regista um aviso que identifica as entidades envolvidas. As entidades afetadas não ficam posicionadas corretamente até corrigir a relação entre elementos principais e filhos.
{% endhint %}

## Anexar uma entidade a um avatar

Existem três métodos para anexar uma entidade ao jogador:

* Torná-la filha da **Avatar Entity**
* Torná-la filha da **Camera Entity**
* Usar o componente **AvatarAttach**

A forma mais simples de anexar uma entidade ao avatar é definir como elemento principal a [entidade reservada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#reserved-entities) `engine.PlayerEntity`. A entidade mover-se-á então juntamente com a posição do jogador.

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

Também pode definir uma entidade como a [entidade reservada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#reserved-entities) `engine.CameraEntity`. Ao usar a entidade da câmara na primeira pessoa, a entidade anexada acompanhará os movimentos da câmara. Isto é ideal para manter algo sempre no campo de visão, por exemplo, para manter o modelo 3D da arma sempre visível, mesmo quando a câmara aponta para cima.

```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 anexar um objeto a um dos ossos do Avatar e fazê-lo mover-se juntamente com as animações do Avatar, adicione um componente `AvatarAttach` à entidade.

Pode escolher diferentes pontos de ancoragem no Avatar. A maioria destes pontos está associada à armature do jogador e acompanha as animações do jogador. Por exemplo, ao usar o ponto de ancoragem da mão direita, a entidade anexada mover-se-á quando o Avatar acenar ou balançar os braços enquanto corre, como se o jogador estivesse a segurar a entidade na mão.

```ts
// Anexar ao jogador principal; se avatarId não estiver definido, engine.PlayerEntity é usado por predefinição
AvatarAttach.create(myEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Anexar a um jogador através do ID
AvatarAttach.create(myEntity, {
	avatarId: '0xAAAAAAAAAAAAAAAAA',
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})
```

Ao criar um componente `AvatarAttach` , passe um objeto com os seguintes dados:

* `avatarId`: *Opcional* O ID do jogador ao qual anexar. Para os jogadores ligados através de uma carteira Ethereum, este é o mesmo que o endereço Ethereum do jogador. Se não for especificado, a entidade é anexada ao Avatar do jogador local.
* `anchorPointId`: O ponto de ancoragem no esqueleto do Avatar ao qual anexar a entidade, usando um valor do enum `AvatarAnchorPointType`.

{% hint style="warning" %}
**📔 Nota**: Se quiser que todos os jogadores na Scene vejam um objeto anexado ao mesmo jogador — por exemplo, que todos vejam o Jogador A apanhar um objeto e segurá-lo na mão esquerda —, tem de fornecer um valor para `avatarId`. Caso contrário, todos os jogadores verão o objeto anexado aos seus próprios Avatares.
{% endhint %}

O exemplo seguinte coloca uma entidade anexada a um Avatar específico, para que todos os outros jogadores a vejam anexada a esse mesmo 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,
  })

  // Outros componentes

  syncEntity(entity, [AvatarAttach.componentId])

}
```

Os seguintes pontos de ancoragem estão disponíveis no enum `AvatarAnchorPointType` :

* `AAPT_RIGHT_HAND`: Fixo na mão direita do jogador
* `AAPT_LEFT_HAND`: Fixo à mão esquerda do jogador
* `AAPT_HEAD`: Fixo ao centro da cabeça do jogador.
* `AAPT_NECK`: Fixo à base do pescoço do jogador.
* `AAPT_SPINE`: Fixo à secção superior da coluna vertebral.
* `AAPT_SPINE1`: Fixo à secção intermédia da coluna vertebral.
* `AAPT_SPINE2`: Fixo à secção inferior da coluna vertebral.
* `AAPT_HIP`: Fixo ao osso da anca.
* `AAPT_LEFT_SHOULDER`: Fixo ao ombro esquerdo.
* `AAPT_LEFT_ARM`: Fixo ao primeiro osso do braço esquerdo, à altura do ombro.
* `AAPT_LEFT_FOREARM`: Fixo ao osso do antebraço esquerdo.
* `AAPT_LEFT_HAND_INDEX`: Fixo à ponta do dedo indicador esquerdo.
* `AAPT_RIGHT_SHOULDER`: Fixo ao ombro direito.
* `AAPT_RIGHT_ARM`: Fixo ao primeiro osso do braço direito, à altura do ombro.
* `AAPT_RIGHT_FOREARM`: Fixo ao osso do antebraço direito.
* `AAPT_RIGHT_HAND_INDEX`: Fixo à ponta do dedo indicador direito.
* `AAPT_LEFT_UP_LEG`: Fixo ao osso superior da perna esquerda.
* `AAPT_LEFT_LEG`: Fixo ao osso inferior da perna esquerda.
* `AAPT_LEFT_FOOT`: Fixo ao tornozelo da perna esquerda.
* `AAPT_LEFT_TOE_BASE`: Fixo à ponta do dedo do pé esquerdo.
* `AAPT_RIGHT_UP_LEG`: Fixo ao osso superior da perna direita.
* `AAPT_RIGHT_LEG`: Fixo ao osso inferior da perna direita.
* `AAPT_RIGHT_FOOT`: Fixo ao tornozelo da perna direita.
* `AAPT_RIGHT_TOE_BASE`: Fixo à ponta do dedo do pé direito.
* `.AAPT_NAME_TAG`: Flutua mesmo acima da etiqueta com o nome do jogador e não é afetado pelas animações do jogador.

  > Nota: A altura da etiqueta com o nome é ajustada dinamicamente com base na altura dos Wearables que o jogador tem equipados. Assim, um jogador que use um chapéu alto terá a etiqueta com o nome um pouco mais alta do que a dos outros.
* `AAPT_POSITION` *OBSOLETO*: A posição geral do jogador. Aparece a uma altura de 0,8 acima dos pés do jogador.

  >

{% hint style="warning" %}
\> \*\*📔 Nota\*\*: \`AAPT\_POSITION\` está obsoleto. Para acompanhar a posição geral do jogador, é melhor tornar a entidade filha da Avatar Entity. Consulte o início desta secção para ver um exemplo. >
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para usar estes valores, escreva `AvatarAnchorPointType.` e o VS Code apresentará a lista completa de opções num menu pendente.
{% endhint %}

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

A renderização da entidade é determinada localmente em cada instância da cena. Anexar uma entidade a um jogador não a torna visível para os outros jogadores que o veem. Se uma entidade for anexada ao jogador local predefinido, cada jogador verá a entidade anexada ao seu próprio avatar.

{% hint style="warning" %}
**📔 Nota**: As entidades anexadas a um avatar têm de permanecer dentro dos limites da cena para serem renderizadas. Se um jogador sair da sua cena, quaisquer entidades anexadas deixam de ser renderizadas até o jogador voltar a entrar. Os Smart wearables não têm esta limitação.
{% endhint %}

O componente `AvatarAttach` substitui os valores do componente `Transform` Quaisquer valores que introduza no componente `Transform` são substituídos pela posição relativa da entidade em relação ao Transform do jogador. Estes valores são atualizados a cada frame à medida que o jogador se move e anima.

Se precisar de posicionar uma entidade com um desvio em relação ao ponto de ancoragem no avatar, ou com uma rotação ou escala diferente, faça-o através de uma entidade-pai.

1. Crie uma entidade invisível apenas com um `Transform` e um componente `AvatarAttach` Os valores de `Transform` serão substituídos à medida que o jogador se move
2. Defina a entidade que pretende anexar como filha desta entidade-pai. Os valores de `Transform` podem descrever o desvio em relação ao ponto de ancoragem.

```ts
// Criar entidade-pai
const parentEntity = engine.addEntity()

// Anexar entidade-pai ao jogador
AvatarAttach.create(parentEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// Criar entidade-filha
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**: Se a entidade anexada tiver colliders, estes podem bloquear o movimento do jogador ou causar efeitos de tremor. Poderá querer desativar a camada de física dos colliders da entidade anexada. Consulte [Camadas de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers)
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Se tiver uma entidade-filha e quiser saber a Position e/ou Rotation global, pode utilizar as funções `getWorldPosition` e `getWorldRotation` Pode consultá-las na secção [Obter a posição e a rotação globais](#getting-global-position-and-rotation-of-an-entity) .
{% endhint %}

### Anexar a outros jogadores

Pode utilizar o componente `AvatarAttach` para anexar uma entidade a outro jogador. Para isso, tem de saber o ID do jogador.

Para anexar uma entidade ao avatar de outro jogador, tem de fornecer o ID do utilizador no campo `avatarId`. Existem [várias formas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md#get-player-data) de obter estes dados.

{% hint style="warning" %}
**📔 Nota**: Para os jogadores ligados com uma carteira Ethereum, o respetivo `userId` é igual ao endereço Ethereum.
{% endhint %}

Obtenha o `userId` de todos os outros jogadores nas proximidades através de `getPlayer()`

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

Em conjunto com `AvatarAttach`, pode usar o seguinte código para adicionar um cubo a flutuar sobre a cabeça de todos os outros jogadores na cena:

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

Consulte outras formas de obter os IDs de outros jogadores em [Obter dados do jogador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md#get-player-data).

{% hint style="warning" %}
**📔 Nota**: Não defina a entidade de outro jogador como `parent` da sua entidade. O Engine escreve o `Transform` dessa entidade para que a sua cena o possa ler, mas ela não é uma entidade principal à qual a sua entidade se possa ligar. Por isso, a entidade filha volta à raiz da cena e permanece na origem da cena. Em vez disso, use `AvatarAttach` com o endereço do jogador, como mostrado acima.
{% endhint %}

Os IDs das entidades dos jogadores são reutilizados à medida que as pessoas entram e saem, pelo que a mesma entidade pode pertencer mais tarde a outra pessoa. Se mantiver um marcador por jogador, guarde o endereço para o qual o criou e compare-o em cada frame. Quando o endereço de uma entidade mudar, elimine o marcador antigo e crie um novo:

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

// endereço para o qual o marcador foi criado, para detetarmos a reutilização de um ID de entidade
const markers = new Map<Entity, { address: string; marker: Entity }>()

function markerSystem() {
	// remover marcadores cujo jogador saiu ou cujo ID de entidade agora pertence a outra pessoa
	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)
```

## Limites das Scenes

Todas as entidades da sua cena têm de caber dentro dos limites da cena, uma vez que, para lá desses limites, existem parcelas de terreno pertencentes a outros jogadores.

Se alguma parte dos seus modelos ultrapassar estes limites durante uma pré-visualização, essas partes serão cortadas e não serão renderizadas, tanto durante a pré-visualização como na cena publicada.

A posição das entidades na sua cena é verificada continuamente à medida que se movem. Se uma entidade sair da cena e depois voltar, será removida e, em seguida, renderizada normalmente outra vez.

Uma grelha no chão da cena mostra os limites da cena, que, por predefinição, vão de 0 a 16 nos eixos *x* e *z* e vão até 20 no eixo *y* eixo. Pode colocar entidades no subsolo, abaixo de 0 no *y* eixo.

{% hint style="info" %}
**💡 Dica**: Se a sua scene precisar de mais parcels, pode adicioná-los no `scene.json` ficheiro do projeto. Consulte [Metadados da scene](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-metadata.md) para ver as instruções. Depois de os adicionar, deverá ver a grelha expandir-se para cobrir os parcels adicionais.
{% 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-pt/scenes-sdk7/fundamentos-de-conteudo-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.
