> 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 형태와 충돌을 부여하는 다양한 컴포넌트에 대해 알아보세요. 디센트럴랜드의 3차원 씬은 다음을 기반으로 합니다. [엔티티-컴포넌트](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) 모델을 기반으로 하며, 씬의 모든 것은 하나의 *entity*이고, 각 엔티티에는 *컴포넌트* 이 포함될 수 있으며, 이들이 그 특성과 기능을 형성합니다. 엔티티의 렌더링된 형태는 어떤 컴포넌트를 사용하는지에 따라 결정됩니다. ![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-417a02dcf0fd40f5032551a0c6996becac7e7166%2Fecs-simple-components-new.png?alt=media) ## Creator Hub의 Scene Editor를 사용하세요 엔티티에 형태를 부여하는 가장 쉬운 방법은 씬 에디터를 사용하는 것입니다. 다음을 추가할 수 있습니다. **메시 렌더러** 컴포넌트로 기본 도형을 제공하거나, **GLTF** 컴포넌트로 파일의 3D 모델을 참조할 수 있습니다. 다음을 참조하세요. [컴포넌트 추가](/creator/content-creator-ko/scene-editor/build/components.md#add-components). ## 기본 도형 종종 *프리미티브라고 불리는 여러 기본 도형은 엔티티에*를 부여하여 엔티티에 추가할 수 있습니다. `MeshRenderer` 컴포넌트를 부여해야 합니다. 다음 도형을 사용할 수 있습니다. 여러 도형에는 해당 도형에만 해당하는 선택적 추가 필드가 포함됩니다. * **박스**: 사용: `MeshRenderer.setBox()`, 엔티티를 전달합니다. 다음을 전달하세요 `uvs` 을 추가 선택적 필드로 사용하여 텍스처 정렬을 매핑합니다. 다음을 참조하세요. [재질](/creator/content-creator-ko/sdk7/3d/materials.md) 자세한 내용은 다음을 참조하세요. * **평면**: 사용: `MeshRenderer.setPlane()`, 엔티티를 전달합니다. 다음을 전달하세요 `uvs` 을 추가 선택적 필드로 사용하여 텍스처 정렬을 매핑합니다. 다음을 참조하세요. [재질](/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) ``` 기본 도형에는 재질이 포함되지 않습니다. 색상이나 텍스처를 적용하려면 [material component](/creator/content-creator-ko/sdk7/3d/materials.md) 를 같은 엔티티에 할당해야 합니다. 기본 도형을 클릭 가능하게 만들거나 플레이어가 그것을 통과하지 못하게 하려면 엔티티에 *콜라이더* 를 다음을 통해 부여해야 합니다. [MeshCollider](/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) // shape 덮어쓰기 MeshRenderer.setSphere(myCube) ``` {% hint style="warning" %} **📔 참고**: `MeshRenderer` 컴포넌트는 다음을 통해 가져와야 합니다: > `import { MeshRenderer } from "@dcl/sdk/ecs"` 참고 [가져오기](/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-creator/blob/main/creator/3d-modeling/3d-models/README.md) 모델의 재질을 덮어쓰려면 다음을 사용하세요. [GltfNodeModifiers](/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 컴포넌트를 사용하여 모든 플레이어를 순회하세요. 자세한 내용은 [glTF 머티리얼 수정](/creator/content-creator-ko/sdk7/3d/materials.md#modify-gltf-materials) 자세한 내용은 다음을 참조하세요. 플레이어가 3D 모델을 통과하지 못하게 하거나 모델을 클릭 가능하게 만들려면 [콜라이더](/creator/content-creator-ko/sdk7/3d/colliders.md)가 필요하며, 이는 모델에 내장되어 있거나 `MeshCollider` 컴포넌트를 부여해야 합니다. 를 통해 제공될 수 있습니다. 모든 모델, 그 셰이더, 텍스처는 반드시 [씬 제한 사항](/creator/content-creator-ko/sdk7/optimizing/scene-limitations.md). {% hint style="warning" %} **📔 참고**: `GltfContainer` 컴포넌트는 다음을 통해 가져와야 합니다: `import { GltfContainer } from "@dcl/sdk/ecs"` 참고 [가져오기](/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", ], }) ``` 자세한 내용은 다음을 확인하세요 [리소스 미리 로드](/creator/content-creator-ko/sdk7/optimizing/pre-load-resources.md) 문서를 확인하세요. ### 3D 모델용 무료 라이브러리 직접 3D 모델을 만드는 대신, 여러 무료 또는 유료 라이브러리에서 다운로드할 수도 있습니다. 시작하는 데 도움이 되도록, 아래에는 무료 또는 비교적 저렴한 콘텐츠를 제공하는 라이브러리 목록이 있습니다. * [IWB Catalog](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으로 유지하는 것이 좋습니다. 이렇게 하면 더 빨리 나타나게 할 수 있습니다. 단점은 사용하지 않을 때 메모리를 차지한다는 점입니다. 다음을 참조하세요. [엔티티와 컴포넌트](/creator/content-creator-ko/sdk7/architecture/entities-components.md#pooling-entities-and-components) ## 도형 늘리기 기본 도형과 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 모델의 렌더링이 완료되었는지 확인하려면 엔티티의 `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` 필드를 사용하면 허용되는 유형 중 하나를 지정할 수 있습니다. 각 유형은 서로 다른 매개변수 집합을 지원합니다. 위 예시에서 `박스` 유형은 `uvs` 필드에 붙여 넣어 자체 스트리밍 인프라를 지정하세요. 다음의 지원되는 값은 `$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 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/creator/content-creator-ko/sdk7/3d/shape-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.