> 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-ko/sdk7/3d/entity-positioning.md).

# 엔티티 위치 설정

씬에서 엔티티의 위치, 회전, 크기를 설정하는 방법

다음 항목을 설정할 수 있습니다. *위치*, *회전* 및 *크기* 임의의 엔티티에 대해 다음을 사용해 설정할 수 있습니다. `Transform` 컴포넌트입니다. 이 컴포넌트는 3D 공간의 모든 엔티티에 사용할 수 있으며, 엔티티가 렌더링되는 위치에 영향을 줍니다. 여기에는 기본 도형(큐브, 구, 평면 등), 3D 텍스트 도형, NFT 도형, 3D 모델(`GltfContainer`).

## Creator Hub의 Scene Editor 사용

Scene Editor를 통해 씬에 항목을 추가하면 암시적으로 **Transform** 컴포넌트가 포함됩니다. 그런 다음 엔티티의 위치, 회전 또는 크기를 변경하여 엔티티의 Transform 컴포넌트 값을 암시적으로 변경할 수 있습니다. Scene Editor의 UI를 사용해 값을 숫자로 입력하면 더 정확하게 설정할 수도 있습니다.

## 코드 기본 사항

![](https://3980763956-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
// 새 엔티티 만들기
const ball = engine.addEntity()

// 엔티티에 도형을 지정해 표시되도록 합니다
MeshRenderer.setSphere(ball)

// 엔티티에 Transform 컴포넌트 지정
Transform.create(ball, {
	position: Vector3.create(5, 1, 5),
	scale: Vector3.create(1, 1, 1),
	rotation: Quaternion.Identity(),
})
```

씬에서 일정 시간 동안 엔티티를 이동하거나 회전하거나 크기를 조정하려면 프레임마다 이 컴포넌트의 값을 조금씩 변경하세요. 자세한 내용과 모범 사례는 다음을 참조하세요. [엔티티 이동](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/move-entities.md) 하세요.

생략한 필드에는 기본값이 적용됩니다. position은 `0, 0, 0`, 회전은 없고, 크기는 `1, 1, 1`입니다. 필드를 `undefined`로 설정하지 말고 생략하세요. 필드에 명시적으로 `undefined`값을 지정하면(예: 값이 설정되지 않은 변수에서 가져오는 경우) 기본값이 대체됩니다. 그러면 Transform.create()를 호출한 줄이 아니라 다음 엔진 업데이트 중에 씬에서 오류가 발생합니다. `Transform.create()`.

```ts
// ❌ savedRotation이 undefined이면 나중에 씬에서 오류가 발생합니다
Transform.create(ball, { position: Vector3.create(5, 1, 5), rotation: savedRotation })

// ✅ 유효한 값으로 대체합니다
Transform.create(ball, { position: Vector3.create(5, 1, 5), rotation: savedRotation ?? Quaternion.Identity() })
```

{% hint style="warning" %}
**📔 참고**: `Vector3` 및 `Quaternion` 은 다음을 통해 가져와야 합니다.

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

자세한 내용은 [가져오기](https://docs.decentraland.org/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 에서 쉽게 처리하는 방법을 확인하세요.
{% endhint %}

## 위치

`position` 은 *3D 벡터*이며, 세 축 모두에서 엔티티 중심의 위치를 설정합니다. *x*, *y*및 *z*. 자세한 내용은 [기하 도형 유형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/special-types.md) 을 참조하세요.

```ts
// 새 엔티티 만들기
const ball = engine.addEntity()

// 미리 정의된 위치로 변환 생성
Transform.create(ball, {
	  position: Vector3.create(5, 1, 5)
})

// 변환의 변경 가능한 버전 가져오기
const mutableTransform = Transform.getMutable(ball)

// 객체로 위치 설정
mutableTransform.position = { x: 5, y: 1, z: 5 }

// 객체로 위치 설정(대체 구문)
mutableTransform.position = Vector3.create(2, 1, 4)

// 각 축을 개별적으로 설정
mutableTransform.position.x = 3
mutableTransform.position.y = 1
mutableTransform.position.z = 3
```

위치를 설정할 때는 다음 사항에 유의하세요.

* 위치 벡터의 숫자는 *미터* 를 나타냅니다(엔티티가 크기가 조정된 엔티티의 자식인 경우는 제외).
* 단일 구획으로 이루어진 씬의 크기는 16m x 16m입니다. 지면 높이에서 씬의 중심은 `x:8, y:0, z:8`에 있습니다. 씬이 여러 구획으로 이루어진 경우 중심은 구획 배치에 따라 달라집니다.
* `x:0, y:0, z:0` 은 지면 높이에 있는 씬 기본 구획의 *남서쪽* 모서리를 나타냅니다.

  > 팁: 씬 미리보기를 볼 때 씬의 (0,0,0) 지점에 나침반이 표시되며, 각 축의 이름을 기준으로 방향을 확인할 수 있습니다.

  > 참고: `base` 의 속성을 수정하면 씬의 기본 구획을 변경할 수 있습니다. *scene.json*.
* 방향을 더 쉽게 파악하려면 *왼손* 을 사용하세요.
  * 앞을 가리키는 검지는 *z* 축이고,
  * 옆을 가리키는 중지는 *x* 축이며,
  * 위쪽을 가리키는 엄지는 *y* 축입니다.
* 엔티티가 다른 엔티티의 자식인 경우, `x:0, y:0, z:0` 은 씬 내 위치와 관계없이 부모 엔티티의 중심을 나타냅니다.
* 씬의 모든 엔티티는 항상 해당 엔티티가 차지하는 구획의 경계 안에 위치해야 합니다. 엔티티가 이 경계를 벗어나면 오류가 발생합니다.

  > 팁: 미리보기 모드에서 씬을 볼 때 경계를 벗어난 엔티티는 *빨간색으로*.
* 씬의 높이도 제한됩니다. 씬이 차지하는 구획 수와 관계없이 모든 씬의 최대 높이는 330미터입니다. 200미터보다 높은 곳에 배치된 엔티티는 멀티플레이어 동기화 문제가 발생할 수 있습니다. 자세한 내용은 [씬 제한](https://docs.decentraland.org/creator/content-creator-ko/sdk7/optimizing/scene-limitations.md) 을 참조하세요.

## 회전

`rotation` 은 다음과 같이 저장됩니다: [*쿼터니언*](https://en.wikipedia.org/wiki/Quaternion), 네 개의 숫자로 이루어진 체계입니다. *x*, *y*, *z* 및 *w*입니다. 각 숫자의 범위는 -1부터 1까지입니다. 자세한 내용은 [기하 유형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/special-types.md) 을 참조하세요.

```ts
// 새 엔티티 만들기
const cube = engine.addEntity()

// 미리 정의된 0 회전으로 변환 생성
Transform.create(cube, {
	  rotation: Quaternion.Identity()
})

// 변환의 변경 가능한 버전 가져오기
const mutableTransform = Transform.getMutable(cube)

// 오일러 각을 사용해 객체로 회전 설정
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)

// 객체로 회전 설정
mutableTransform.rotation = { x: 0.1, y: 0.5, z: 0.5, w: 0 }

// 각 축을 개별적으로 설정
mutableTransform.rotation.x = 0
mutableTransform.rotation.y = 1
mutableTransform.rotation.z = 0.3
mutableTransform.rotation.w = 0
```

회전 필드에는 다음을 사용해 설정할 수도 있습니다: [*오일러* 각](https://en.wikipedia.org/wiki/Euler_angles), 더 일반적으로 사용되는 *x*, *y* 및 *z* 표기법은 대부분의 사람에게 익숙하며, 숫자 범위는 0부터 360까지입니다. 오일러 각을 사용하려면 다음 표기법 중 하나를 사용하세요:

```ts
// 오일러 각으로 미리 정의된 회전을 사용해 변환 생성
Transform.create(cube, {
	  rotation: Quaternion.fromEulerDegrees(0, 90, 0)
})

// 변환의 변경 가능한 버전 가져오기
const mutableTransform = Transform.getMutable(cube)

// 오일러 각을 사용해 객체로 회전 설정
mutableTransform.rotation = Quaternion.fromEulerDegrees(0, 90, 0)
```

오일러 각을 나타내는 데 *3D 벡터* 를 사용하는 경우, *x*, *y* 및 *z* 는 각 축의 회전을 나타내며, 단위는 도입니다. 한 바퀴를 완전히 돌려면 360도가 필요합니다.

엔티티의 회전을 가져오면 기본적으로 쿼터니언이 반환됩니다. 오일러 각으로 표현된 회전을 얻으려면 다음을 사용하세요: `Quaternion.toEulerAngles()`:

```ts
// 변환의 읽기 전용 버전 가져오기
const transform = Transform.get(cube)

// 오일러 각도로 표현된 회전을 가져옵니다
const eulerAngle = Quaternion.toEulerAngles(transform.rotation)
```

## 엔티티의 전역 위치와 회전 가져오기

다음 `getWorldPosition` 및 `getWorldRotation` 함수는 엔티티의 전역 위치와 회전을 반환합니다. 즉, 부모 계층 구조를 고려하지 않고 플레이어에게 보이는 항목의 위치나 회전을 반환합니다.

* `getWorldPosition(engine, entity: Entity): Vector3Type`: 이 함수는 엔티티의 월드 위치를 반환합니다. 엔티티에 부모 엔티티가 있는 경우 모든 부모 엔티티의 위치를 고려하여 반환합니다. `{x: 0, y: 0, z: 0}` 엔터티에 Transform이 없는 경우입니다.

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

* `getWorldRotation(engine, entity: Entity): QuaternionType`: 이 함수는 엔터티 자체의 회전이 있는 경우 부모 엔터티의 모든 회전을 고려하여 엔터티의 월드 회전을 반환합니다. 반환값은 `Quaternion` 형이며, 항등 쿼터니언을 반환합니다 `{x: 0, y: 0, z: 0, w: 1}` 엔터티에 Transform이 없는 경우입니다.

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

{% hint style="info" %}
**참고:** 전역 위치와 전역 회전은 Genesis City가 아니라 장면 내부의 좌표를 기준으로 합니다.
{% endhint %}

## 플레이어를 향하게 하기

엔터티에 *Billboard* 컴포넌트를 추가하면 항상 플레이어의 카메라를 향하도록 회전합니다.

빌보드는 90년대 3D 게임에서 흔히 사용된 기법입니다. 대부분의 엔터티가 항상 플레이어를 향하는 2D 평면이었죠. 같은 아이디어를 3D 모델을 회전하는 데에도 사용할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 빌보드는 아바타가 아니라 **카메라를 향합니다**. 3인칭 시점에서는 카메라가 아바타의 뒤쪽 위에 위치하므로 둘은 서로 다른 곳에 있습니다. 따라서 카메라를 향하는 빌보드는 아바타에게서 눈에 띄게 돌아서 있습니다. 대신 아바타를 향하게 하려면 `targetEntity` 를 `engine.PlayerEntity`.
{% endhint %}

```ts
// 새 엔티티 만들기
const cube = engine.addEntity()

// 엔티티에 눈에 보이는 모양 지정
MeshRenderer.setBox(cube)

// 미리 정의된 위치로 변환 생성
Transform.create(cube, {
	  position: Vector3.create(5, 1, 5)
})

// 엔티티에 Billboard 컴포넌트 추가
Billboard.create(cube, {})
```

다음 매개변수로 빌보드의 동작을 설정할 수 있습니다:

* `billboardMode`: 다음 값을 사용해 `BillboardMode` 플레이어를 향하도록 자동으로 회전할 축을 설정합니다.
  * `BillboardMode.BM_ALL`: 엔터티가 모든 회전축에서 플레이어를 향해 회전합니다. 플레이어가 엔터티보다 높은 곳에 있으면 엔터티가 위쪽을 향합니다.
  * `BillboardMode.BM_NONE`: 엔터티가 전혀 회전하지 않습니다.
  * `BillboardMode.BM_X`: 엔터티가 다음 축에서만 회전합니다. *x* 회전축입니다.
  * `BillboardMode.BM_Y`: 엔티티는 *y* 회전축을 중심으로만 회전합니다. 왼쪽과 오른쪽으로만 회전하고 위아래로는 회전하지 않습니다. 플레이어가 엔티티보다 위나 아래에 있어도 지면과 수직을 유지합니다.
  * `BillboardMode.BM_Z`: 엔티티는 *z* 회전축을 중심으로만 회전합니다.
* `targetEntity`: (선택 사항) 플레이어의 카메라 대신 빌보드가 바라보도록 할 엔티티입니다. 참조된 엔티티가 존재하지 않으면(예를 들어 아직 생성되지 않았거나 제거된 경우) 빌보드는 회전을 멈추고 해당 엔티티가 다시 존재할 때까지 마지막 방향을 유지합니다. 이 값을 `engine.CameraEntity` 로 설정하는 것은 값을 설정하지 않는 것과 같습니다.

```ts
// 평면 빌보드
const perpendicularPlane = engine.addEntity()

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

MeshRenderer.setPlane(perpendicularPlane)

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

// 텍스트 라벨
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)

// 플레이어 대신 다른 엔티티를 바라보는 표지판
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" %}
**💡 팁**: 빌보드는 *텍스트* 엔티티에 추가하면 항상 읽기 쉽게 표시되므로 매우 유용합니다.
{% endhint %}

아바타가 아닌 카메라를 따라가도록 하려면 `targetEntity` 를 `engine.PlayerEntity` 로 설정하세요. 이름표, 말풍선 등 플레이어의 시점이 아니라 아바타에 속하는 요소에 이 설정을 사용하면 됩니다.

```ts
// 카메라가 아니라 아바타를 바라보도록 회전하는 라벨
Billboard.create(label, {
	targetEntity: engine.PlayerEntity,
	billboardMode: BillboardMode.BM_Y,
})
```

아바타의 위치는 발에 있으므로, 머리 위의 라벨은 아바타 쪽으로 아래를 향해 기울어집니다. `BM_Y` 를 사용하면 라벨이 똑바로 선 채 왼쪽과 오른쪽으로만 회전합니다.

### 빌보드가 바라보는 방향

빌보드는 로컬 **-Z** 축이 자신이 향하는 방향을 가리킵니다. 빌보드에 다른 엔티티를 자식으로 배치할 때 이 점이 중요합니다.

* 로컬 **+Z** 오프셋된 자식은 빌보드 **뒤에** 위치하여 빌보드에 가려집니다.
* 로컬 **-Z** 오프셋된 자식은 **앞에**위치하여 보는 사람과 더 가까워집니다.

빌보드로 표시되는 레이블 뒤에 프레임이나 배경을 배치하려면 **+Z**방향으로 오프셋합니다. 레이블 앞에 강조 표시를 배치하려면 **-Z**.

엔티티의 `rotation` 값은 빌보드가 플레이어를 따라다녀도 변경되지 않습니다. 엔티티의 `Transform` 컴포넌트

엔티티에 `Billboard` 컴포넌트와 `Transform` 컴포넌트가 모두 있고, 여기에 `rotation` 값이 설정되어 있으면 플레이어에게 엔티티가 빌보드로서 회전하는 것처럼 보입니다. 빌보드가 모든 축에 영향을 주지 않는다면 나머지 축은 해당 컴포넌트에 따라 회전합니다. `Transform` 컴포넌트.

{% hint style="warning" %}
**📔 참고**: 여러 플레이어가 동시에 접속해 있으면 각 플레이어에게 빌보드 모드의 엔티티가 자신을 향하는 것으로 보입니다. 빌보드 회전은 플레이어마다 로컬에서 계산되므로 다른 플레이어가 보는 장면에는 영향을 주지 않습니다. 단, targetEntity가 설정된 빌보드에는 해당하지 않습니다. 대상 엔티티의 위치는 장면의 일부이므로 모든 플레이어에게 빌보드가 같은 방향을 향하는 것으로 보입니다. `targetEntity`가 있는 빌보드에는 적용되지 않습니다. 대상의 위치는 장면의 일부이므로 모든 플레이어에게 해당 빌보드가 같은 방향을 향하는 것으로 보입니다.
{% endhint %}

## 좌표를 향하게 하기

엔티티 A가 엔티티 B를 바라보게 하려면 다음 단계를 따릅니다.

```
1) 엔티티 B의 위치에서 엔티티 A의 위치를 빼서 두 엔티티 사이의 거리를 나타내는 벡터를 구합니다.
2) 벡터의 방향은 유지하면서 길이가 1이 되도록 정규화합니다.
3) `Quaternion.lookRotation`을 사용해 해당 방향으로 회전하는 것을 나타내는 쿼터니언 회전을 구합니다.
4) 해당 쿼터니언을 엔티티 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)
}
```

## 크기 조정

`scale` 도 *3D 벡터*이며, `Vector3` 객체를 포함하며, 여기에는 *x*, *y* 및 *z* 축의 배율도 포함됩니다. 기본 도형이든 3D 모델이든 엔티티의 모양은 그에 따라 크기가 조정됩니다.

기본 배율은 1입니다. 엔티티를 늘리려면 1보다 큰 값을, 줄이려면 1보다 작은 값을 지정하세요.

```ts
// 새 엔티티 만들기
const ball = engine.addEntity()

// 미리 정의된 위치로 변환 생성
Transform.create(ball, {
	  scale: Vector3.create(5, 5, 5)
})

// 변환의 변경 가능한 버전 가져오기
const mutableTransform = Transform.getMutable(ball)

// Vector3로 배율 설정

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

// 객체로 위치 설정
mutableTransform.scale = { x: 5, y: 1, z: 5 }

// 각 축을 개별적으로 설정
mutableTransform.scale.x = 3
mutableTransform.scale.y = 3
mutableTransform.scale.z = 2
```

## 부모의 변환 상속

엔티티가 다른 엔티티 안에 중첩되면 자식 엔티티는 부모의 컴포넌트를 상속합니다. 즉, 부모 엔티티의 위치, 배율 또는 회전을 변경하면 자식에도 영향을 줍니다. 자식 엔티티의 위치, 회전 및 배율 값은 부모의 값을 덮어쓰지 않고, 부모의 값과 결합됩니다.

자식 엔티티의 `parent` 필드를 설정하여 다른 엔티티를 해당 엔티티의 부모로 지정합니다. 이 필드는 자식 엔티티의 `Transform` 컴포넌트에 있습니다.

부모 엔티티의 배율을 조정하면 자식 엔티티의 모든 위치 값도 함께 조정됩니다.

```ts
// 엔티티 생성
const parentEntity = engine.addEntity()
const childEntity = engine.addEntity()

// 부모의 Transform 생성
Transform.create(parentEntity, {
	position: Vector3.create(3, 1, 1),
	scale: Vector3.create(0.5, 0.5, 0.5),
})

// 자식의 Transform을 생성하고 자식으로 지정
Transform.create(childEntity, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity,
})
```

이 예시에서 자식 엔티티의 부모 배율이 0.5이므로 자식 엔티티도 0.5배로 축소됩니다. 자식 엔티티의 위치 역시 부모를 기준으로 합니다. 부모의 위치에 자식의 위치를 더해야 합니다. 이 경우 부모의 크기가 절반으로 조정되었으므로 자식의 변환도 비례하여 축소됩니다. 절대 좌표로 보면 자식의 위치는 `{ x: 3, y: 1.5, z: 1 }`입니다. 부모에 `rotation`이 있으면 자식이 이동하는 축이 바뀌므로 자식의 최종 위치에도 영향을 줍니다.

자식 엔티티의 Transform에 `position` 이 없으면 기본값은 `0,0,0`이며, 이 경우 자식은 부모와 같은 위치에 놓입니다.

셰이프 컴포넌트가 없는 보이지 않는 엔티티를 부모로 사용해 여러 엔티티를 묶을 수 있습니다. 이 엔티티는 렌더링된 장면에 표시되지 않지만, 자식들을 그룹화하고 모두에게 변환을 적용하는 데 사용할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 엔티티가 자기 자신의 조상이 되는 계층 구조의 순환을 만들지 마세요. SDK는 이러한 순환을 감지하고 관련 엔티티의 이름을 포함한 경고를 로그에 기록합니다. 부모-자식 관계를 수정할 때까지 해당 엔티티의 위치가 올바르게 설정되지 않습니다.
{% endhint %}

## 아바타에 엔티티 연결

플레이어에 엔티티를 연결하는 방법은 세 가지입니다.

* 엔티티를 다음의 자식으로 만듭니다: **아바타 엔티티**
* 엔티티를 다음의 자식으로 만듭니다: **카메라 엔티티**
* 다음을 사용합니다: **AvatarAttach 컴포넌트**

엔티티를 아바타에 연결하는 가장 간단한 방법은 부모를 다음 예약 엔티티로 설정하는 것입니다: [예약 엔티티](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/entities-components.md#reserved-entities) `engine.PlayerEntity`입니다. 그러면 엔티티가 플레이어의 위치를 따라 함께 움직입니다.

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

엔티티를 다음 [예약 엔티티](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/entities-components.md#reserved-entities) `engine.CameraEntity`로 설정할 수도 있습니다. 1인칭 시점에서 카메라 엔티티를 사용하면 연결된 엔티티가 카메라의 움직임을 따라갑니다. 카메라가 위를 향할 때도 총의 3D 모델을 항상 화면에 표시하는 것처럼, 무언가를 항상 시야에 두고 싶을 때 유용합니다.

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

아바타의 뼈대 중 하나에 오브젝트를 연결해 아바타의 애니메이션에 맞춰 함께 움직이게 하려면 엔티티에 `AvatarAttach` 컴포넌트를 추가합니다.

아바타의 여러 앵커 포인트 중에서 선택할 수 있습니다. 대부분의 포인트는 플레이어의 스켈레톤에 연결되어 플레이어의 애니메이션을 따라갑니다. 예를 들어 오른손 앵커 포인트를 사용하면 플레이어가 달리면서 아바타의 팔을 흔들거나 휘두를 때 연결된 엔티티도 움직입니다. 마치 플레이어가 손에 엔티티를 들고 있는 것처럼 보입니다.

```ts
// 기본적으로 avatarId를 설정하지 않으면 메인 플레이어에 연결되며, engine.PlayerEntity가 사용됩니다
AvatarAttach.create(myEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// ID로 플레이어에 연결
AvatarAttach.create(myEntity, {
	avatarId: '0xAAAAAAAAAAAAAAAAA',
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})
```

AvatarAttach `컴포넌트를 생성할 때` 다음 데이터가 포함된 객체를 전달합니다:

* `avatarId`: *선택 사항* 연결할 플레이어의 ID입니다. Ethereum 지갑으로 접속한 플레이어의 경우, 플레이어의 Ethereum 주소와 같습니다. 지정하지 않으면 엔티티가 로컬 플레이어의 아바타에 연결됩니다.
* `anchorPointId`: 아바타 스켈레톤에서 엔티티를 연결할 앵커 포인트입니다. 열거형 `AvatarAnchorPointType`.

{% hint style="warning" %}
**📔 참고**: 씬의 모든 플레이어에게 같은 플레이어에게 연결된 오브젝트를 표시하려면, 예를 들어 플레이어 A가 오브젝트를 집어 왼손에 든 모습을 모두에게 보여 주려면 `avatarId`에 값을 지정해야 합니다. 지정하지 않으면 모든 플레이어에게 각자의 아바타에 연결된 오브젝트가 표시됩니다.
{% endhint %}

다음 예에서는 특정 아바타에 연결된 엔티티를 배치하여 다른 모든 플레이어에게도 같은 아바타에 연결된 모습이 보이도록 합니다.

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

  // 기타 컴포넌트

  syncEntity(entity, [AvatarAttach.componentId])

}
```

다음 앵커 포인트를 `AvatarAnchorPointType` 열거형에서 사용할 수 있습니다:

* `AAPT_RIGHT_HAND`: 플레이어의 오른손에 고정
* `AAPT_LEFT_HAND`: 플레이어의 왼손에 고정됩니다
* `AAPT_HEAD`: 플레이어 머리 중앙에 고정됩니다.
* `AAPT_NECK`: 플레이어의 목 아래쪽에 고정됩니다.
* `AAPT_SPINE`: 척추의 위쪽 부분에 고정됩니다.
* `AAPT_SPINE1`: 척추의 중간 부분에 고정됩니다.
* `AAPT_SPINE2`: 척추의 아래쪽 부분에 고정됩니다.
* `AAPT_HIP`: 엉덩이뼈에 고정됩니다.
* `AAPT_LEFT_SHOULDER`: 왼쪽 어깨에 고정됩니다.
* `AAPT_LEFT_ARM`: 어깨 높이에 있는 왼팔의 첫 번째 뼈에 고정됩니다.
* `AAPT_LEFT_FOREARM`: 왼쪽 아래팔 뼈에 고정됩니다.
* `AAPT_LEFT_HAND_INDEX`: 왼쪽 검지 끝에 고정됩니다.
* `AAPT_RIGHT_SHOULDER`: 오른쪽 어깨에 고정됩니다.
* `AAPT_RIGHT_ARM`: 어깨 높이에 있는 오른팔의 첫 번째 뼈에 고정됩니다.
* `AAPT_RIGHT_FOREARM`: 오른쪽 아래팔 뼈에 고정됩니다.
* `AAPT_RIGHT_HAND_INDEX`: 오른쪽 검지 끝에 고정됩니다.
* `AAPT_LEFT_UP_LEG`: 왼쪽 다리의 위쪽 다리뼈에 고정됩니다.
* `AAPT_LEFT_LEG`: 왼쪽 다리의 아래쪽 다리뼈에 고정됩니다.
* `AAPT_LEFT_FOOT`: 왼쪽 발목에 고정됩니다.
* `AAPT_LEFT_TOE_BASE`: 왼쪽 발가락 끝에 고정됩니다.
* `AAPT_RIGHT_UP_LEG`: 오른쪽 다리의 위쪽 다리뼈에 고정됩니다.
* `AAPT_RIGHT_LEG`: 오른쪽 다리의 아래쪽 다리뼈에 고정됩니다.
* `AAPT_RIGHT_FOOT`: 오른쪽 발목에 고정됩니다.
* `AAPT_RIGHT_TOE_BASE`: 오른쪽 발가락 끝에 고정됩니다.
* `.AAPT_NAME_TAG`: 플레이어 이름표 바로 위에 떠 있으며 플레이어의 애니메이션에 영향을 받지 않습니다.

  > 참고: 이름표의 높이는 플레이어가 착용한 웨어러블의 높이에 따라 동적으로 조정됩니다. 따라서 키가 큰 모자를 쓴 플레이어의 이름표는 다른 플레이어보다 조금 더 높게 표시됩니다.
* `AAPT_POSITION` *사용 중단됨*: 플레이어의 전체 위치입니다. 플레이어의 발보다 0.8 높은 위치에 표시됩니다.

  >

{% hint style="warning" %}
\> \*\*📔 참고\*\*: \`AAPT\_POSITION\`은 사용 중단되었습니다. 플레이어의 전체 위치를 따르려면 엔티티를 아바타 엔티티의 자식으로 만드는 것이 가장 좋습니다. 예시는 이 섹션의 시작 부분을 참조하세요. >
{% endhint %}

{% hint style="info" %}
**💡 팁**: 이 값을 사용하려면 다음을 입력하세요. `AvatarAnchorPointType.` 그러면 VS Code가 드롭다운에 전체 옵션 목록을 표시합니다.
{% endhint %}

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

엔티티 렌더링은 각 씬 인스턴스에서 로컬로 결정됩니다. 한 플레이어에 엔티티를 연결해도 그 플레이어를 보고 있는 다른 플레이어에게는 표시되지 않습니다. 엔티티를 기본 로컬 플레이어에 연결하면 각 플레이어는 자신의 아바타에 연결된 엔티티를 보게 됩니다.

{% hint style="warning" %}
**📔 참고**: 아바타에 연결된 엔티티가 렌더링되려면 씬 경계 안에 있어야 합니다. 플레이어가 씬 밖으로 나가면 다시 씬 안으로 들어올 때까지 연결된 엔티티가 렌더링되지 않습니다. 스마트 웨어러블에는 이러한 제한이 없습니다.
{% endhint %}

해당 `AvatarAttach` 컴포넌트는 다음 컴포넌트의 값을 덮어씁니다. `Transform` 컴포넌트에 어떤 값을 지정하더라도 `Transform` 해당 컴포넌트의 값은 엔티티와 플레이어의 Transform 간 상대 위치로 대체됩니다. 플레이어가 이동하고 애니메이션을 재생하면 이 값은 매 프레임 업데이트됩니다.

아바타의 앵커 지점에서 오프셋을 적용하거나 다른 회전 또는 크기를 지정해 엔티티의 위치를 조정해야 한다면, 부모 엔티티를 통해 조정하세요.

1. Transform만 포함하는 보이지 않는 엔티티를 만들고 `Transform` 와 `AvatarAttach` 컴포넌트입니다. 해당 `Transform` 값은 플레이어가 이동하면 덮어쓰입니다
2. 이 부모 엔티티의 자식으로 연결할 엔티티를 설정합니다. 해당 `Transform` 값은 앵커 지점으로부터의 오프셋을 나타낼 수 있습니다.

```ts
// 부모 엔티티 생성
const parentEntity = engine.addEntity()

// 부모 엔티티를 플레이어에 연결
AvatarAttach.create(parentEntity, {
	anchorPointId: AvatarAnchorPointType.AAPT_NAME_TAG,
})

// 자식 엔티티 생성
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" %}
**📔 참고**: 연결된 엔티티에 콜라이더가 있으면 플레이어의 이동을 막거나 떨림 현상을 일으킬 수 있습니다. 연결된 엔티티의 콜라이더에서 물리 레이어를 비활성화하는 것이 좋습니다. 자세한 내용은 다음을 참조하세요. [충돌 레이어](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md#collision-layers)
{% endhint %}

{% hint style="warning" %}
**📔 참고**: 자식 엔티티의 전역 위치 및/또는 회전을 확인하려면 다음을 사용할 수 있습니다. `getWorldPosition` 및 `getWorldRotation` 함수를 사용하세요. 자세한 내용은 다음에서 확인할 수 있습니다. [전역 위치 및 회전 가져오기](#getting-global-position-and-rotation-of-an-entity) 섹션.
{% endhint %}

### 다른 플레이어에게 부착하기

다음을 사용할 수 있습니다. `AvatarAttach` 컴포넌트를 사용해 엔티티를 다른 플레이어에게 부착할 수 있습니다. 이렇게 하려면 플레이어의 ID를 알아야 합니다.

엔티티를 다른 플레이어의 아바타에 부착하려면 해당 사용자의 ID를 다음 필드에 입력해야 합니다. `avatarId`. 이 데이터를 얻는 [방법은 여러 가지가](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/user-data.md#get-player-data) 있습니다.

{% hint style="warning" %}
**📔 참고**: Ethereum 지갑을 연결한 플레이어의 경우, 해당 플레이어의 `userId` 는 Ethereum 주소와 같습니다.
{% endhint %}

다른 주변 플레이어의 `userId` 는 `getPlayer()`

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

이를 `AvatarAttach`와 함께 사용하면 다음 코드로 씬의 다른 모든 플레이어 머리 위에 떠 있는 큐브를 추가할 수 있습니다.

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

다른 사용자의 ID를 가져오는 다른 방법은 [플레이어 데이터 가져오기](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/user-data.md#get-player-data).

{% hint style="warning" %}
**📔 참고**: 다른 플레이어의 엔티티를 내 엔티티의 `parent` 로 설정하지 마세요. 엔진은 씬에서 읽을 수 있도록 해당 엔티티의 `Transform` 을 기록하지만, 이 엔티티는 내 엔티티가 매달릴 수 있는 부모가 아닙니다. 따라서 자식 엔티티는 씬 루트로 돌아가 씬의 원점에 머뭅니다. 위에서 보인 것처럼 대신 플레이어 주소와 함께 `AvatarAttach` 를 사용하세요.
{% endhint %}

플레이어가 들어오고 나가면 플레이어 엔티티 ID가 재사용되므로, 나중에 같은 엔티티가 다른 플레이어에게 할당될 수 있습니다. 플레이어마다 마커를 하나씩 유지한다면, 마커를 만든 주소를 저장해 매 프레임마다 비교하세요. 엔티티의 주소가 바뀌면 기존 마커를 삭제하고 새 마커를 만드세요.

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

// 엔티티 ID가 재사용되었는지 확인할 수 있도록 마커를 만든 주소를 저장합니다
const markers = new Map<Entity, { address: string; marker: Entity }>()

function markerSystem() {
	// 플레이어가 나갔거나 엔티티 ID가 다른 플레이어에게 할당된 경우 마커를 제거합니다
	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)
```

## 씬 경계

씬의 모든 엔티티는 씬 경계 안에 있어야 합니다. 경계 밖에는 다른 플레이어가 소유한 토지가 있기 때문입니다.

미리 보기를 실행할 때 모델의 일부가 이 한계를 넘어가면, 경계를 넘은 부분은 잘려 렌더링되지 않습니다. 미리 보기뿐 아니라 게시된 씬에서도 마찬가지입니다.

엔티티가 이동할 때 씬 내 위치가 계속 확인됩니다. 엔티티가 씬을 벗어났다가 다시 돌아오면 제거된 후 정상적으로 다시 렌더링됩니다.

씬 바닥의 격자는 씬의 경계를 보여 줍니다. 기본적으로 경계는 *x* 축과 *z* 축에서 0부터 16까지이며, *y* 축. 엔티티를 지하, 즉 축에서 0보다 아래에 자유롭게 배치할 수 있습니다. *y* 축.

{% hint style="info" %}
**💡 팁**: 씬에 구획이 더 필요하면 프로젝트의 `scene.json` 파일에 추가할 수 있습니다. 자세한 방법은 [씬 메타데이터](https://docs.decentraland.org/creator/content-creator-ko/sdk7/kinds-of-projects/scene-metadata.md) 를 참조하세요. 구획을 추가하면 그리드가 확장되어 추가된 구획까지 덮는 것을 확인할 수 있습니다.
{% 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-ko/sdk7/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.
