# MaterialVariant

MaterialVariant : `Instance`

## Overview

MaterialVariant는 기존 Material을 확장하거나 대체하기 위해 활용되는 사용자 정의 Material 객체입니다. 이 객체를 사용하시면 월드 전체 또는 특정 파트에서 고유한 표면 질감, 색상, 반사도 등 다양한 시각적 특성을 구현할 수 있습니다.

MaterialVariant는 반드시 MaterialService의 하위 계층에 배치되어야 정상적으로 작동하며, 해당 구조를 벗어나면 기능이 적용되지 않으므로 구성 시 주의가 필요합니다.

## Properties

### BaseMaterial

`Enum.Material`

MaterialVariant가 어떤 기본 소재 그룹에 속하는지를 나타내는 분류 정보입니다.

이 값을 기반으로 해당 변형이 어떤 소재 계열을 확장하는지 판단하며, 렌더링 및 특성 적용 시 이를 참고하여 처리합니다.

#### Code Samples

```lua
local MaterialVariant = Instance.new("MaterialVariant")

MaterialVariant.BaseMaterial = Enum.Material.Plastic
```

### ColorMap

`Content`

어떤 색으로 표시될지를 지정하는 기본 색상 맵(알베도 텍스처)입니다. 광원이나 음영 효과와 결합하여 표면의 기본 색감을 형성합니다. 이 텍스처의 알파 채널은 렌더링 과정에서 참조되지 않으므로 불투명도 제어에는 사용되지 않습니다.

#### Code Samples

### CustomPhysicalProperties

`PhysicalProperties`

현재 지원되지 않습니다.

#### Code Samples

### Emissive

`Color3`

현재 지원되지 않습니다.

#### Code Samples

### EmissiveIntensity

`number`

현재 지원되지 않습니다.

#### Code Samples

### EmissiveMap

`Content`

현재 지원되지 않습니다.

#### Code Samples

### Metalness

`number`

표면이 금속처럼 빛을 반사하는 정도를 정의하는 스칼라 값입니다.

0.0은 비금속 성질을 의미하며, 1.0에 가까울수록 금속 표면 특유의 반사 특성이 강하게 적용됩니다.

이 값은 PBR 기반 렌더링에서 소재의 시각적 성격을 결정하는 핵심 요소로 활용됩니다.

#### Code Samples

### MetalnessMap

`Content`

표면의 어느 부분이 금속 성질을 갖는지를 지정하는 회색조 텍스처입니다.

검정에 가까울수록 비금속, 흰색에 가까울수록 금속으로 처리되며, 중간 톤은 금속 표면의 오염·마모 같은 변형 표현에 사용됩니다.

#### Code Samples

### MetersPerTile

`number`

텍스처가 표면에 얼마나 크게 매핑될지를 지정하는 속성입니다.

값을 높이면 텍스처가 확대되어 반복 빈도가 줄어들고, 값을 낮추면 텍스처가 더 촘촘하게 표시되며 반복 횟수가 늘어납니다.

#### Code Samples

### NormalMap

`Content`

표면의 실제 지오메트리를 변경하지 않고, 조명 반응을 조정해 미세한 요철·패턴·굴곡을 표현하는 텍스처입니다.

RGB 채널은 표면 노멀 방향을 나타내며, 잘못된 채널 구성은 돌출·오목 효과가 반대로 보일 수 있습니다. NormalMap 효과가 나타나지 않는 경우 메시가 tangent 정보를 포함하고 있는지 확인해야 합니다.

#### Code Samples

### Roughness

`number`

표면이 얼마나 거칠게 빛을 퍼뜨리는지를 정의하는 스칼라 값입니다.

0.0일 경우 매끄러운 표면으로 간주되어 반사가 선명하고 강하게 나타나며, 1.0에 가까울수록 거친 표면으로 처리되어 빛이 넓게 확산됩니다.

이 값은 PBR 기반 렌더링에서 반사 품질과 표면 질감을 결정하는 중요한 요소로 사용됩니다.

#### Code Samples

### RoughnessMap

`Content`

표면이 미세한 스케일에서 얼마나 매끄럽거나 거칠게 보이는지를 정의하는 회색조 텍스처입니다.

어두운 값일수록 반사가 선명하게 나타나는 매끄러운 표면을 의미하며, 밝은 값일수록 빛이 넓게 퍼져 흐릿하게 반사되는 거친 표면을 나타냅니다.

#### Code Samples

### UseCustomPhysicsProperties

`boolean`

현재 지원되지 않습니다.

#### Code Samples

## Methods

## Events

## See also

{% content-ref url="/pages/jCNdUlp5Hl1wzQFnSMEz" %}
[Material Manager](/korean/manual/studio-manual/game-development/material-manager.md)
{% endcontent-ref %}


---

# Agent Instructions: 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:

```
GET https://docs.overdare.com/korean/development/api-reference/classes/materialvariant.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.