> 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/shape-components.md).

# 형상 컴포넌트

엔티티에 3D 형태와 충돌을 부여하는 다양한 컴포넌트에 대해 알아봅니다.

Decentraland의 3차원 장면은 다음을 기반으로 합니다. [엔티티-컴포넌트](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) 모델입니다. 장면의 모든 요소는 *엔티티*이며, 각 엔티티에는 특성과 기능을 정의하는 *컴포넌트* 가 포함될 수 있습니다.

엔티티가 렌더링되는 모양은 사용하는 컴포넌트에 따라 결정됩니다.

![](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)

## Creator Hub의 Scene Editor 사용

엔티티에 모양을 지정하는 가장 쉬운 방법은 Scene Editor를 사용하는 것입니다. 원시 도형을 제공하는 **Mesh Renderer** 컴포넌트나 파일의 3D 모델을 참조하는 **GLTF** 컴포넌트를 추가할 수 있습니다. 자세한 내용은 [컴포넌트 추가](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/build/components.md#add-components).

## 원시 도형

흔히 *원시 도형*이라고 하는 몇 가지 기본 도형을 엔티티에 `MeshRenderer` 컴포넌트를 지정해 추가할 수 있습니다.

사용 가능한 도형은 다음과 같습니다. 일부 도형에는 해당 도형에만 적용되는 선택적 추가 필드가 있습니다.

* **상자**:

  엔티티를 전달해 `MeshRenderer.setBox()`를 사용합니다. 텍스처 정렬을 지정하려면 선택적 추가 필드로 `uvs` 를 전달합니다. 자세한 내용은 [머티리얼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md) 을 참조하세요.
* **평면**:

  엔티티를 전달해 `MeshRenderer.setPlane()`를 사용합니다. 텍스처 정렬을 지정하려면 선택적 추가 필드로 `uvs` 를 전달합니다. 자세한 내용은 [머티리얼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md) 을 참조하세요.
* **구**:

  엔티티를 전달해 `MeshRenderer.setSphere()`를 사용합니다.
* **원기둥**:

  엔티티를 전달해 `MeshRenderer.setCylinder()`를 사용합니다. 원기둥을 수정하려면 선택적 추가 필드로 `radiusTop` 및 `radiusBottom` 을 전달합니다.

  팁: 다음 중 하나를 설정하세요 `radiusTop` 또는 `radiusBottom` 을 0으로 설정하면 원뿔이 됩니다.

다음 예제에서는 정육면체를 만듭니다.

```ts
const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)
```

다음 예제에서는 `radiusTop` 이 0인 원기둥을 만들어 원뿔을 생성합니다.

```ts
const myCone = engine.addEntity()

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

MeshRenderer.setCylinder(myCone, 1, 0)
```

기본 도형에는 머티리얼이 포함되어 있지 않습니다. 색상이나 텍스처를 지정하려면 동일한 엔티티에 [머티리얼 컴포넌트](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md) 를 할당해야 합니다.

기본 도형을 클릭할 수 있게 하거나 플레이어가 도형을 통과하지 못하게 하려면 엔티티에 *콜라이더* 컴포넌트를 통해 [MeshCollider](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md) 추가해야 합니다.

이미 `MeshRenderer` 컴포넌트가 있는 엔티티의 모양을 변경하려면 `MeshRenderer.setBox()` 또는 다른 도우미 함수 중 하나를 실행하면 원래 모양이 덮어써집니다. 원래 모양을 제거하거나 `MeshRenderer` 고급 구문을 사용할 필요는 없습니다.

```ts
const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

// 모양 덮어쓰기
MeshRenderer.setSphere(myCube)
```

{% hint style="warning" %}
**📔 참고**: `MeshRenderer` 컴포넌트는 다음을 통해 가져와야 합니다.

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

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

## 3D 모델

더 복잡한 모양은 Blender 같은 외부 도구에서 3D 모델을 만든 다음, 이를 *.glTF* 또는 *.glb* (바이너리 *.glTF*). [glTF](https://www.khronos.org/gltf) (GL 전송 형식)는 Khronos가 공개 프로젝트로 제공하는 형식입니다. 효율적이며 최신 웹 기술과의 상호 운용성이 뛰어나고, 3D 에셋을 위한 공통의 확장 가능한 형식입니다.

외부 모델을 씬에 추가하려면 엔티티에 `GltfContainer` 컴포넌트를 추가하고 해당 `src` 를 모델이 포함된 glTF 파일의 경로로 설정합니다.

```ts
const houseEntity = engine.addEntity()

GltfContainer.create(houseEntity, {
	src: 'models/House.gltf',
})
```

이 `src` 필드는 필수입니다. 컴포넌트를 생성할 때 값을 지정해야 합니다. 위 예시에서 모델은 씬 프로젝트 폴더의 최상위 수준에 있는 `models` 폴더에 있습니다.

{% hint style="info" %}
**💡 팁**: 모델은 씬 내부의 `assets/scene/models` 폴더에 별도로 보관하는 것을 권장합니다.
{% endhint %}

glTF 모델에는 자체적으로 포함된 텍스처, 머티리얼, 콜라이더 및 애니메이션이 들어 있을 수 있습니다. 자세한 내용은 [3D 모델](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/3d-models.md) 을 참고하세요. 모델의 머티리얼을 재정의하려면 [GltfNodeModifiers](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 컴포넌트를 사용하세요. 자세한 내용은 [glTF 머티리얼 수정](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 을 참고하세요.

플레이어가 3D 모델을 통과하지 못하게 하거나 모델을 클릭할 수 있게 하려면 [콜라이더](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md), 즉 모델에 포함된 콜라이더나 `MeshCollider` 컴포넌트가 있어야 합니다.

모든 모델과 셰이더, 텍스처가 [씬 제한](https://docs.decentraland.org/creator/content-creator-ko/sdk7/optimizing/scene-limitations.md).

{% hint style="warning" %}
**📔 참고**: `GltfContainer` 컴포넌트를 사용하려면 다음을 통해 가져와야 합니다.

`import { GltfContainer } from "@dcl/sdk/ecs"`

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

### 3D 모델 미리 로드하기

경우에 따라 맞춤형 3D 모델을 씬에 추가하지만 즉시 사용하지는 않습니다. 예를 들어, 플레이어가 다른 오브젝트와 상호작용할 때만 맞춤형 의자 모델을 불러올 수 있습니다. 이 경우 첫 상호작용에서는 모델의 다운로드와 로딩이 완료될 때까지 시간이 걸릴 수 있습니다.

이를 방지하려면 `AssetLoad.create` 메서드를 사용해 에셋이 필요하기 전에 다운로드되도록 하세요.

```ts
import { AssetLoad } from "@dcl/sdk/ecs"

AssetLoad.create(engine.RootEntity, {
  assets: [
    "assets/scene/bundle1/explosion.glb",
  ],
})
```

자세한 내용은 [리소스 미리 로드](https://docs.decentraland.org/creator/content-creator-ko/sdk7/optimizing/pre-load-resources.md) 문서를 확인하세요.

### 3D 모델 무료 라이브러리

직접 3D 모델을 만드는 대신, 여러 무료 또는 유료 라이브러리에서 모델을 다운로드할 수도 있습니다.

시작하는 데 도움이 되도록, 무료 또는 비교적 저렴한 콘텐츠를 제공하는 라이브러리를 아래에 소개합니다.

* [IWB 카탈로그](https://dcl-iwb.co/)
* [Asset Ovi](https://assetovi.com/)
* [Builder의 에셋](https://github.com/decentraland/builder-assets/tree/master/assets)
* [SketchFab](https://sketchfab.com/)
* [Clara.io](https://clara.io/)
* [Archive3D](https://archive3d.net/)
* [SketchUp 3D Warehouse](https://3dwarehouse.sketchup.com/)
* [Thingiverse](https://www.thingiverse.com/) (주로 3D 프린팅용으로 제작된 3D 모델이지만 가상 세계에 맞게 활용할 수 있음)
* [ShareCG](https://www.sharecg.com/)
* [CGTrader](https://www.cgtrader.com/)

{% hint style="warning" %}
**📔 참고**: 다운로드한 콘텐츠에 적용되는 라이선스 제한 사항에 유의하세요.
{% endhint %}

이러한 사이트 중 일부에서는 모델을 다운로드할 형식을 선택할 수 있습니다. 사용할 수 있다면 항상 *.glTF* 형식을 선택하세요. 이 형식을 사용할 수 없다면 씬에서 사용하기 전에 *glTF* 로 변환해야 합니다. 변환하려면 Blender로 가져온 다음 *.glTF* 형식으로 내보내는 것을 권장합니다.

### 3D 모델 최적화

씬의 3D 모델을 더 빠르게 로드하고 메모리를 덜 사용하도록 하려면 다음 모범 사례를 따르세요:

* 모델은 다음 형식으로 저장하세요:  *.glb* 보다 용량이 작은 형식인  *.gltf*.
* 같은 텍스처를 공유하는 모델이 여러 개라면, 텍스처를 별도 파일로 내보내세요. 그러면 여러 모델이 하나의 텍스처 파일을 참조할 수 있고, 해당 파일은 한 번만 불러오면 됩니다.
* 장면에 나타났다 사라지는 엔티티가 있다면, 엔티티를 풀링해 지하에 두거나 크기를 0으로 설정하는 것이 좋습니다. 이렇게 하면 엔티티가 더 빠르게 나타납니다. 대신 사용하지 않을 때도 메모리를 차지합니다.

## 도형 늘이기

기본 도형과 3D 모델에는 기본 크기가 있으며, 엔티티의  `Transform` 컴포넌트에서 크기를 변경할 수 있습니다.

```ts
const primitiveEntity = engine.addEntity()

MeshRenderer.setBox(primitiveEntity)

Transform.create(primitiveEntity, {
	position: { x: 8, y: 1, z: 8 },
	scale: { x: 4, y: 0.5, z: 4 },
})
```

## 보이지 않게 하기

엔티티에  `VisibilityComponent`를 추가하고  `visible` 속성을  *false*.

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(myEntity)

VisibilityComponent.create(myEntity, { visible: false })
```

기본 `VisibilityComponent` 은 기본 도형과  `GLTFContainer` 컴포넌트가 있는 엔티티에서 동일하게 작동합니다.

엔티티가 보이지 않더라도, 콜라이더에 할당된 충돌 레이어에 따라 콜라이더가 플레이어의 이동을 막거나 그 뒤에 있는 엔티티를 클릭할 수 없게 만들 수 있습니다.

### 하위 엔티티에 가시성 전파

엔티티의 하위 트리에 있는 모든 하위 엔티티에 설정을 적용하려면  `propagateToChildren` 필드를  `VisibilityComponent` 에서 사용할 수 있습니다. 이 필드를  `propagateToChildren` 로 설정하면 *true*아래 모든 단계의 하위 엔티티에 설정이 적용됩니다. 이렇게 하면 각 하위 엔티티를 일일이 보이지 않게 하거나 보이게 설정하는 번거로운 작업을 줄일 수 있습니다.

```ts
// 상위 엔티티 (명시적으로 보이지 않게 설정)
const parentEntity = engine.addEntity()
Transform.create(parentEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(parentEntity)
VisibilityComponent.create(parentEntity, { visible: false, propagateToChildren: true })

// 하위 엔티티 (상위 엔티티의 설정으로 인해 암묵적으로 보이지 않음)
const child = engine.addEntity()
Transform.create(child, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity
})
MeshRenderer.setBox(child)
```

{% hint style="warning" %}
**📔 참고**: 엔티티에 자체  `VisibilityComponent`가 있으면 상위 엔티티의 설정을 덮어씁니다.

엔티티에 자체 `VisibilityComponent`가 있다면 해당 엔터티의 가시성은 다음을 가진 가장 가까운 부모에 의해 결정됩니다: `VisibilityComponent` 및 `propagateToChildren` 이 다음 값으로 설정됨: *true*.
{% endhint %}

## 로딩 상태

3D 모델이 상당히 크면 렌더링하는 데 눈에 띄게 시간이 걸릴 수 있습니다. 이 시간은 플레이어의 하드웨어와 그 밖의 여러 요인에 따라 달라질 수 있습니다. 다른 작업을 수행하기 전에 모델 로딩이 완료되었는지 확인해야 할 때가 있습니다. 예를 들어 플레이어를 하늘에 있는 플랫폼으로 텔레포트하려면 먼저 플랫폼이 완전히 렌더링되었는지 확인해야 합니다. 그렇지 않으면 플레이어가 플랫폼을 그대로 통과해 떨어질 수 있습니다.

3D 모델의 렌더링이 완료되었는지 확인하려면 엔터티의 `GltfContainerLoadingState` 컴포넌트를 확인하세요. 이 컴포넌트는 읽기 전용이며 `GltfContainer`컴포넌트가 있는 모든 엔터티에 존재합니다.

이 컴포넌트에는 `currentState`라는 속성이 하나 있으며, 이 속성은 `LoadingState` 열거형의 값을 저장합니다.

다음 예제에서는 시스템을 사용해 엔터티의 3D 모델 로딩 상태를 주기적으로 확인합니다. 상태가 `LoadingState.FINISHED`이면 해당 위치에서 사용자 지정 로직을 수행하고 시스템 실행을 종료할 수 있습니다.

```ts
export function main() {
	const meshEntity = engine.addEntity()
	GltfContainer.create(meshEntity, { src: 'models/Monster.glb' })
	engine.addSystem((deltaTime) => {
		const loadingState = GltfContainerLoadingState.getOrNull(meshEntity)
		if (!loadingState) return
		switch (loadingState.currentState) {
			case LoadingState.LOADING:
				console.log('mesh is LOADING')
				break
			case LoadingState.FINISHED:
				console.log('mesh is FINISHED')
				// 사용자 지정 로직 수행
				break
			case LoadingState.FINISHED_WITH_ERROR:
				console.log('mesh is FINISHED BUT MAY HAVE PROBLEMS')
				break
			case LoadingState.UNKNOWN:
				console.log('mesh is in an UNKNOWN STATE')
				break
		}
	})
}
```

## 고급 구문

구문을 간소화하는 헬퍼 없이 `MeshRenderer` 컴포넌트를 생성하는 전체 구문은 다음과 같습니다:

```ts
MeshRenderer.create(myBox, {
	mesh: {
		$case: 'box',
		box: { uvs: [] },
	},
})

MeshRenderer.create(myPlane, {
	mesh: {
		$case: 'plane',
		plane: { uvs: [] },
	},
})

MeshRenderer.create(myShpere, {
	mesh: {
		$case: 'sphere',
		sphere: {},
	},
})

MeshRenderer.create(myCylinder, {
	mesh: {
		$case: 'cylinder',
		cylinder: {},
	},
})
```

기본 프로토콜은 MeshRenderer 컴포넌트를 이와 같이 해석합니다. 헬퍼 함수는 이를 추상화해 사용하기 쉬운 구문을 제공하지만, 내부적으로는 이 구문을 출력합니다.

해당 `$case` 필드를 사용하면 허용된 유형 중 하나를 지정할 수 있습니다. 각 유형은 서로 다른 매개변수 집합을 지원합니다. 위 예시에서 `box` 유형은 `uvs` 필드를 지원합니다.

지원되는 `$case` 값은 다음과 같습니다.

* `box`
* `plane`
* `sphere`
* `cylinder`

$case `$case`값에 따라 해당 도형의 객체를 정의하고 관련 속성을 전달할 수 있습니다.

이미 이 컴포넌트의 인스턴스가 있을 수도 있는 엔터티에 `MeshRenderer` 컴포넌트를 추가하려면 `MeshRenderer.createOrReplace()`을 사용하세요. 다음과 같은 헬퍼 함수는 `MeshRenderer.setBox()` 기존 컴포넌트 인스턴스를 덮어쓰도록 처리하지만, 이미 이 컴포넌트를 가진 엔터티에서 `MeshRenderer.create()` 를 실행하면 오류가 반환됩니다.


---

# 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/shape-components.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.
