> 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/scene-editor/build/components.md).

# 엔티티와 컴포넌트

아이템의 컴포넌트가 어떻게 작동하는지 이해합니다

캔버스 또는 엔티티 트리에서 클릭하여 항목을 선택하세요. 그러면 화면 오른쪽의 속성 패널에 해당 항목의 컴포넌트가 표시됩니다. 항목마다 서로 다른 컴포넌트가 있으며, 각 컴포넌트는 특정 설정을 보여줍니다.

![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c9c570da87ad3e8ba629f2a0c0b64ea2587a34ac%2Fcomponents-in-editor.png?alt=media\&token=916b4ef9-6a25-4cc9-beaa-553b6ebed067)

대부분의 비상호작용 항목에는 다음 컴포넌트가 있습니다:

* **Transform**: 항목의 위치, 회전 및 크기를 설정합니다. 항목이 다른 항목의 자식인 경우 [엔티티 트리](/creator/content-creator-ko/scene-editor/get-started/scene-editor-essentials.md#the-entity-tree) 이 값은 부모의 값에 상대적입니다.
* **GLTF**: 어떤 3D 모델을 불러올지 지정합니다. 여기에는 이 3D 모델 파일의 로컬 경로가 포함됩니다. 또한 다음을 구성하기 위한 몇 가지 속성도 포함됩니다 [충돌체](/creator/content-creator-ko/sdk7/3d/colliders.md#colliders-on-3d-models)  모델에서.

씬의 항목들은 모두 **엔터티**엔티티입니다. 씬의 모든 것은 엔티티이며, 이는 씬의 기본 구성 요소입니다. 항목은 최소한 위치와 보이는 모양을 가진 엔티티입니다.

## 컴포넌트 추가

어떤 엔티티에든 컴포넌트를 추가하려면 속성 탭 상단의 **+** 기호를 클릭하고 목록에서 컴포넌트를 선택하세요. 참조 [모든 항목을 스마트 아이템으로 만들기](/creator/content-creator-ko/scene-editor/interactivity/make-any-item-smart.md)

![엔티티에서 열리는 컴포넌트 추가 메뉴에는 3D Content와 Interaction 아래에 분류된 컴포넌트가 나열됩니다.](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6a35142910f0343c27340673c61d75ed5f75f05a%2Fadd-component.png?alt=media\&token=a3fb4e60-b24d-4e2a-b9b8-45d7db23aee0)

엔티티에서 오른쪽의 점 세 개 아이콘을 클릭한 뒤 **컴포넌트 삭제**.

## 처음부터 엔티티 만들기

새로운 엔티티를 만들려면 루트 **씬** 엔티티 트리의 엔티티 또는 다른 엔티티를 마우스 오른쪽 버튼으로 클릭한 다음 **자식 추가**

![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-46376236db2643c1394a6498cbbbec8519b7fe72%2Fnew-entity.png?alt=media\&token=ad2ff878-123d-4a00-a5bf-1ebf5b718d00)

그러면 하나의 **Transform** 컴포넌트만 가진 빈 엔티티가 생성됩니다. 새 엔티티는 클릭한 부모 엔티티의 자식입니다. 그런 다음 원하는 다른 컴포넌트를 추가해 원하는 형태로 만들 수 있습니다.

## 사용 가능한 컴포넌트

다음 컴포넌트는 씬 편집기 UI를 통해 어떤 엔티티에든 추가할 수 있습니다:

* **메시 렌더러**: 기본 도형(큐브, 평면, 원통 또는 구)을 기반으로 엔티티에 보이는 모양을 부여합니다.
* **MeshCollider**: 엔티티에 보이지 않는 충돌체 지오메트리를 부여합니다. 이를 통해 플레이어가 항목을 통과하지 못하게 하거나, 클릭 가능하게 만들 수 있습니다. 참조 [collider](/creator/content-creator-ko/sdk7/3d/colliders.md).
* **재질**: 색상, 텍스처 및 기타 속성을 정의합니다. 엔티티에 **메시 렌더러**  컴포넌트가 있는 [재질](/creator/content-creator-ko/sdk7/3d/materials.md).

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>**📔 참고**: 해당 항목에는 **Mesh Renderer** 컴포넌트가 있어야 합니다. **GLTF** 보이는 모양을 가진 항목에는 영향을 주지 않습니다.</p></div>
* **가시성**: 엔티티가 보이지 않도록 정의합니다.
* **광원**: 엔티티에 조명을 추가합니다.
* **재질 교체**: 엔티티의 재질을 교체합니다. 엔티티에 **GLTF**  컴포넌트가 있는 경우, 3D 모델에 여러 메쉬가 있어도 각 메쉬의 재질을 개별적으로 교체할 수 있습니다.
* **오디오 소스**: 엔티티 위치에서 사운드 파일의 소리를 재생합니다. 참조 [사운드](/creator/content-creator-ko/sdk7/3d/sounds.md).
* **Text Shape**: 3D 공간에 텍스트를 표시합니다. 참조 [텍스트](/creator/content-creator-ko/sdk7/3d/text.md).
* **포인터 이벤트**: 엔티티를 클릭 가능한 것으로 표시하고, 호버 힌트를 표시합니다.

{% hint style="warning" %}
**📔 참고**: **포인터 이벤트** 컴포넌트는 피드백만 제공합니다. 엔티티와 상호작용할 때 동작을 수행하려면 [모든 항목을 스마트 아이템으로 만들기](/creator/content-creator-ko/scene-editor/interactivity/make-any-item-smart.md)
{% endhint %}

* **멀티플레이어**: 엔티티에 발생한 변경 사항을 공유하여 씬의 모든 플레이어가 이를 볼 수 있게 합니다. 특정 컴포넌트의 변경 사항만 공유하도록 설정할 수도 있습니다. 참조 [서버리스 멀티플레이어](/creator/content-creator-ko/sdk7/networking/serverless-multiplayer.md#mark-an-entity-as-synced) 자세한 내용은.
* **애니메이터**: 엔티티에 있는 애니메이션의 재생을 제어합니다. **GLTF** 3D 모델에 대해 참조 [3D 모델 애니메이션](/creator/content-creator-ko/sdk7/3d/3d-model-animations.md).
* **트윈**: 엔티티가 일정 시간에 걸쳐 서서히 이동, 회전 또는 크기 조정을 하게 합니다. 참조 [엔티티 이동](/creator/content-creator-ko/sdk7/3d/move-entities.md).
* **빌보드**: 엔티티가 항상 플레이어를 향하도록 회전하게 합니다. 참조 [사용자 바라보기](/creator/content-creator-ko/sdk7/3d/entity-positioning.md#face-the-user).
* **아바타 연결**: 엔티티를 플레이어의 아바타에 연결하여 따라다니게 합니다. 참조 [엔티티를 아바타에 연결하기](/creator/content-creator-ko/sdk7/3d/entity-positioning.md#attach-an-entity-to-an-avatar).
* **비디오 플레이어**: 씬 안에서 비디오를 재생하며, 엔티티의 **재질**. 참고: [비디오 재생](/creator/content-creator-ko/sdk7/media/video-playing.md).
* **NFT 형태**: 프레임 안에 NFT 이미지를 표시합니다. 참조 [NFT 표시하기](/creator/content-creator-ko/scene-editor/build/nfts.md).
* **파티클 시스템**: 엔티티의 위치에서 연기, 불꽃 또는 반짝임 같은 효과를 위한 파티클을 방출합니다. 참조 [파티클 시스템](/creator/content-creator-ko/sdk7/3d/particle-system.md).
* **가상 카메라**: 씬이 플레이어의 시점을 전환할 수 있는 사용자 지정 카메라 각도를 정의합니다. 참조 [카메라](/creator/content-creator-ko/sdk7/3d/camera.md).
* **아바타 수정 영역**: 이 엔티티를 중심으로 한 영역 안에 있는 플레이어에 대해 아바타의 동작이나 외형을 변경합니다. 엔티티의 크기가 영역의 크기를 설정합니다. 참조 [수정 영역](/creator/content-creator-ko/scene-editor/interactivity/modifier-areas.md).
* **카메라 수정 영역**: 이 엔티티를 중심으로 한 영역 안에서 플레이어의 카메라를 1인칭 또는 3인칭으로 강제합니다. 엔티티의 크기가 영역의 크기를 설정합니다. 참조 [수정 영역](/creator/content-creator-ko/scene-editor/interactivity/modifier-areas.md).
* **스크립트**: UI에서 설정할 수 있는 매개변수를 가진 사용자 지정 코드 모듈을 엔티티에 연결합니다. 참조 [스크립트 컴포넌트](/creator/content-creator-ko/scene-editor/extend-with-code/script-component.md).

{% hint style="warning" %}
**📔 참고**: SDK에는 현재 코드로만 사용할 수 있는 다른 컴포넌트들도 있습니다. 또한 자체 [사용자 정의 컴포넌트](/creator/content-creator-ko/sdk7/architecture/custom-components.md) 를 코드로 만들 수도 있습니다. 이들은 UI 표현이 없지만 코드로 추가하고 편집할 수 있습니다.

다음 [코드와 결합](/creator/content-creator-ko/scene-editor/extend-with-code/overview.md) 씬의 코드를 편집하는 방법은

또한 엔티티는 각 컴포넌트를 **하나만** 가질 수 있다는 점도 참고하세요. 엔티티에 이미 존재하는 컴포넌트의 두 번째 인스턴스를 할당할 수는 없습니다. 예를 들어, 두 개의 **동작** 컴포넌트를 같은 엔티티에 추가할 수는 없습니다.
{% endhint %}

## 알아두면 좋은 설정

대부분의 컴포넌트 필드는 위에 링크된 SDK 페이지와 1:1로 대응합니다. 몇 가지는 놓치기 쉽거나, 필드 이름만으로는 분명하지 않은 방식으로 동작합니다.

### 오디오 소스

**피치** 는 재생 속도를 곱하고 그에 따라 피치를 이동시킵니다. `1` 원래 소리를 재생합니다, `2` 두 배 빠르게 재생합니다(한 옥타브 위), `0.5` 절반 속도로 재생합니다(한 옥타브 아래). 0보다 커야 하며 기본값은 `1`.

### 비디오 플레이어

* **재생 속도**: 피치와 같은 개념이지만 비디오용입니다. `1` 정상 속도입니다. 기본값은 비워 두세요.
* **시작 위치(초)**: 비디오가 시작될 때 재생이 시작되는 지점입니다. 처음부터 시작하려면 비워 두세요.
* **공간 오디오**: **공간** 을 켜면 비디오의 소리가 위치 기반이 되어, 플레이어가 멀어질수록 줄어듭니다. **공간 거리** 는 범위를 설정합니다. 오디오는 **최소** 미터까지는 최대 볼륨으로 재생되고 **최대** 미터에서 무음으로 줄어듭니다. 기본값은 0과 60입니다.

를 사용하면 **공간** 오디오는 씬의 모든 곳에서 같은 볼륨으로 재생됩니다.

### Text Shape

* **크기**: 텍스트 상자의 너비(**W**)와 높이(**H**)를 미터 단위로 나타냅니다. 정렬과 여백은 이 상자를 기준으로 측정됩니다.
* **텍스트 줄 바꿈**: **크기**에서 설정한 너비에 도달하면 텍스트를 새 줄로 나눕니다. 끄면 텍스트가 한 줄로 유지됩니다.

### 재질

* **색상 알파**: 주요 **색상**의 불투명도이며, 0에서 1까지입니다. **투명도 모드** 가 **불투명**.
* **알파 테스트**: 픽셀이 보이지 않게 되는 기준점입니다. **투명도 모드** 가 **알파 테스트** 또는 **알파 테스트 및 블렌드**일 때만 표시되며, 이는 이를 사용하는 유일한 모드이기 때문입니다.
* **없음**: 색상 드롭다운에는 이제 색상을 지우는 **없음** 항목과 텍스처 **유형** 드롭다운에는 **없음** 텍스처를 제거하는 옵션이 있습니다.

### 파티클 시스템

이 **회전** 섹션은 파티클의 방향과 회전 방식을 제어합니다:

* **빌보드**: 각 파티클은 항상 카메라를 향합니다. 기본값으로 켜져 있습니다. 3D에서 자유롭게 뒤집혀야 하는 파티클은 끄세요.
* **이동 방향 바라보기**: 각 파티클은 화살표처럼 이동하는 방향을 바라보며 시작합니다.
* **초기 회전(도)**: 각 파티클이 생성될 때 축별로 어떻게 회전하는지 나타냅니다.
* **시간에 따른 회전(도/초)**: 축별로 얼마나 빠르게 회전하는지 나타냅니다. 값은 축별로 180으로 제한됩니다.

When **텍스처 사용** 이 켜져 있으면 드롭다운이 두 개 더 나타납니다:

* **랩 모드**: 텍스처가 가장자리를 넘어갈 때 어떻게 동작하는지 나타냅니다. **클램프** (기본값)는 가장자리 픽셀을 늘리고, **반복** 은 타일처럼 반복하며, **미러** 는 번갈아 뒤집히며 타일처럼 반복합니다.
* **필터 모드**: 텍스처를 어떻게 샘플링하는지 나타냅니다. **바이리니어** (기본값)는 부드럽고, **포인트** 는 픽셀화되어 픽셀 아트에 적합하며, **트라이리니어** 는 밉맵 수준 전반에 걸쳐 부드럽게 만듭니다.

### 트윈

**트윈 유형** 은 다섯 가지 모드를 제공합니다:

| 모드                                 | 기능                                           |
| ---------------------------------- | -------------------------------------------- |
| **항목 이동**, **항목 회전**, **항목 크기 조정** | 주어진 시간 동안 시작 값에서 종료 값까지 애니메이션합니다. **지속 시간**. |
| **연속 이동**                          | 고정된 방향으로, 영원히, 일정한 속도로 계속 이동합니다.             |
| **연속 회전**                          | 고정된 축을 중심으로, 영원히, 일정한 속도로 계속 회전합니다.          |

두 개의 연속 모드에는 종료 값이 없으므로 **시작**, **종료**, **지속 시간**, **이징 함수** 과 **반복** 가 숨겨집니다. 대신 다음이 제공됩니다:

* **연속 이동**: 하나의 **방향**  벡터와 하나의 **속도(미터/초)**. 길이가 1인 방향을 사용해야 속도가 정확히 초당 미터 단위가 됩니다. 음수 속도는 반대 방향으로 이동합니다.
* **연속 회전**: 하나의 **회전 축(도)** 와 하나의 **속도(도/초)**. 축의 방향만 중요하며, 각도의 크기는 중요하지 않습니다.

전환 **트윈 유형** 새 모드에 맞는 적절한 기본값으로 이러한 값을 재설정합니다. 각 모드에서 숫자가 의미하는 바가 다르기 때문입니다.

이 **재생 중** 체크박스(이전에는 "Auto start"라고 불림)는 씬이 로드되자마자 트윈이 실행될지 여부를 결정합니다. 끄면 트윈은 시작 값에서 일시 정지된 상태로 생성되며, 코드가 재생하도록 설정할 때만 실행됩니다.

{% hint style="info" %}
**💡 팁**컴포넌트 속성 중 일부는 코드에서만 설정할 수 있습니다. 이제 인스펙터에서 엔티티를 편집해도 이러한 값이 더 이상 삭제되지 않으므로, 씬 코드에서 값을 설정한 뒤에도 잃지 않고 해당 엔티티를 계속 편집할 수 있습니다.
{% endhint %}

## 스마트 아이템

[스마트 아이템](/creator/content-creator-ko/scene-editor/interactivity/smart-items.md) 에는 엔티티의 상호작용성을 제어하는 특수 컴포넌트도 포함될 수 있습니다. 보통 다음과 같습니다:

* **동작**: 아이템이 수행할 수 있는 모든 가능한 동작을 나열합니다.
* **트리거**: Actions 컴포넌트의 동작이 수행되는 시점을 결정합니다.
* **States**: 아이템의 현재 상태를 추적합니다. 이 상태는 조건부 로직에 사용되어, 아이템이 특정 상태일 때만 특정 동작을 트리거할 수 있습니다.
* **Counter**: 카운터를 추적합니다. 카운터는 조건부 로직에 사용되어, 카운터 값이 주어진 값과 같거나 크거나 작을 때만 특정 동작을 트리거할 수 있습니다.

다음 [스마트 아이템 고급](/creator/content-creator-ko/scene-editor/interactivity/smart-items-advanced.md) 자세한 내용은.

## 엔티티와 컴포넌트에 대하여

씬의 모든 것은 엔티티입니다. 씬의 모든 항목과 스마트 아이템은 엔티티입니다.

엔티티의 모든 특성은 컴포넌트에 의해 결정됩니다. 컴포넌트는 엔티티가 무엇인지, 어디에 있는지, 어떻게 들리는지, 그리고 어떻게 동작하는지를 정의합니다. 예를 들어, 하나의 **Transform** 컴포넌트는 엔티티의 좌표, 회전 및 크기를 저장합니다. 하나의 **MeshRenderer** 컴포넌트는 엔티티에 보이는 모양(큐브나 구 같은 것)을 부여하고, 하나의 **재질** 컴포넌트는 엔티티에 색상이나 텍스처를 부여합니다.

컴포넌트의 값은 시간이 지나면서 바뀔 수 있습니다. 씬 편집기에서는 이러한 컴포넌트의 초기 값을 설정합니다. 하지만 씬이 실행되면 플레이어의 행동이나 시간의 경과로 인해 그 값이 바뀔 수 있습니다.

예를 들어, 움직이는 플랫폼 스마트 아이템은 **Transform** 컴포넌트를 통해 설정한 초기 위치를 가지고 있지만, 이 아이템의 동작으로 움직이게 된 뒤에는, **Transform** 서로 다른 값을 가지게 됩니다.

다음 [엔티티와 컴포넌트](/creator/content-creator-ko/sdk7/architecture/entities-components.md) 이 개념과 Decentraland 씬에서 어떻게 사용되는지 자세히 알아보세요.


---

# 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/scene-editor/build/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.