형상 컴포넌트

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

Decentraland의 3차원 장면은 엔티티-컴포넌트 모델에 기반하며, 장면의 모든 것은 엔티티이며, 각 엔티티는 컴포넌트 특성과 기능을 형성하는 컴포넌트를 포함할 수 있습니다.

엔티티의 렌더링된 모양은 어떤 컴포넌트를 사용하는지에 따라 결정됩니다.

Creator Hub의 Scene Editor를 사용하세요

엔티티에 모양을 부여하는 가장 쉬운 방법은 Scene Editor를 사용하는 것입니다. 다음을 추가할 수 있습니다. 메시 렌더러 기본 도형을 제공하는 컴포넌트 또는 GLTF 파일의 3D 모델을 참조하는 컴포넌트입니다. 다음을 참조하세요. 컴포넌트 추가.

기본 도형

종종 기본 도형라고 불리는 몇 가지 기본 모양은 엔티티에 MeshRenderer 컴포넌트를 추가해야 합니다.

다음 모양을 사용할 수 있습니다. 여러 모양에는 해당 모양에만 해당하는 선택적 추가 필드가 포함됩니다.

• 박스:

  다음을 사용하세요 MeshRenderer.setBox()를 사용하고, 엔티티를 전달합니다. 추가 선택 필드로 uvs 는 텍스처 정렬을 매핑하기 위한 추가 선택 필드로 사용할 수 있습니다. 다음을 참조하세요. 재질 자세한 내용은.

• 평면:

  다음을 사용하세요 MeshRenderer.setPlane()를 사용하고, 엔티티를 전달합니다. 추가 선택 필드로 uvs 는 텍스처 정렬을 매핑하기 위한 추가 선택 필드로 사용할 수 있습니다. 다음을 참조하세요. 재질 자세한 내용은.

• 구:

  다음을 사용하세요 MeshRenderer.setSphere()를 사용하고, 엔티티를 전달합니다.

• 원통:

  다음을 사용하세요 MeshRenderer.setCylinder()를 사용하고, 엔티티를 전달합니다. 추가 선택 필드로 radiusTop 과 radiusBottom 을 전달하여 원통을 수정할 수 있습니다.

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

다음 예제는 큐브를 생성합니다:

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

다음 예제는 다음과 같은 원통을 생성합니다. radiusTop 가 0인 원통으로, 원뿔이 생성됩니다:

const myCone = engine.addEntity()

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

MeshRenderer.setCylinder(myCone, 1, 0)

기본 도형에는 머티리얼이 포함되지 않습니다. 색상이나 텍스처를 부여하려면 동일한 엔티티에 머티리얼 컴포넌트 를 할당해야 합니다.

기본 도형을 클릭 가능하게 하거나 플레이어가 그 안을 통과하지 못하게 하려면, 엔티티에 collider 를 통해 MeshCollider 컴포넌트를 추가해야 합니다.

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

const myCube = engine.addEntity()

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

MeshRenderer.setBox(myCube)

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

📔 참고: MeshRenderer 구성 요소는 다음을 통해 import해야 합니다

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

다음 가져오기 를 참고해 쉽게 처리하는 방법을 확인하세요.

3D 모델

더 복잡한 모양의 경우, Blender 같은 외부 도구에서 3D 모델을 만든 다음 이를 가져와 .glTF 또는 .glb (binary .glTF). glTF (GL Transmission Format)은 Khronos의 오픈 프로젝트로, 효율적이고 현대 웹 기술과의 상호운용성이 뛰어난 3D 자산용 공통 확장 가능 형식을 제공합니다.

외부 모델을 장면에 추가하려면, 엔티티에 GltfContainer 컴포넌트를 추가하고 그 src 을 모델이 들어 있는 glTF 파일의 경로로 설정하세요.

const houseEntity = engine.addEntity()

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

이 src 필드가 필요하므로, 컴포넌트를 구성할 때 값을 지정해야 합니다. 위 예제에서 모델은 models 장면 프로젝트 폴더의 루트 수준에 있는 폴더에 있습니다.

💡 팁: 모델은 assets/scene/models 폴더에 분리해 두는 것을 권장합니다.

glTF 모델에는 자체적으로 포함된 텍스처, 머티리얼, 콜라이더 및 애니메이션이 포함될 수 있습니다. 이에 대한 자세한 내용은 3D 모델 를 참조하세요. 모델의 머티리얼을 재정의하려면 GltfNodeModifiers 컴포넌트가 붙은 모든 플레이어를 순회하세요. 자세한 내용은 glTF 재질 수정 자세한 내용은.

3D 모델을 플레이어가 통과하지 못하게 하거나 모델을 클릭 가능하게 만들려면, 다음이 필요합니다. collider, 이는 모델에 포함되어 있거나 MeshCollider 컴포넌트를 추가해야 합니다.

를 통해 제공될 수 있습니다. 모든 모델과 해당 셰이더 및 텍스처는 씬 제한 사항.

📔 참고: GltfContainer 구성 요소는 다음을 통해 import해야 합니다

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

다음 가져오기 를 참고해 쉽게 처리하는 방법을 확인하세요.

3D 모델 미리 로드하기

경우에 따라 사용자 지정 3D 모델이 장면에 추가되지만 바로 사용되지는 않습니다. 예를 들어, 사용자 지정 의자 모델은 플레이어가 다른 객체와 상호작용할 때만 로드될 수 있습니다. 이런 상황에서는 모델 다운로드와 로딩이 끝날 때까지 첫 상호작용에 시간이 걸릴 수 있습니다.

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

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

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

자세한 내용은 다음을 확인하세요 리소스 미리 로드 문서를 참고하세요.

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

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

시작하기 쉽게, 아래는 무료 또는 비교적 저렴한 콘텐츠가 있는 라이브러리 목록입니다:

• IWB Catalog

• Asset Ovi

• Builder의 에셋

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

• Thingiverse (주로 3D 프린팅용으로 만들어졌지만 가상 세계에 적용할 수 있는 3D 모델)

• ShareCG

• CGTrader

📔 참고: 다운로드한 콘텐츠에 적용되는 라이선스 제한에 주의하세요.

이들 사이트 중 몇 곳에서는 모델을 어떤 형식으로 다운로드할지 선택할 수 있습니다. 항상 .glTF 형식을 선택하세요. 사용할 수 없다면, 장면에서 사용하기 전에 glTF 장면에서 사용하기 전에. 이를 위해, Blender로 가져와서 .glTF 형식으로 내보내는 것을 권장합니다.

3D 모델 최적화

장면의 3D 모델이 더 빨리 로드되고 메모리를 덜 차지하도록 하려면 다음 모범 사례를 따르세요:

• 모델을 .glb 형식으로 저장하세요. 이는 .gltf.

• 동일한 텍스처를 공유하는 모델이 여러 개라면, 텍스처가 있는 모델을 별도의 파일로 내보내세요. 이렇게 하면 여러 모델이 한 번만 로드하면 되는 단일 텍스처 파일을 참조할 수 있습니다.

• 장면에 나타났다 사라지는 엔티티가 있다면, 이 엔티티들을 풀링하고 지하에 두거나 크기를 0으로 유지하는 것이 좋습니다. 이렇게 하면 더 빨리 나타나는 데 도움이 되지만, 사용하지 않을 때 메모리를 차지한다는 단점이 있습니다. 다음을 참조하세요. 엔티티와 컴포넌트

모양 늘리기

기본 도형과 3D 모델은 기본 치수를 가지며, 엔티티의 Transform 컴포넌트를 추가해야 합니다.

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, 표시되는 속성이 false.

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라면, 이 설정은 아래로 내려가는 모든 수준의 자식에게 영향을 줍니다. 이렇게 하면 각 자식 엔티티를 보이지 않게 또는 보이게 표시하는 번거로운 작업을 많이 줄일 수 있습니다.

// 부모 엔티티(명시적으로 보이지 않음)
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)

📔 참고: 엔티티에 자체 VisibilityComponent가 있다면, 이는 부모의 모든 구성을 덮어씁니다.

엔티티에 자체 VisibilityComponent가 없다면, 그 가시성은 VisibilityComponent 과 propagateToChildren 다음으로 설정되어 있고 true.

로딩 상태

3D 모델이 상당히 크다면 렌더링되는 데 눈에 띄는 시간이 걸릴 수 있으며, 이 시간은 플레이어의 하드웨어와 기타 여러 요인에 따라 달라질 수 있습니다. 때로는 다른 동작을 수행하기 전에 모델 로딩이 완료되었는지 확인해야 합니다. 예를 들어, 플레이어를 하늘 위의 플랫폼으로 순간이동시키고 싶다면, 먼저 플랫폼이 완전히 렌더링되었는지 확인한 뒤 플레이어를 그곳으로 이동시켜야 합니다. 그렇지 않으면 플레이어가 플랫폼을 그대로 통과해 떨어질 수 있습니다.

3D 모델의 렌더링이 끝났는지 확인하려면 엔티티의 GltfContainerLoadingState 컴포넌트를 확인하세요. 이 컴포넌트는 읽기 전용이며, 다음이 있는 모든 엔티티에 존재합니다. GltfContainer컴포넌트를 추가해야 합니다.

이 컴포넌트에는 이름이 currentState인 단일 속성이 있으며, LoadingState 열거형.

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

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는 로딩 중입니다')
				break
			case LoadingState.FINISHED:
				console.log('mesh는 완료되었습니다')
				// 사용자 지정 로직 수행
				break
			case LoadingState.FINISHED_WITH_ERROR:
				console.log('mesh는 완료되었지만 문제가 있을 수 있습니다')
				break
			case LoadingState.UNKNOWN:
				console.log('mesh는 알 수 없는 상태입니다')
				break
		}
	})
}

고급 구문

다음을 생성하는 전체 문법은 MeshRenderer 컴포넌트이며, 이를 단순화하는 어떤 헬퍼도 사용하지 않으면 다음과 같습니다:

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() 를 이미 이 컴포넌트가 있는 엔티티에서 실행하면 오류가 반환됩니다.