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

# 조명

씬에서 조명을 사용하는 방법을 알아봅니다

조명은 3D 그래픽의 기본 요소입니다. 장면을 밝히고 깊이감과 현실감을 더하는 데 사용되며, 다양한 분위기와 느낌을 연출할 수도 있습니다.

기본적으로 장면은 단일 방향성 조명으로 비춰집니다. 특정 방향으로 빛을 비추는 조명으로, 태양이나 달을 표현하는 데 사용됩니다. 자세한 내용은 [스카이박스 제어](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/skybox-control.md) 를 참조하세요.

장면의 파셀마다 조명을 최대 1개까지 추가할 수 있습니다.

지원되는 조명 유형은 다음과 같습니다.

* 점 조명: 특정 지점에서 모든 방향으로 빛을 비추는 조명입니다.
* 스포트 조명: 특정 방향으로 빛을 비추며 원뿔 모양 영역만 밝히는 조명입니다.

{% hint style="warning" %}
**📔 참고**:  `.glb` 또는 `.gltf`  파일에 포함된 조명은 Decentraland에서 무시됩니다. 3D 모델을 조명이 포함된 상태로 내보냈더라도 장면을 밝히지 않습니다. 유효한 조명 소스는  `LightSource`  컴포넌트가 있는 엔터티뿐입니다. 램프 모델에서 빛을 비추려면 같은 엔터티에  `LightSource` 를 추가하거나 전구가 있는 위치에 배치한 자식 엔터티에 추가하세요.
{% endhint %}

{% hint style="info" %}
**💡 팁**: Creator Hub 에셋 카탈로그에는 바로 사용할 수 있는 **스포트라이트** 및 **점 조명** 스마트 아이템이  **조명**  카테고리에 있습니다. 각 아이템에는 모델, 설정된  `LightSource`와 켜기, 끄기, 전환 동작이 포함되어 있어 코드를 작성할 필요가 없습니다. 또한  **스포트라이트** 장식 **장식** 카테고리에는 빛을 비추지 않는 모델만 있습니다. 실제 조명이 필요하면  **조명**  카테고리에서 선택하세요.
{% endhint %}

## 조명 추가

장면에 조명을 추가하려면 조명 엔터티를 만들고 여기에  `LightSource`  컴포넌트를 추가해야 합니다.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
  type: LightSource.Type.Point({})
})
```

{% hint style="warning" %}
**📔 참고**: 현실 세계와 마찬가지로 기본 밝기의 조명은 한낮의 태양 아래에서 거의 보이지 않습니다.  [스카이박스 제어](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/skybox-control.md) 를 사용해 스카이박스를 야간으로 설정하거나  `intensity`  속성을  `LightSource`  컴포넌트에서 더 높은 값으로 설정해 밝기를 높일 수 있습니다.
{% endhint %}

## 스포트 조명

스폿 조명은 특정 방향으로 빛을 비추고, 원뿔 모양의 특정 영역을 밝히는 조명입니다. 빛의 방향은 엔터티의 Transform 컴포넌트로 정의됩니다. 즉, 빛은 엔터티의 정방향(로컬 +Z축)을 따라 비춥니다. 원뿔의 개구각은 다음 속성으로 정의됩니다. `innerAngle` 와 `outerAngle` 의 `LightSource` 컴포넌트 속성입니다.

아래 예시에서는 엔터티를 X축을 중심으로 90도 회전시켜 조명이 바로 아래를 향하도록 합니다. -90도로 회전하면 하늘을 향합니다.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
  rotation: Quaternion.fromEulerDegrees(90, 0, 0),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true
})
```

은 `innerAngle` 는 빛이 최대 밝기로 비치는 내부 원뿔의 각도이고, `outerAngle` 는 빛이 원뿔 가장자리로 갈수록 서서히 어두워지는 외부 원뿔의 각도입니다. 이 값을 조정해 빛을 더 집중시키거나 더 넓게 퍼뜨리는 등 다양한 효과를 만들 수 있습니다.

## 강도와 색상

점광원과 스포트라이트를 비롯한 모든 조명에는 색상과 강도가 있습니다. 색상은 다음과 같이 정의합니다. `color` 의 속성 `LightSource`  구성 요소이며, 강도는 다음 속성으로 정의됩니다. `intensity`  속성입니다.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
  type: LightSource.Type.Point({}),
  color: Color3.Red(),
  intensity: 10000,
})
```

색상은 `Color3` 객체입니다. 지정하지 않으면 흰색으로 설정됩니다. 원하는 색상을 지정할 수 있으며, 색상은 장면의 분위기에 큰 영향을 줄 수 있습니다.

강도는 칸델라(lm/m^2, 광원에서 1m 떨어진 지점 기준, 또는 루멘을 4\*pi로 나눈 값)로 표시됩니다.

기본 강도는 16000입니다. 이는 현실에서 평균적인 전구의 밝기에 해당하며, 광원에서 약 10미터 떨어진 곳까지 빛이 보입니다. 더 먼 거리에서 또는 낮에도 빛이 보이게 하려면 강도를 높이면 됩니다.

빛이 보이는 거리는 강도 값의 네제곱근입니다(`intensity^0.25`).

* 강도가 625이면 빛은 약 5미터 떨어진 곳까지 보입니다.
* 강도가 10000이면 빛은 약 10미터 떨어진 곳까지 보입니다.
* 강도가 160000이면 빛은 약 20미터 떨어진 곳까지 보입니다.

## 그림자

각 조명은 그림자를 드리울 수도 있고 드리우지 않을 수도 있습니다. 기본적으로 그림자를 드리우지 않지만, 다음을 설정하면 그림자를 활성화할 수 있습니다. `shadow` 속성을 `LightSource` 컴포넌트에서 `true`.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
  rotation: Quaternion.fromEulerDegrees(90, 0, 0),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true
})
```

{% hint style="warning" %}
**📔 참고**: 그림자는 스포트 조명만 지원합니다. 점 조명은 그림자를 지원하지 않습니다. 장면에 조명이 여러 개 있는 경우 일부 조명은 그림자를 드리우지 않을 수 있습니다. 자세한 내용은 [조명 최적화](#light-optimization) 를 참조하세요.
{% endhint %}

## 조명 켜고 끄기

LightSource 컴포넌트에는 `active` 속성이 있으며, 이 속성으로 조명을 켜고 끌 수 있습니다. 씬에서 조명을 제거하지 않고 끄거나, 원래 강도 값을 잃지 않으면서 `intensity` 를 0으로 설정하지 않고 조명을 끄고 싶을 때 유용합니다.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
  rotation: Quaternion.fromEulerDegrees(90, 0, 0),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true,
	active: true
})

const lightSwitch = engine.addEntity()

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

MeshRenderer.setBox(lightSwitch)

MeshCollider.setBox(lightSwitch)

pointerEventsSystem.onPointerDown(
	{
		entity: lightSwitch,
		opts: {
			button: InputAction.IA_POINTER,
			hoverText: '클릭',
		},
	},
	function () {
		const lightSource = LightSource.getMutable(light)
		lightSource.active = !lightSource.active
	}
)
```

## 조명 최적화

조명은 씬 성능에 큰 영향을 줄 수 있습니다. 따라서 엔진은 더 멀리 있는 조명부터 일부 조명이나 그림자를 비활성화해 씬을 자동으로 최적화합니다.

씬에서 활성화할 수 있는 조명 수는 구획당 하나로 제한되며, 이보다 많은 조명을 사용할 수 있는지는 사용자가 선택한 품질 설정에 따라 달라집니다.

* 낮은 품질: 씬 조명 없음
* 보통 품질: 조명 최대 6개(구획이 충분한 씬 기준)
* 높은 품질: 조명 최대 10개(구획이 충분한 씬 기준)
* 모바일: 앱 자체 프리셋을 사용하며, 매우 낮음에서는 씬 조명이 없고 높음에서는 최대 8개까지 사용할 수 있습니다. 자세한 내용은 [모바일의 조명과 파티클](https://docs.decentraland.org/creator/content-creator-ko/build-for-mobile/develop/optimize-performance.md#lights-and-particles).

품질 설정 슬라이더를 사용하면 프리셋의 상한을 더 낮출 수 있습니다.

허용된 수보다 조명이 많으면 엔진은 조명과 플레이어 사이의 거리를 기준으로 조명을 자동으로 비활성화합니다. 플레이어가 이동하면 엔진은 플레이어와 충분히 가까운 조명을 다시 활성화합니다.

{% hint style="warning" %}
**📔 참고**: 낮은 품질 프리셋에서는 씬 조명이 완전히 꺼집니다. 올바르게 구성된 `LightSource` 도 아무것도 표시하지 않으며, 강도나 범위를 아무리 조정하거나 머티리얼을 튜닝해도 달라지지 않습니다. 조명이 작동하지 않는 것 같다면 무엇보다 먼저 품질 설정을 확인하세요. 높은 품질이 아니라 보통 품질을 씬에서 지원하는 최저 설정으로 간주하세요.

발광하는 머티리얼이 있다고 해서 조명이 작동한다는 뜻은 아닙니다. 빛나는 램프 메시와 주변 표면에 비치는 빛은 별개의 요소이므로 각각 확인해야 합니다.
{% endhint %}

일부 플레이어는 씬 조명을 전혀 볼 수 없으므로(데스크톱의 낮은 품질, 모바일의 매우 낮음), 조명이 없어도 씬이 제대로 작동하도록 해야 합니다. 앞으로 가는 길이나 상호작용할 수 있는 물체처럼 플레이어가 보아야 하는 요소는 발광 머티리얼, 텍스처 또는 스카이박스로 눈에 띄게 표현하세요. `LightSource` 는 보조 수단으로 사용하고 유일한 시각적 단서로 삼지 마세요. 그림자도 마찬가지입니다. 물체의 위치를 파악하는 유일한 방법이 그림자여서는 안 됩니다.

어떤 경우든 엔진은 최대 3개의 광원에 대해서만 그림자를 렌더링합니다. 그림자가 있는 조명이 3개를 초과하면 엔진은 더 멀리 있는 나머지 조명의 그림자를 자동으로 비활성화합니다.

허용되는 조명 수 외에도 그림자 렌더링 여부는 플레이어와의 거리에 따라 달라집니다. 정확한 거리는 조명 유형과 플레이어의 품질 설정에 따라 다르지만, 일반적으로 다음과 같습니다.

* 10미터 미만: 부드러운 그림자로 렌더링(높은 품질)
* 10\~20미터: 뚜렷한 그림자로 렌더링(낮은 품질)
* 20미터 초과: 그림자를 렌더링하지 않음

광원 자체는 훨씬 더 먼 거리에서도 씬을 비춥니다. 플레이어가 광원에서 160미터(구획 10개) 넘게 떨어져 있을 때만 비활성화됩니다. 따라서 대부분의 관객이 광원에서 멀리 떨어져 있는 라이브 이벤트의 무대 조명처럼 넓은 공간을 사용하는 설정에도 조명을 적합하게 사용할 수 있습니다.

또한 조명은 플레이어가 씬 안에 있을 때만 렌더링된다는 점에 유의해야 합니다. 플레이어가 씬 밖에 있으면 조명은 렌더링되지 않습니다.

## 조명 범위

LightSource 컴포넌트에는 `range` 속성이 있으며, 이 속성을 사용해 조명이 보이는 최대 거리를 설정할 수 있습니다. 기본적으로 `range` 속성 값은 -1이며, 이는 조명 범위가 조명의 강도에 따라 달라짐을 의미합니다.

범위는 강도 값의 4제곱근으로 계산됩니다(`intensity^0.25`).

* 강도가 16000일 때 범위는 약 11미터입니다.
* 강도가 160000일 때 범위는 약 20미터입니다.
* 강도가 1600000일 때 범위는 약 36미터입니다.

기본 설정에서는 감쇠 곡선이 부드럽고 자연스럽게 보입니다. 하지만 조명의 범위를 제한하려면 `range` 속성을 양수로 설정하면 됩니다.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
  type: LightSource.Type.Point({}),
  intensity: 16000,
  range: 20,
})
```

{% hint style="warning" %}
**📔 참고**: `range` 속성을 양수로 설정하면 지정된 거리에서 조명이 갑자기 끊깁니다. 특정 영역에서만 조명이 보이게 하거나 장면의 성능을 최적화하려는 경우 유용합니다.  `range` 현재 강도로 조명이 실제로 도달할 수 있는 범위보다 큰 값으로 설정해도 효과가 없습니다.
{% endhint %}

## 조명 마스크

조명 마스크를 사용해 흥미로운 효과를 만들 수 있습니다. 전체 영역을 비추는 대신 텍스처를 필터로 적용하여 영역의 일부만 비출 수 있습니다.

마스크는 보통 스포트 조명에 사용하지만 점 조명에도 사용할 수 있습니다. 아래는 마스크를 적용한 스포트 조명의 예입니다.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true,
	shadowMaskTexture: Material.Texture.Common({src: "assets/scene/images/lightmask1.png"})
})
```

예를 들어 아래 이미지를 적용하면 텍스처가 흰색인 영역에서만 조명이 보이는 재미있는 효과를 만들 수 있습니다. 모든 색상과 강도의 조명에 사용할 수 있습니다.

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

흑백 이미지를 사용하면 영역을 비추거나 비추지 않는 두 가지 상태로 표현됩니다. 색상이 있는 이미지도 사용할 수 있으며, 각 영역에서 해당 색상이 조명에 입혀집니다. 이를 이용해 표면에 컬러 로고나 이미지를 투사할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 마스크로 사용하는 이미지의 픽셀 높이와 너비는 2의 거듭제곱이어야 합니다(예: 1024, 512, 256). 크기가 다른 이미지는 이 기능에서 작동하지 않습니다.
{% endhint %}

점 조명에 마스크를 적용하면 텍스처가 조명 주변의 큐브에 둘러싸이듯 매핑됩니다. 큐브 면 사이의 경계가 보이지 않게 하려면 텍스처 가장자리가 서로 이어지도록 하세요.

```ts
import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
	type: LightSource.Type.Point({}),
	shadowMaskTexture: Material.Texture.Common({src: "assets/scene/images/point-light-mask1.png"})
})
```

예를 들어 아래 이미지는 큐브의 각 면에 문자를 하나씩 표시합니다(Y는 위쪽, -Y는 아래쪽, X는 오른쪽, -X는 왼쪽, Z는 앞쪽, -Z는 뒤쪽).

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

{% hint style="info" %}
**💡 팁**: 조명을 다음과 결합해 [파티클 시스템](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/particle-system.md) 더 풍부한 시각 효과를 만들어 보세요. 예를 들어 가산 블렌딩을 사용하는 불꽃 파티클 시스템을 따뜻한 점 조명과 함께 사용하면 그럴듯한 모닥불을 연출할 수 있습니다.
{% endhint %}

{% hint style="info" %}
**💡 팁**: 이 구성 요소의 작동 예시는 다음 테스트 장면을 참조하세요. [`0,4-dynamic-lights`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,4-dynamic-lights) 이 장면에서는 다음 항목을 모두 다룹니다. `LightSource.Type.Point` 및 `LightSource.Type.Spot`, 다음을 통한 런타임 변경 `LightSource.getMutable()`, 그림자 및 `shadowMaskTexture`.
{% endhint %}

## 어두운 곳의 조명

하늘의 빛이 조명과 경쟁하지 않을 때 조명을 가장 잘 감상할 수 있습니다.  `Skybox`, `Sun` 및 `EnvironmentFog` 구성 요소를 사용하면 햇빛, 하늘색(그리고 이에 따른 주변광), 안개, 구름, 별을 모두 검게 만들어 조명만이 유일한 광원이 되게 할 수 있습니다.  [완전한 어둠](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/skybox-control.md#complete-darkness).

낮음 품질 프리셋에서는 장면 조명이 전혀 렌더링되지 않으므로, 완전히 어두운 장면은 해당 플레이어에게 온통 검게 보입니다. 필수 요소가 계속 보이도록 발광 재질을 사용하세요. 모바일 앱과 Bevy 탐색기는 아직 이 구성 요소를 지원하지 않으므로, 해당 클라이언트의 플레이어에게는 일반적인 하늘이 계속 보입니다.


---

# 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/lights.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.
