> 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/contributor/contributor-ko/scene-runtime/basic-components.md). # 기본 컴포넌트 월드 익스플로러는 씬과 정의를 공유하는 기본 컴포넌트 목록을 지원하며, 위치 지정, 애니메이션, 미디어, 월드 상태 질의에 대한 기본 제공 지원을 제공합니다 컴포넌트에는 다섯 가지 유형이 있습니다: 1. [오브젝트 컴포넌트](#object) 엔티티에 시각적 및 물리적 속성을 추가합니다. 2. [게임 컴포넌트](#game) 액션을 요청하고 게임 엔진으로부터 정보를 받을 수 있습니다. 3. [미디어 컴포넌트](#media) 이미지를 표시하고 소리를 재생할 수 있습니다. 4. [영역 컴포넌트](#area) 특정 구역에서 엔티티의 동작을 변경합니다. 5. [UI 컴포넌트](#ui) 씬이 떠 있는 인터페이스를 렌더링할 수 있게 합니다. 다음을 제외하고 [`트랜스폼`](#Transform), 아래에 자세히 설명된 바와 같이, 모든 컴포넌트의 상태는 프로토콜 버퍼를 사용해 직렬화됩니다. 각 제목의 링크를 따라가면 전체 정의를 볼 수 있습니다. ### 오브젝트 컴포넌트 가장 흔한 컴포넌트는 엔티티에 시각적 및 물리적 속성을 부여하는 컴포넌트입니다. 이를 사용해 게임 내 오브젝트의 위치를 지정하고, 크기를 조정하고, 그리며, 충돌을 추가할 수 있습니다. *** **`트랜스폼`** [**↗ 명세**](https://adr.decentraland.org/adr/ADR-153) 엔티티에 위치, 회전, 크기를 추가합니다. 이 컴포넌트는 단연코 가장 많이 사용되며 씬의 수명 동안 가장 자주 업데이트됩니다. 따라서, `트랜스폼` 는 프로토콜 버퍼를 사용해 직렬화되지 않으며, 대신 사용자 정의 구조체로 패킹됩니다. `트랜스폼` 크기는 `44` 바이트이며, 정확한 레이아웃은 다음과 같습니다: ``` .-----------------------.-------------------------------.-----------------------.-----------------. | x | y | z | x | y | z | w | x | y | z | 상위 (uint32) | '-----------------------'-------------------------------'-----------------------'-----------------' ╵ 위치 (3x float) ╵ 회전 (4x float) ╵ 크기 (3x float) ╵ ``` 이 방식은 런타임(특히 저수준 코드 환경)에서 중간 직렬화 및 역직렬화 단계를 피할 수 있게 합니다. a가 `트랜스폼` 존재하는 메모리는 복사, 공유 및 직접 참조할 수 있습니다. 좌표는 소수일 수 있으므로 4바이트 부동소수점 숫자를 사용합니다. 그 `상위` 필드는 이 엔티티가 ID로 식별되는 다른 엔티티를 기준으로 배치되어야 함을 나타냅니다. parent의 null 값은 `상위` 또한 [`루트 엔티티`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#RootEntity) ID (`0`), 모든 `트랜스폼` 은 기본적으로 그에 대해 상대적입니다. 프로토콜상, `트랜스폼` 빅엔디언 바이트 순서로 직렬화되어야 합니다. *** **`MeshRenderer`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/mesh_renderer.proto#L7) 엔티티에 대한 기본 렌더링 동작을 제공합니다. 평면, 구, 큐브 또는 원기둥을 렌더링하도록 설정할 수 있습니다. 임의의 3D 형태를 렌더링하려면 [`GltfContainer`](#GltfContainer). *** **`MeshCollider`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/mesh_collider.proto#L15) 엔티티에 대한 기본 충돌 동작과 마우스 포인터 감지를 제공합니다. 평면, 구, 큐브 또는 원기둥처럼 동작하도록 설정할 수 있습니다. 사용자 지정 충돌 메시를 사용하려면 [`GltfContainer`](#GltfContainer). *** **`Material`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/material.proto#L19) 또한 다음을 가진 엔티티의 텍스처, 조명, 색상 및 투명도 속성을 설정합니다 [`MeshRenderer`](#MeshRenderer) 컴포넌트. 모든 일반적인 경우를 다루도록 설계된 복잡한 구조이지만, 모든 필드에는 적절한 기본값이 있어 지정하지 않아도 됩니다. 엔티티의 시각적 속성을 완전히 사용자 지정하려면 [`GltfContainer`](#GltfContainer). *** **`GltfContainer`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/gltf_container.proto#L7) 다음이 주어지면 이 엔티티에 3D 모델을 연결합니다 [파일 경로](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files) 를 `.gltf` 씬의 매니페스트에 있는 에셋. 모델은 자체 메시와 머티리얼을 가지므로, 이 컴포넌트는 다음의 동작을 모두 재정의합니다 [`MeshRenderer`](#MeshRenderer), [`MeshCollider`](#MeshCollider) 및 [`Material`](#Material). *** **`Billboard`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17) 엔티티가 자동으로 자신의 `트랜스폼` 를 카메라를 향하도록 재정렬하게 하거나, 선택적으로 다음을 통해 참조된 다른 엔티티를 향하도록 합니다 `target_entity`. 이름에서 알 수 있듯이 게임 내 배너/간판을 표시하는 데 사용되며, 종종 다음과 함께 사용됩니다 [`TextShape`](#TextShape). 기본적으로 모든 방향에 영향을 주지만, 한 축으로만 회전하도록 설정할 수 있습니다. 참조된 대상 엔티티가 존재하지 않으면, 존재할 때까지 재정렬이 일시 중단됩니다. *** **`Animator`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/animator.proto#L7) 엔티티에 동시에 적용할 수 있는 하나 이상의 애니메이션을 정의합니다. 씬은 컴포넌트 상태를 설정하여 애니메이션을 사용자 지정하고, 재생하고, 전환할 수 있으며, 이를 읽어 사용 가능한 애니메이션이나 현재 재생 중인 애니메이션을 확인할 수도 있습니다. *** **`AvatarAttach`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_attach.proto#L16) 엔티티의 위치가 아바타 몸체의 특정 앵커 포인트를 따라야 함을 나타냅니다. 사용자 ID를 설정하면 플레이어의 아바타뿐 아니라 어떤 아바타에도 적용할 수 있습니다. *** **`TextShape`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/text_shape.proto#L11) 다음에 의해 제공되는 엔티티의 위치에 텍스트를 렌더링합니다 `트랜스폼`. 크기, 여백, 패딩, 색상, 그림자 등과 같은 매개변수를 지원하며 매우 세부적으로 설정할 수 있습니다. *** **`가시성`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/visibility_component.proto#L7) 엔티티를 보이게(기본값) 할지 보이지 않게 할지 설정합니다. 보이지 않는 오브젝트도 여전히 존재하며, 연결된 다른 컴포넌트의 동작은 그대로 나타납니다. *** **`AvatarShape`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_shape.proto#L8) 플레이어의 아바타에 대한 정보를 포함하며, 신체 형태, 색상, 착용 아이템 및 일시적 상태를 포함합니다. 이 컴포넌트는 다음의 엔티티에 연결됩니다 [아바타 씬](https://github.com/decentraland/docs/tree/main/contributor/runtime/execution/README.md#avatarScene). ### 게임 컴포넌트 일부 기본 컴포넌트는 씬과 런타임이 정보를 교환하는 데 사용할 수 있습니다. 이들은 다음을 활용합니다 [ECS 동기화 메커니즘](https://github.com/decentraland/docs/tree/main/contributor/runtime/modules/engine_api/README.md#synchronization) 모든 상태 변경이나 이벤트의 일관성과 순서를 보장하기 위해 *** **`CameraMode`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode.proto#L8) 플레이어가 1인칭 또는 3인칭 시점을 사용하는지 확인하는 데 사용할 수 있습니다. *** **`PointerLock`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_lock.proto#L7) 마우스 포인터가 카메라의 초점 지점을 자동으로 따라가는지(잠김), 아니면 화면에서 자유롭게 움직일 수 있는지(잠금 해제) 확인하는 데 사용할 수 있습니다. 이는 다음에 연결됩니다 [`카메라 엔티티`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#CameraEntity), 그리고 그 상태는 씬에서 읽을 수 있지만(쓰기 불가) *** **`PointerEvents`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events.proto#L17) 포인터가 엔티티를 클릭하거나 위에 올렸을 때 시각적 피드백을 보여줍니다. *** **`PointerEventsResult`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events_result.proto#L13) 키와 포인터 동작을 포함해 플레이어의 최근 입력에 대한 정보를 담고 있습니다. 이는 다음에 연결됩니다 `루트 엔티티`, 그리고 매 프레임마다 런타임에 의해 새로운 이벤트로 업데이트됩니다. *** **`Raycast`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast.proto#L15) 엔티티에 연결하여 게임 엔진에 레이캐스트를 요청할 수 있습니다. `RaycastResult` 컴포넌트는 나중에 같은 엔티티에 연결됩니다. 레이의 시작점, 방향, 최대 길이를 설정할 수 있습니다. *** **`RaycastResult`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast_result.proto#L9) 런타임이 다음을 가진 엔티티에 연결합니다 [`Raycast`](#Raycast) 결과를 기다리는 컴포넌트. 원래 레이에 대한 정보를 포함하며, 충돌한 모든 엔티티를 식별합니다. ### 미디어 컴포넌트 씬은 이미지를 표시하거나 비디오를 보여주거나 소리를 재생하기 위해 특수 컴포넌트를 연결할 수 있습니다. *** **`AudioSource`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_source.proto#L7) 다음이 주어지면 씬에 번들로 포함된 오디오 클립을 재생합니다 [매니페스트에 있는 파일의 경로](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files). 소리는 연결된 엔티티의 위치에서 발생합니다. 피치, 볼륨, 반복 동작을 설정할 수 있으며 오디오 플레이어의 상태를 읽을 수 있습니다. {% hint style="info" %} 향후 업그레이드를 대비해, 다음의 필드는 `AudioSource` 다음과 같이 불립니다 `audio_clip_url`, 그러나 현재 프로토콜 버전에서는 실제로 매니페스트에 정의된 경로입니다. {% endhint %} *** **`AudioStream`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_stream.proto#L7) 다음과 유사하지만 [AudioSource](#AudioSource), 오디오는 외부 URL에서 실시간으로 스트리밍됩니다. 특정 엔티티에 연결되어 있음에도 소리는 그 위치의 영향을 받지 않습니다. 볼륨을 설정할 수 있고, 오디오 플레이어의 상태를 읽을 수 있습니다. *** **`NftShape`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/nft_shape.proto#L36) 이미지 또는 비디오 에셋과 연결된 NFT를 표시합니다. 구성 가능한 장식 프레임이 있는 2D 캔버스를 렌더링합니다. ### 영역 컴포넌트 이 컴포넌트는 씬이 지정된 범위 내의 엔티티 기본 동작을 수정할 수 있게 합니다. *** **`AvatarModifierArea`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_modifier_area.proto#L15) 엔티티를 중심으로 하는 공간 내 아바타의 동작을 변경합니다. 3D 크기 벡터로 정의되며, 아바타의 표시 여부나 클릭 가능 여부에 영향을 줄 수 있습니다. 특정 아바타는 해당 사용자의 ID를 기준으로 이 효과에서 제외할 수 있습니다. *** **`CameraModeArea`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode_area.proto#L11) 엔티티를 중심으로 하는 공간 내에서 카메라 모드(1인칭 또는 3인칭)를 변경합니다. 3D 크기 벡터와 원하는 카메라 모드로 정의됩니다. ### UI 컴포넌트 다음 컴포넌트는 게임 월드 위에 떠 있는 그래픽 인터페이스를 만드는 데 사용됩니다. 이들은 보통 계층적 구조를 가진 엔티티 집합에 연결됩니다 [`UiTransform`](#UiTransform) 컴포넌트는 다음을 통해 서로 연결됩니다 `상위` 속성. 예를 들어, 떠 있는 옵션 창은 다음을 가진 엔티티일 수 있습니다 [`UiTransform`](#UiTransform) 그리고 다음을 가진 [`UiBackground`](#UiBackground) 컴포넌트, 그리고 자식이 있는 엔티티 [`UiTransform`](#UiTransform) 그리고 다음을 가진 [`UiDropdown`](#UiDropdown). *** **`UiTransform`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_transform.proto#L77) UI 컴포넌트의 크기, 배치, 여백 및 패딩을 설명합니다. Flexbox 모델을 기반으로 하며 매우 세부적으로 설정할 수 있습니다. *** **`UiBackground`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_background.proto#L11) UI 엔티티의 배경으로 사용할 색상 또는 텍스처를 설명합니다. *** **`UiDropdown`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown.proto#L11) 드롭다운 위젯에 표시될 상호 배타적인 옵션 목록을 정의합니다. *** **`UiDropdownResult`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown_result.proto#L9) 다음에서 선택된 값을 포함합니다 [`UiDropdown`](#UiDropdown), 런타임이 설정하고 씬이 읽습니다. *** **`UiInput`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input.proto#L11) 약간의 사용자 지정을 위한 여백이 있는 텍스트 입력 위젯을 정의합니다. *** **`UiInputResult`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input_result.proto#L9) 다음의 텍스트 값을 포함합니다 [`UiInput`](#UiInput), 런타임이 설정하고 씬이 읽습니다. *** **`UiText`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_text.proto#L11) 약간의 사용자 지정을 위한 여백이 있는 간단한 텍스트 뷰를 정의합니다. *** --- # 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/contributor/contributor-ko/scene-runtime/basic-components.md?ask=&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.