> 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). # 기본 컴포넌트 World Explorer는 씬과 정의를 공유하는 기본 컴포넌트 목록을 지원하며, 위치 지정, 애니메이션, 미디어, 월드 상태 쿼리에 대한 내장 지원을 제공합니다 컴포넌트에는 다섯 가지 유형이 있습니다: 1. [오브젝트 컴포넌트](#object) 엔티티에 시각적 및 물리적 속성을 추가합니다. 2. [게임 컴포넌트](#game) 게임 엔진에 동작을 요청하고 정보를 받을 수 있습니다. 3. [미디어 컴포넌트](#media) 이미지를 표시하고 사운드를 재생할 수 있습니다. 4. [영역 컴포넌트](#area) 특정 영역에서 엔티티의 동작을 변경합니다. 5. [UI 컴포넌트](#ui) 씬에서 떠다니는 인터페이스를 렌더링할 수 있습니다. 다음을 제외하고 [`Transform`](#Transform)자세히 아래에 설명된 바와 같이, 모든 컴포넌트의 상태는 프로토콜 버퍼를 사용해 직렬화됩니다. 각 제목의 링크를 따라가면 전체 정의를 볼 수 있습니다. ### 오브젝트 컴포넌트 가장 일반적인 컴포넌트는 엔티티에 시각적 및 물리적 속성을 연결하는 컴포넌트입니다. 이를 사용해 게임 내 오브젝트의 위치를 지정하고, 크기를 조정하고, 색을 칠하고, 충돌을 추가할 수 있습니다. *** **`Transform`** [**↗ 사양**](https://adr.decentraland.org/adr/ADR-153) 엔티티에 위치, 회전 및 스케일을 추가합니다. 이 컴포넌트는 압도적으로 가장 많이 사용되며, 씬의 수명 주기 동안 가장 자주 업데이트됩니다. 이 때문에, `Transform` 는 프로토콜 버퍼를 사용해 직렬화되지 않으며, 대신 사용자 지정 구조체에 패킹됩니다. `Transform` 크기는 `44` 바이트이며, 정확한 레이아웃은 다음과 같습니다: ``` .-----------------------.-------------------------------.-----------------------.-----------------. | x | y | z | x | y | z | w | x | y | z | parent (uint32) | '-----------------------'-------------------------------'-----------------------'-----------------' ╵ 위치 (3x float) ╵ 회전 (4x float) ╵ 스케일 (3x float) ╵ ``` 이 접근 방식은 런타임(특히 저수준 코드 환경)에서 중간 직렬화 및 역직렬화 단계를 피할 수 있게 합니다. 어떤 객체가 위치한 메모리는 `Transform` 복사, 공유, 직접 참조할 수 있습니다. 좌표는 소수일 수 있으므로 4바이트 부동소수점 숫자를 사용합니다. 이 `parent` 필드는 이 엔티티가 ID로 식별되는 다른 엔티티를 기준으로 배치되어야 함을 나타냅니다. null 값이 `parent` 또한 [`RootEntity`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#RootEntity) ID (`0`), 어떤 `Transform` 은 기본적으로 그것을 기준으로 합니다. 프로토콜에 따라, `Transform` 는 빅 엔디안 바이트 순서로 직렬화되어야 합니다. *** **`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). *** **`빌보드`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17) 엔티티가 자동으로 자신의 `Transform` 를 카메라를 향하게 하거나, 선택적으로 다음으로 참조되는 다른 엔티티를 향하게 합니다 `target_entity`. 이름에서 알 수 있듯이, 게임 내 빌보드를 표시하는 데 사용되며, 종종 [`TextShape`](#TextShape). 기본적으로 모든 방향에 영향을 주지만, 하나의 축에서만 회전하도록 설정할 수도 있습니다. 참조된 대상 엔티티가 존재하지 않으면, 존재할 때까지 재지향은 일시 중단됩니다. *** **`애니메이터`** [**↗ 소스**](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) 엔티티의 위치가 아바타 몸의 특정 앵커 포인트를 따라가야 함을 나타냅니다. user ID를 설정하면 플레이어뿐 아니라 어떤 아바타에도 영향을 줄 수 있습니다. *** **`TextShape`** [**↗ 소스**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/text_shape.proto#L11) 다음에 의해 제공되는 엔티티 위치에 텍스트를 렌더링합니다: `Transform`. 크기, 여백, 패딩, 색상, 그림자 등의 매개변수를 지원해 매우 유연하게 설정할 수 있습니다. *** **`가시성`** [**↗ 소스**](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) 마우스 포인터가 카메라의 초점에 자동으로 따라가고 있는지(잠김), 아니면 화면에서 자유롭게 움직일 수 있는지(잠금 해제)를 확인하는 데 사용할 수 있습니다. 다음에 연결되어 있습니다 [`CameraEntity`](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) 키와 포인터 동작을 포함한 플레이어의 최근 입력에 대한 정보를 담고 있습니다. 다음에 연결되어 있습니다 `RootEntity`, 그리고 런타임이 매 프레임마다 새 이벤트로 업데이트합니다. *** **`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) 컴포넌트에 연결되어 있으며, 다음 속성을 통해 서로 관련됩니다 `parent` 속성. 예를 들어, 떠 있는 옵션 창은 다음을 가진 엔티티일 수 있습니다: [`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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.