> 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/materials.md).

# 재질

단순한 형태의 엔티티에 재질과 텍스처를 추가하는 방법을 알아봅니다.

## 머티리얼

큐브, 구, 평면 등의 기본 도형을 사용하는 엔티티에는 다음을 추가해 머티리얼을 적용할 수 있습니다. `Material` 컴포넌트입니다. 이 컴포넌트에는 머티리얼 속성을 설정하고 텍스처를 추가하는 등의 작업을 할 수 있는 여러 필드가 있습니다.

*glTF* 모델에는 자체 머티리얼이 포함되어 있으며, 모델과 함께 씬으로 암시적으로 가져옵니다. 이러한 머티리얼을 수정하거나 재정의하려면 `GltfNodeModifiers` 컴포넌트를 사용하세요. 자세한 내용은 [glTF 머티리얼 수정](#modify-gltf-materials) 을 참조하세요.

자체 머티리얼이 있는 3D 모델을 가져올 때는 모든 셰이더가 Decentraland 엔진에서 지원되는 것은 아니라는 점에 유의하세요. 표준 머티리얼과 PBR(물리 기반 렌더링) 머티리얼만 지원됩니다. 자세한 내용은 [외부 3D 모델 고려 사항](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/materials.md) 을 참조하세요.

지원되는 머티리얼 유형은 다음과 같습니다.

* PBR(물리 기반 렌더링): Decentraland에서 가장 일반적으로 사용되는 머티리얼 유형입니다. 단색이나 텍스처를 지원하며, 금속성, 발광, 투명도 등 다양한 속성을 설정할 수 있습니다. 자세한 내용은 [PBR](https://en.wikipedia.org/wiki/Physically_based_rendering).
* 기본 머티리얼: 조명과 그림자의 영향을 받지 않으므로 빌보드 이미지를 표시하는 데 적합합니다.

## Creator Hub의 Scene Editor 사용

엔티티에 머티리얼을 적용하는 가장 쉬운 방법은 Scene Editor를 사용하는 것입니다. 엔티티에 **머티리얼** 컴포넌트를 추가한 다음 Scene Editor UI에서 사용 가능한 모든 필드를 설정할 수 있습니다. 자세한 내용은 [컴포넌트 추가](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/build/components.md#add-components).

## 머티리얼 추가

다음 예제에서는 PBR 머티리얼을 생성하고 일부 필드를 설정해 빨간색과 금속성 속성을 부여합니다. 이 머티리얼은 박스 모양도 있는 엔티티에 추가되므로 해당 머티리얼의 색상으로 박스가 칠해집니다.

```ts
//엔티티를 생성하고 모양 지정
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//머티리얼을 생성하고 필드 설정
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
	metallic: 0.8,
	roughness: 0.1,
})
```

이미 `Material` 컴포넌트가 있는 엔티티의 머티리얼을 변경하려면 `Material.setPbrMaterial()` 또는 다른 헬퍼 함수를 실행하면 원래 머티리얼이 덮어써집니다. 기존 머티리얼을 제거하거나 `Material` 고급 구문을 사용할 필요는 없습니다.

```ts
//엔티티를 생성하고 모양 지정
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//머티리얼을 생성하고 필드 설정
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Red(),
})

//새 머티리얼 컴포넌트로 덮어쓰기
Material.setPbrMaterial(meshEntity, {
	albedoColor: Color4.Blue(),
})
```

{% hint style="warning" %}
**📔 참고**: `Material` 컴포넌트는 다음을 통해 가져와야 합니다.

> `import { Material } from "@dcl/sdk/ecs"`

자세한 내용은 [가져오기](https://docs.decentraland.org/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 에서 쉽게 처리하는 방법을 확인하세요.
{% endhint %}

## 머티리얼 색상

머티리얼에 단색을 지정합니다. PBR 머티리얼에서는 `albedoColor` 필드를 설정합니다. 알베도 색상은 조명의 영향을 받으며 음영을 포함할 수 있습니다.

색상 값의 유형은 `Color4`, 다음으로 구성됩니다 *r*, *g* 및 *b* 값(빨강, 초록, 파랑)입니다. 각 값은 0에서 1 사이입니다. 값을 다르게 설정하면 눈에 보이는 모든 색상을 만들 수 있습니다. 검은색은 세 값을 모두 0으로, 흰색은 모두 1로 설정합니다.

{% hint style="warning" %}
**📔 참고**:  `albedoColor` 의 색상 값을 *1*보다 높게 설정하면  *발광하는 것처럼*표시되며, 값이 클수록 더 강하게 빛납니다. 예를 들어,  `{r: 15, g: 0, b: 0}` 은 매우 밝은 빨간색 빛을 냅니다.
{% endhint %}

색상 설정 방법에 관한 자세한 내용은  [색상 유형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/color-types.md) 을 참고하세요.

PBR 머티리얼에서 다음 필드를 수정하여 색상이 인식되는 방식을 세밀하게 조정할 수도 있습니다.

* *emissiveColor*: 머티리얼에서 방출되는 색상입니다.
* *reflectivityColor*: 다른 명명법으로는  *스페큘러 색상* 이라고도 합니다.

환경의 빛과 그림자의 영향을 받지 않는 단색 머티리얼을 만들려면 PBR 머티리얼 대신 기본 머티리얼을 만드세요.

```ts
Material.setBasicMaterial(myEntity, {
	diffuseColor: Color4.Black(),
})
```

## 텍스처 사용

이미지 파일을 머티리얼의 텍스처로 설정하려면  `texture` 매개변수를 설정하세요.

```ts
//엔티티를 생성하고 모양 지정
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity)

//머티리얼을 생성하고 필드 설정
Material.setPbrMaterial(meshEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
	}),
})
```

위 예시에서 머티리얼 이미지는 장면 프로젝트 폴더의 루트에 있는  `assets/materials` 폴더에 있습니다.

{% hint style="info" %}
**💡 팁**: 텍스처 이미지 파일은 장면 내의  `/assets` 폴더에 보관하는 것이 좋습니다.
{% endhint %}

텍스처를 만들 때 추가 매개변수도 전달할 수 있습니다.

* `filterMode`: 렌더링할 때 텍스처의 픽셀을 늘리거나 줄이는 방식을 결정합니다.  `TextureFilterMode` 열거형의 값을 사용합니다. 자세한 내용은  [텍스처 크기 조정](#texture-scaling).
* `wrapMode`: 텍스처를 객체에 타일 형식으로 적용하는 방식을 결정합니다.  `TextureWrapMode` 열거형을 참조하세요. 자세한 내용은 [텍스처 래핑](#texture-wrapping).

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
		filterMode: TextureFilterMode.TFM_BILINEAR,
		wrapMode: TextureWrapMode.TWM_CLAMP,
	}),
})
```

환경의 빛과 그림자의 영향을 받지 않는 텍스처를 만들려면 PBR 머티리얼 대신 기본 머티리얼을 만드세요.

```ts
Material.setBasicMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
	}),
})
```

### 외부 URL의 텍스처

씬 프로젝트의 내부 경로 대신 외부 URL을 머티리얼의 텍스처 경로로 지정할 수 있습니다.

```ts
Material.setBasicMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'https://wearable-api.decentraland.org/v2/collections/community_contest/wearables/cw_tuxedo_tshirt_upper_body/thumbnail',
	}),
})
```

URL은 다음으로 시작해야 합니다. `https`, `http` URL은 지원되지 않습니다.

### 텍스처 래핑

텍스처가 표면에 정렬되는 방식을 설정할 수 있습니다. 기본적으로 텍스처는 표면을 한 번 채우도록 늘어나지만, 크기를 조정하거나 오프셋을 설정할 수 있습니다.

모든 텍스처에서 다음 필드를 사용할 수 있습니다.

* `offset`: 텍스처를 이동해 정렬을 변경합니다. 값은 Vector2이며, 두 축 모두 0에서 1 사이의 값을 사용합니다. 1은 텍스처의 전체 너비 또는 높이에 해당합니다.
* `tiling`: 텍스처의 크기를 조정합니다. 기본값은 Vector2 `[1, 1]`이며, 이 값은 이미지가 표면 전체를 덮도록 한 번 반복되게 합니다.
* `TextureWrapMode`: 이미지의 타일링이 표면 전체를 덮지 못할 때의 동작을 결정합니다. 이 속성에는 다음 값을 사용할 수 있는 `TextureWrapMode` 열거형의 값이 지정됩니다.
  * `TextureWrapMode.TWM_CLAMP`: 지정된 크기로 텍스처를 한 번만 표시합니다. 메시의 나머지 표면은 투명하게 남습니다. tiling의 값은 `tiling` 무시됩니다.
  * `TextureWrapMode.TWM_REPEAT`: 지정된 크기를 사용해 메시를 채울 수 있을 만큼 텍스처를 반복합니다.
  * `TextureWrapMode.TWM_MIRROR`: 래핑 모드와 마찬가지로 텍스처를 메시를 채울 수 있을 만큼 반복하지만, 반복되는 텍스처의 방향이 서로 반전됩니다.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
		offset: Vector2.create(0, 0.2),
		tiling: Vector2.create(1, 1),
	}),
})
```

{% hint style="warning" %}
**📔 참고**: `offset` 및 `tiling` 속성은 DCL 2.0 데스크톱 클라이언트에서만 지원됩니다.
{% endhint %}

이 기능을 사용하면 타일 패턴으로 넓은 표면을 덮을 수 있습니다. 예를 들어 다음 이미지를 반복해 보세요.

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-9fc3c9552e1da78b7ab43f388bab8c2d91b010fd%2Ftiles.webp?alt=media)

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'assets/materials/wood.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
		tiling: Vector2.create(8, 8),
	}),
})
```

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-b432accf316018a223e2902f5dd392b6d5d54c2c%2Ftiles-in-scene.webp?alt=media)

아래 예시에서 텍스처는 *미러* 래핑 모드를 사용하며, 텍스처가 반복될 때마다 표면의 1/4만 차지합니다. 즉, 두 축 모두에서 서로를 향해 반전된 이미지 사본 4개가 표시됩니다.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/atlas.png',
		wrapMode: TextureWrapMode.TWM_MIRROR,
		tiling: Vector2.create(0.25, 0.25),
	}),
})
```

### 텍스처 트윈

Tween을 사용해 텍스처를 부드럽게 슬라이드하세요. `Tween` 컴포넌트를 `TextureMove` 모드로 설정합니다. 트윈은 일정 시간 동안 텍스처의 `offset` 또는 `tiling` 속성 값을 부드럽고 최적화된 방식으로 점진적으로 변경합니다.

{% hint style="warning" %}
**📔 참고**: 텍스처 트윈은 DCL 2.0 데스크톱 클라이언트에서만 지원되는 기능입니다.
{% endhint %}

두 위치 사이에서 텍스처를 이동하려면 `Tween` 컴포넌트와 `setTextureMove` 함수를 사용합니다.

```ts
Tween.setTextureMove(myEntity, Vector2.create(0, 0), Vector2.create(1, 0), 2000)
```

텍스처 트윈에는 다음 정보가 사용됩니다.

* `entity`: 텍스처를 이동할 엔티티
* `start`: 시작 위치를 나타내는 Vector2
* `end`: 끝 위치를 나타내는 Vector2
* `duration`: 두 위치 사이를 이동하는 데 걸리는 시간(밀리초)

다음 선택적 매개변수도 사용할 수 있습니다.

* `movementType`: 이동을 `offset` 필드에서 수행할지 `tiling` 필드에서 수행할지 지정합니다. 기본값은 `offset`.
* `easingFunction`: 시간에 따른 변화율 곡선입니다. 기본값은 `EasingFunction.EF_LINEAR`입니다. 다른 값을 사용하면 변화가 서로 다른 속도로 가속하거나 감속합니다.

```ts
const myEntity = engine.addEntity()

MeshRenderer.setPlane(myEntity)

Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/water.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})

Tween.setTextureMove(myEntity, Vector2.create(0, 0), Vector2.create(0, 1), 1000)
```

위 예제에서는 1초 동안 지속되는 트윈이 실행되어 텍스처를 한 번만 이동합니다. 폭포가 흐르는 모습을 표현하는 것처럼 연속해서 이동하려면 `setTextureMoveContinuous`.

```ts
const myEntity = engine.addEntity()

MeshRenderer.setPlane(myEntity)

Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/water.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})

Tween.setTextureMoveContinuous(myEntity, Vector2.create(0, 1), 1)
```

위 예제에서는 `setTextureMoveContinuous`를 사용하고 방향은 `(0, 1)`, 속도는 초당 1단위로 설정합니다.

텍스처 연속 트윈은 다음 정보를 사용합니다:

* `entity`: 텍스처를 이동할 엔티티
* `direction`: 움직임 방향을 나타내는 Vector2
* `speed`: 엔티티가 초당 이동할 단위 수

다음과 같은 선택적 매개변수도 사용할 수 있습니다.

* `movementType`: 움직임을 오프셋 필드에서 적용할지, 타일링 필드에서 적용할지 지정합니다. 기본값은 오프셋입니다.
* `duration`: 이동을 유지할 시간(밀리초)입니다. 이 시간이 지나면 이동이 멈춥니다.

**복잡한 트윈 시퀀스**

원하는 만큼 여러 단계를 지정해 텍스처 이동이 복잡한 시퀀스를 따르게 할 수도 있습니다. `sequence` 필드에 원하는 만큼 트윈을 나열하면, `Tween` 컴포넌트에 지정된 첫 번째 트윈 다음에 순서대로 실행됩니다.

```ts
//(...)
Tween.setTextureMove(myEntity, Vector2.create(0, 0), Vector2.create(0, 1), 1000)

TweenSequence.create(myEntity, {
	sequence: [
		{
			mode: Tween.Mode.TextureMove({
				start: Vector2.create(0, 1),
				end: Vector2.create(1, 1),
			}),
			duration: 1000,
			easingFunction: EasingFunction.EF_LINEAR,
		},
		{
			mode: Tween.Mode.TextureMove({
				start: Vector2.create(1, 1),
				end: Vector2.create(1, 0),
			}),
			duration: 1000,
			easingFunction: EasingFunction.EF_LINEAR,
		},
		{
			mode: Tween.Mode.TextureMove({
				start: Vector2.create(1, 0),
				end: Vector2.create(0, 0),
			}),
			duration: 1000,
			easingFunction: EasingFunction.EF_LINEAR,
		},
	],
	loop: TweenLoop.TL_RESTART,
})
```

TweenSequence 안에서 트윈을 정의할 때는 더 자세한 형식인 다음 형식을 사용해야 합니다. `Tween.Mode.TextureMove` 트윈을 정의합니다.

### 다중 레이어 텍스처

여러 이미지 파일을 레이어로 사용해 더 사실적인 텍스처를 만들 수 있습니다. 예를 들어 다음을 포함할 수 있습니다. `bumpTexture` 와 `emissiveTexture`.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/wood.png',
	}),
	bumpTexture: Material.Texture.Common({
		src: 'materials/woodBump.png',
	}),
	emissiveTexture: Material.Texture.Common({
		src: 'materials/glow.png',
	}),
})
```

bumpTexture `bumpTexture` 는 각 픽셀에서 표면 법선의 동작 방식을 변경하여 표면의 요철과 주름을 시뮬레이션할 수 있습니다.

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c10fa878ba8f8a81fa0d124ec6680cde048f20b1%2Fwood-bump.webp?alt=media)

emissiveTexture `emissiveTexture` 는 재질의 특정 부분에서 빛나는 효과를 강조해 매우 흥미로운 효과를 낼 수 있습니다.

**UV 설정**

텍스처의 크기나 정렬을 변경하는 또 다른 방법은 다음 항목의 *uv* 속성을 구성하는 것입니다. [MeshRenderer 컴포넌트](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/shape-components.md).

텍스처의 2D 이미지에서 도형의 정점에 해당하는 *u* 및 *v* 좌표를 설정합니다. 엔티티에 정점이 많을수록 텍스처에 정의해야 하는 *uv* 좌표도 많아집니다. 예를 들어 평면에는 *uv* 총 8개의 점을 정의해야 하며, 양쪽 면에 각각 4개씩 필요합니다.

```ts
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setPlane(
	meshEntity,
	[
		0, 0.75,

		0.25, 0.75,

		0.25, 1,

		0, 1,

		0, 0.75,

		0.25, 0.75,

		0.25, 1,

		0, 1,
	]
)

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/wood.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})
```

다음 예제에는 UV 설정을 간소화하는 함수가 포함되어 있습니다. 여기서 정의한 `setUVs` 함수는 매개변수로 행과 열의 개수를 받아 텍스처 이미지가 지정된 횟수만큼 반복되도록 UV를 설정합니다.

```ts
const meshEntity = engine.addEntity()
Transform.create(meshEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(meshEntity, setUVs(3, 3))

Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/atlas.png',
		wrapMode: TextureWrapMode.TWM_REPEAT,
	}),
})

function setUVs(rows: number, cols: number) {
	return [
		// 회전하지 않은 평면의 북쪽 면
		0, // 왼쪽 아래 모서리
		0,

		cols, // 오른쪽 아래 모서리
		0,

		cols, // 오른쪽 위 모서리
		rows,

		0, // 왼쪽 위 모서리
		rows,

		// 회전하지 않은 평면의 남쪽 면
		cols, // 오른쪽 아래 모서리
		0,

		0, // 왼쪽 아래 모서리
		0,

		0, // 왼쪽 위 모서리
		rows,

		cols, // 오른쪽 위 모서리
		rows,
	]
}
```

다음의 UV를 설정하려면 `box` 메시 모양에도 동일한 구조가 적용됩니다. 큐브의 6개 면은 각각 모서리마다 하나씩, 좌표 쌍 4개를 사용합니다. 이 48개 값은 모두 하나의 배열로 나열됩니다.

{% hint style="warning" %}
**📔 참고**: UV 속성은 현재 다음에서만 사용할 수 있습니다. `plane` 및 `box` 모양에서만 사용할 수 있습니다. 또한 *uv* 값은 *shape*.
{% endhint %}

### 에 설정되므로 모든 텍스처 레이어에 동일하게 적용됩니다.

텍스처 크기 조정 [텍스처를 원본 이미지와 다른 크기로 늘리거나 줄이면 아티팩트가 생길 수 있습니다. 3D 환경에서는 원근 효과로 인해 이러한 현상이 자연스럽게 발생합니다. 이를 각기 다른 방식으로 보정하는 다양한](https://en.wikipedia.org/wiki/Texture_filtering) 텍스처 필터링

알고리즘이 있습니다. `Material` 객체는 기본적으로 *쌍선형* 알고리즘을 사용하지만, 텍스처의 *최근접 이웃* 또는 *삼선형* 알고리즘을 사용하도록 설정할 수도 있습니다. 텍스처의 `filterMode` 속성을 설정하면 됩니다. 이 속성에는 `TextureFilterMode` 열거형의 값을 지정합니다.

* `TextureFilterMode.TFM_POINT`: "최근접 이웃" 알고리즘을 사용합니다. 텍스처가 화면에서 확대되어 표시될 때 흐려지지 않고 윤곽이 선명하게 유지되므로 픽셀 아트 스타일 그래픽에 적합합니다.
* `TextureFilterMode.TFM_BILINEAR`: 쌍선형 알고리즘을 사용해 각 픽셀의 색상을 추정합니다.
* `TextureFilterMode.TFM_TRILINEAR`: 삼선형 알고리즘을 사용해 각 픽셀의 색상을 추정합니다.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Common({
		src: 'materials/atlas.png',
		filterMode: TextureFilterMode.TFM_BILINEAR,
	}),
})
```

## 비조명 머티리얼

대부분의 경우 장면의 머티리얼이 그림자를 포함한 조명 조건의 영향을 받고, 시간대에 따라 달라지는 색조가 반영되도록 하고 싶을 것입니다. 하지만 색상을 본래 그대로 표시하고 싶은 경우도 있습니다. 동영상을 재생할 때나 플레이어에게 단서를 전달하기 위해 눈에 띄어야 하는 추상적인 표식을 표시할 때 유용합니다.

비조명 머티리얼을 만들려면 `Material.setBasicMaterial`을 사용합니다. 기본 머티리얼에는 PBR 머티리얼과 같은 속성이 모두 있는 것은 아니며, 필수 속성만 포함됩니다.

* `diffuseColor`: 색상을 나타내는 Color4
* `texture`: 텍스처
* `alphaTexture`: 투명도 레이어에 사용할 별도의 텍스처
* `alphaTest`: 텍스처 색상을 기준으로 투명도를 결정하는 임계값
* `castShadows`: false이면 장면의 다른 엔티티에 그림자가 드리워지지 않습니다.

```ts
Material.setBasicMaterial(screen, {
	diffuseColor: Color4.Red(),
})
```

## 아바타 초상화

플레이어의 썸네일 이미지를 표시하려면 `Material.Texture.Avatar` 를 사용해 머티리얼의 텍스처를 설정하고, 기존 플레이어의 주소를 전달하세요. 그러면 플레이어의 머리와 어깨가 보이는 256x256 이미지를 바탕으로 텍스처가 생성됩니다. 플레이어는 현재 서버에 마지막으로 기록된 웨어러블 세트를 착용한 모습으로 표시됩니다.

```ts
Material.setPbrMaterial(myEntity, {
	texture: Material.Texture.Avatar({
		userId: '0x517....',
	}),
})
```

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-7d9533dc2cdb50a2250e230346b85e1b458c6cc3%2FavatarTexture.webp?alt=media)

현재 접속 중이 아니거나 Decentraland 이름을 등록하지 않은 플레이어의 초상화도 가져올 수 있습니다.

인수로 전달하는 객체에서 다음 속성을 사용할 수 있습니다:

* `userId`: 프로필을 표시하려는 사용자의 ID
* `filterMode`: 렌더링할 때 텍스처의 픽셀을 늘리거나 줄이는 방식을 결정합니다.  `TextureFilterMode` 열거형의 값을 사용합니다. 자세한 내용은  [텍스처 크기 조정](#texture-scaling).
* `wrapMode`: 텍스처를 객체에 타일 형식으로 적용하는 방식을 결정합니다.  `TextureWrapMode` 열거형을 참조하세요. 자세한 내용은 [텍스처 래핑](#texture-wrapping).

## 투명한 머티리얼

단색 머티리얼을 투명하게 만들려면 색상을 다음과 같은 `Color4`로 정의하고, 네 번째 값을 *0* 와 *1*사이의 값으로 설정하면 됩니다. 값이 *1*에 가까울수록 불투명해집니다.

```typescript
let transparentRed = Color4.create(1, 0, 0, 0.5)

Material.setPbrMaterial(meshEntity, {
	albedoColor: transparentRed,
})
```

재질에서 투명도를 포함한 .png 텍스처를 사용하면 기본적으로 불투명하지만, 다음을 설정하여 투명도를 활성화할 수 있습니다. `transparencyMode` 을 `MaterialTransparencyMode.MTM_ALPHA_BLEND`.

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-4cfaaf2d24f923ceb5187b0b2d5039ec049085bf%2Ftransparent-image.webp?alt=media)

```typescript
Material.setPbrMaterial(floor, {
	texture: Material.Texture.Common({
		src: 'assets/scene/transparent-image.png',
	}),
	transparencyMode: MaterialTransparencyMode.MTM_ALPHA_BLEND,
})
```

transparencyMode `transparencyMode` 에는 다음 값을 지정할 수 있습니다:

* `MaterialTransparencyMode.MTM_OPAQUE`: 투명도가 전혀 없습니다
* `MaterialTransparencyMode.MTM_ALPHA_TEST`: 임계값에 따라 각 픽셀이 완전히 불투명하거나 완전히 투명합니다.
* `MaterialTransparencyMode.MTM_ALPHA_BLEND`: 각 픽셀의 값에 따라 중간 투명도 값을 사용할 수 있습니다.
* `MaterialTransparencyMode.MTM_ALPHA_TEST_AND_ALPHA_BLEND`: 두 방식을 함께 사용합니다.
* `MaterialTransparencyMode.MTM_AUTO`: 제공된 텍스처에 따라 방식을 결정합니다.

{% hint style="warning" %}
**📔 참고**: 다음을 항상 설정하세요 `transparencyMode` 텍스처 자체의 알파 채널이 비치도록 하려면 직접 설정해야 합니다. 데스크톱 클라이언트에서는 기본값인 `MTM_AUTO` 모드가 텍스처의 알파를 무시하고 `albedoColor` 의 알파가 1보다 작을 때만 블렌딩하므로, 투명한 `.png` 도 완전히 불투명하게 표시됩니다. 다음과 같이 설정하면 `MTM_ALPHA_BLEND` 또는 `MTM_ALPHA_TEST`의 경우 투명도는 텍스처의 알파에 `albedoColor` 알파를 곱한 값입니다.
{% endhint %}

를 `transparencyMode` 로 `MaterialTransparencyMode.MTM_ALPHA_TEST`설정하면 각 픽셀의 투명 여부를 판단하는 임계값을 세밀하게 조정할 수 있습니다. alphaTest `alphaTest` 속성을 다음 범위로 설정하세요: *0* 부터 *1*까지. 기본값은 *0.5*.

```ts
// 알파 테스트 사용
Material.setPbrMaterial(meshEntity1, {
	texture: Material.Texture.Common({
		src: 'images/myTexture.png',
	}),
	transparencyMode: MaterialTransparencyMode.MTM_ALPHA_TEST,
	alphaTest: 1,
})
```

언릿 머티리얼을 사용할 때는 [언릿 머티리얼](#unlit-materials)에 `alphaTexture` 를 추가하여 텍스처를 바탕으로 머티리얼의 특정 영역만 투명하게 만들 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 머티리얼이 표시되어야 하는 부분은 마스크를 흰색으로, 사라져야 하는 부분은 검은색으로 칠하세요. 클라이언트는 마스크 색상의 알파 채널이 아니라 밝기를 읽으므로, 채널 값이 최대인 색상은 모두 불투명하게 처리됩니다. 순수한 빨간색 마스크도 불투명합니다. 색상 텍스처를 마스크로 재사용하지 마세요. 텍스처의 어두운 픽셀이 모두 투명해져 윤곽선과 음영이 사라집니다.
{% endhint %}

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-901568ee2ece2fed1734c93716d4c7069869c47c%2Fcircular-video-screen.webp?alt=media)

```ts
// 마스크 이미지로 화면을 원형으로 자르기
Material.setBasicMaterial(meshEntity1, {
	texture: Material.Texture.Common({
		src: 'images/myTexture.png',
	}),
	alphaTexture: Material.Texture.Common({
		src: 'assets/scene/circle_mask.png',
		wrapMode: TextureWrapMode.TWM_MIRROR,
	}),
})
```

데스크톱 클라이언트에서 `alphaTexture` 를 사용할 때 알아둘 점이 두 가지 더 있습니다.

* **언릿 머티리얼에서만 작동합니다.** `Material.setPbrMaterial` 는 `alphaTexture` 를 인수로 받지만 사용하지는 않습니다. PBR 머티리얼에서는 색상 텍스처 자체의 알파 채널에 투명도를 지정하고 `transparencyMode` 를 대신 설정하세요.
* **alphaTexture `가 없는 언릿 머티리얼은 완전히 불투명하며` 완전히 불투명합니다**이며 `alphaTest` 는 아무런 효과가 없습니다. `texture` 와 `alphaTest` 만 사용하면 투명 픽셀의 색상이 표시되며, 보통 검은색입니다.

비디오와 함께 사용하면 매우 흥미로운 효과를 낼 수 있습니다. 자세한 내용은 다음을 참조하세요. [동영상 재생](https://docs.decentraland.org/creator/content-creator-ko/sdk7/media/video-playing.md).

## 동영상 재생

URL에서 머티리얼로 동영상을 스트리밍하거나 씬에 저장된 파일의 동영상을 재생하는 방법은 다음을 참조하세요. [동영상 재생](https://docs.decentraland.org/creator/content-creator-ko/sdk7/media/video-playing.md).

동영상은 머티리얼의 텍스처로 사용됩니다. 머티리얼의 다른 속성을 설정해 동영상 화면의 모양을 조정할 수 있습니다.

## 고급 구문

다음은 `Materials` 컴포넌트를 간소화하는 헬퍼 없이 생성하는 전체 구문입니다.

```ts
Material.create(myEntity, {
	material: {
		$case: 'pbr',
		pbr: {
			texture: {
				tex: {
					$case: 'texture',
					texture: {
						src: 'images/scene-thumbnail.png',
					},
				},
			},
		},
	},
})

Material.create(myEntity, {
	material: {
		$case: 'pbr',
		pbr: {
			texture: {
				tex: {
					$case: 'avatarTexture',
					avatarTexture: {
						userId: '0x517....',
					},
				},
			},
		},
	},
})
```

기본 프로토콜이 Materials 구성 요소를 해석하는 방식은 다음과 같습니다. 도우미 함수는 이 구문을 추상화해 더 편리한 구문을 제공하지만, 내부적으로는 이 구문을 출력합니다.

다음 `$case` 필드를 사용하면 허용된 유형 중 하나를 지정할 수 있습니다. 각 유형은 서로 다른 매개변수 집합을 지원합니다. 다음과 같은 두 가지 수준의 `$case` 여기에서:

* 다음 `material` 필드는 다음 값을 지원합니다. `pbr` 및 `unlit`, 재질의 종류를 정의합니다.
* 다음 `tex` texture 내부의 field는 텍스처 종류를 정의하기 위해 다음 값을 지원합니다.
  * `texture`
  * `avatarTexture`
  * `videoTexture`

값에 따라 `$case`, 해당 종류에 맞는 객체를 관련 속성과 함께 정의할 수 있습니다.

이미 이 컴포넌트의 인스턴스가 있을 수도 있는 엔티티에 `Material` 컴포넌트를 추가하려면 다음을 사용하세요 `Material.createOrReplace()`와 같은 헬퍼 함수는 `Material.setPbrMaterial()` 기존 컴포넌트 인스턴스를 덮어쓰지만, 이미 이 컴포넌트가 있는 엔티티에서 `Material.create()` 를 실행하면 오류가 반환됩니다.

## glTF 머티리얼 수정

를 사용해 `GltfNodeModifiers` 컴포넌트로 다음의 머티리얼을 수정하세요 *glTF* 모델입니다. 이 컴포넌트를 사용하면 *glTF* 모델의 머티리얼을 원하는 머티리얼로 재정의할 수 있습니다. 다음의 속성을 모두 사용할 수 있습니다: `Material` 컴포넌트의 속성(텍스처, 비디오 텍스처, 언릿 머티리얼 등)

GltfNodeModifiers `GltfNodeModifiers` 컴포넌트를 사용하는 방법은 두 가지입니다:

* path `path` 속성을 빈 문자열로 두어 모델 전체의 머티리얼을 수정합니다.
* path `path` 속성에 노드 경로를 지정하여 모델의 특정 노드(또는 여러 노드)의 머티리얼을 수정합니다.

### 모델 전체의 머티리얼 수정

다음 예시에서는 *glTF* 모델의 머티리얼을 수정하는 방법을 보여 줍니다. 이 경우 모델 전체의 머티리얼을 빨간색으로 변경합니다.

```ts
import { GltfNodeModifiers, GltfContainer, Transform } from '@dcl/sdk/ecs'

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: '',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						albedoColor: Color4.Red(),
					},
				},
			},
		},
	],
})
```

GltfNodeModifiers `GltfNodeModifiers` 컴포넌트에는 다음 속성이 있습니다:

* `modifiers`: 수정자 배열입니다. 각 수정자에는 다음 속성이 있습니다:
  * `path`: 수정할 모델 내 노드의 경로입니다.
  * `material`: 사용할 머티리얼입니다.

path `path` 속성은 수정할 *glTF* 모델 내 노드의 경로를 나타내는 문자열입니다. 모델 전체의 머티리얼을 수정하려면 빈 문자열을 사용할 수 있습니다. 특정 노드의 머티리얼을 수정하려면 해당 노드의 경로를 사용할 수 있습니다. 경로는 버텍스 노드가 아니라 메시 노드를 가리켜야 합니다.

{% hint style="info" %}
**💡 팁**: 다음을 사용해 [Babylon Sandbox 앱](https://sandbox.babylonjs.com/) 에서 *glTF* 모델을 검사하고 수정할 노드의 경로를 찾을 수 있습니다.

그러나 일부 모델에서는 Babylon Sandbox에 메시가 아닌 버텍스에 해당하는 경로가 표시될 수 있으며, 이 경로는 작동하지 않습니다. 유효하지 않은 경로를 사용하려고 하면 씬 콘솔에 해당 모델에서 사용할 수 있는 전체 경로 목록이 포함된 오류 메시지가 표시됩니다.
{% endhint %}

material `material` 속성은 사용할 머티리얼을 나타내는 객체입니다. 위 예시처럼 머티리얼의 [고급 구문](#advanced-syntax) 을 사용해 작성해야 합니다. 다음과 같은 헬퍼 함수는 `Material.setPbrMaterial()` 은 여기서 사용할 수 없습니다.

### 모델의 특정 노드 머티리얼 수정

다음 예제에서는 모델의 특정 노드 머티리얼을 수정하는 방법을 보여 줍니다. *glTF* 모델입니다. 이 경우 머리의 머티리얼이 대체 텍스처를 사용하도록 수정됩니다.

```ts
import { GltfNodeModifiers, GltfContainer, Transform } from '@dcl/sdk/ecs'

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: 'M_Head_BaseMesh',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						texture: Material.Texture.Common({
							src: 'assets/scene/images/blinking-head.png',
						}),
					},
				},
			},
		},
	],
})
```

A `GltfNodeModifiers` 에는 여러 수정자가 포함될 수 있으며, 각 수정자는 모델의 서로 다른 노드를 수정합니다. 다음 예제에서는 *glTF* 모델의 머리와 몸통의 머티리얼을 수정하는 방법을 보여 줍니다.

```ts
import { GltfNodeModifiers, GltfContainer, Transform } from '@dcl/sdk/ecs'

const myEntity = engine.addEntity()

GltfContainer.create(myEntity, {
	src: 'models/myModel.glb',
})

Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: 'M_Head_BaseMesh',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						albedoColor: Color4.Red(),
					},
				},
			},
		},
		{
			path: 'M_Body_BaseMesh',
			material: {
				material: {
					$case: 'pbr',
					pbr: {
						albedoColor: Color4.Blue(),
					},
				},
			},
		},
	],
})
```

### 기존 머티리얼의 필드 수정

Material 컴포넌트는 Material 컴포넌트 속성에 액세스하고 수정할 수 있는 간소화된 인터페이스를 제공합니다. 이를 통해 깊게 중첩된 유니온 구조체를 탐색할 필요가 없습니다(`PBR` 와 `Unlit`, `texture` 와 `avatarTexture` 와 `videoTexture`). 따라서 머티리얼을 더 직관적으로 조작할 수 있고 오류 발생 가능성도 줄어듭니다.

다음 메서드를 사용하면 `Material` 컴포넌트를 쉽게 조작할 수 있습니다.

* `Material.getFlat(entity: Entity): ReadonlyFlatMaterial`: 머티리얼 속성에 직접 읽기 액세스할 수 있는 **읽기 전용** `FlatMaterial` 접근자 객체를 반환합니다. 엔티티에 `Material` 컴포넌트가 없으면 오류를 반환합니다. 이를 방지하려면 다음 메서드를 대신 사용할 수 있습니다.

```ts
const src = Material.getFlat(entity).texture.src
```

* `Material.getFlatOrNull(entity: Entity): ReadonlyFlatMaterial | null`: 엔티티에 **읽기 전용 객체 또는 null**을 반환합니다. 엔티티에 `Material` 컴포넌트가 있는지에 따라 반환값이 달라집니다.

```ts
const src = Material.getFlatOrNull(entity)?.texture.src
```

* `Material.getFlatMutable(entity: Entity): FlatMaterial`: 속성을 수정할 수 있는 **읽기 및 쓰기** `FlatMaterial`객체를 반환합니다. 호출 대상 엔티티에 `Material` 컴포넌트가 없으면 오류를 발생시킵니다.

```ts
const src = Material.getFlatMutable(entity).texture.src
```

* `Material.getFlatMutableOrNull(entity: Entity): FlatMaterial | null`: 다음을 반환합니다. **읽기 및 쓰기 가능 객체 또는 null** `FlatMaterial` 속성을 수정할 수 있는 객체입니다. 엔티티에 `Material component`가 없는 경우 `null`.

```ts
const flatMaterial = Material.getFlatMutableOrNull(entity)
if (flatMaterial) {
	flatMaterial.texture.src = myNewTextureFile
}
```

### glTF 모델의 그림자 제거

glTF *glTF* 모델의 그림자를 제거하려면 `castShadows` 속성을 `false` 로 설정하면 됩니다.  `GltfNodeModifiers`  객체에서 설정합니다. 이렇게 하면 모델의 원래 머티리얼은 유지하면서 그림자를 드리우지 않도록 할 수 있습니다. 광선처럼 그림자를 드리우지 않아야 하는 모델에 유용합니다.

```ts
import { GltfNodeModifiers } from '@dcl/sdk/ecs'

GltfNodeModifiers.create(myEntity, {
	modifiers: [
		{
			path: '',
			castShadows: false,
		},
	],
})
```

{% hint style="info" %}
**💡 팁**: 머티리얼에 사용되는 텍스처는 파티클 효과에도 적용할 수 있습니다. 파티클에 사용자 지정 텍스처와 스프라이트 시트를 사용하는 방법은 [Particle System](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/particle-system.md) 에서 자세히 알아보세요.
{% endhint %}

{% hint style="info" %}
**💡 팁**: 머티리얼 사용 예제는 다음 테스트 씬을 참고하세요. [`52,-52-testing-gallery`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/52,-52-testing-gallery) 에서는 PBR 메탈릭/러프니스/이미시브/노멀 맵 조합을 나란히 비교하고, [`74,-8-gltfnodemodifier`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/74,-8-gltfnodemodifier)에서는 개별 GLTF 노드의 PBR 및 언릿 머티리얼을 재정의하며, [`0,3-texture-movement`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,3-texture-movement)에서는 텍스처 오프셋과 타일링을 애니메이션으로 적용합니다.
{% endhint %}


---

# 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/sdk7/3d/materials.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.
