> 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 그래픽의 기본적인 요소입니다. 장면을 비추고 깊이감과 사실감을 만들어내는 데 사용되며, 다양한 분위기와 무드를 연출하는 데도 활용됩니다.

기본적으로 장면에는 단일 방향광이 비춰집니다. 이는 특정 방향으로 비추는 조명으로, 태양이나 달을 시뮬레이션하는 데 사용됩니다. 자세한 내용은 [Skybox 제어](/creator/content-creator-ko/sdk7/interactivity/skybox-control.md) 에서 확인하세요.

장면의 각 parcel에는 최대 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" %}
**📔 참고**: 기본 밝기의 조명은 현실 세계처럼 한낮의 태양 아래에서는 거의 보이지 않습니다.  [Skybox 제어](/creator/content-creator-ko/sdk7/interactivity/skybox-control.md) Skybox를 밤으로 강제하거나,  `intensity` 의 속성을 `LightSource`  컴포넌트 값을 더 높게 설정하여 밝기를 높일 수 있습니다.
{% endhint %}

## 스폿 조명

스폿 조명은 특정 방향으로 비추며 특정 원뿔 모양 영역을 덮는 조명입니다. 조명의 방향은 엔티티의 Transform 컴포넌트에 의해 정의됩니다. 원뿔의 개구각은 `innerAngle` 그리고 `outerAngle` 의 속성으로 정의됩니다. `LightSource` 구성 요소.

```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` 객체이며, 지정하지 않으면 흰색이 됩니다. 원하는 색상으로 설정할 수 있으며, 이는 장면의 분위기에 큰 영향을 줄 수 있습니다.

강도는 칸델 단위로 표시됩니다(1m 거리에서의 루멘/m^2, 또는 루멘을 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: 'Click',
		},
	},
	function () {
		const lightSource = LightSource.getMutable(light)
		lightSource.active = !lightSource.active
	}
)
```

## 조명 최적화

광원은 장면 성능에 상당한 영향을 줄 수 있습니다. 이 때문에 엔진은 거리가 먼 조명부터 자동으로 일부 조명이나 그 그림자를 비활성화하여 장면을 최적화합니다.

장면에서 활성화할 수 있는 조명 수는 parcel당 1개로 제한되며, 그 이후에는 사용자가 선택한 품질 설정에 따라 달라집니다.

* 낮은 품질: 장면 조명 없음
* 중간 품질: 최대 6개 조명(parcel이 충분한 장면에서)
* 높은 품질: 최대 10개 조명(parcel이 충분한 장면에서)

품질 설정 슬라이더는 프리셋의 상한을 더 낮출 수도 있습니다.

허용된 수보다 조명이 많으면 엔진은 광원이 플레이어와 얼마나 가까운지에 따라 자동으로 조명을 비활성화합니다. 플레이어가 이동하면 엔진은 플레이어에게 충분히 가까운 조명을 다시 활성화합니다.

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

빛나는 발광 재질이 있다고 해서 조명이 작동한다는 증거는 아닙니다. 빛나는 램프 메시와 주변 표면에 비치는 빛은 각각 따로 확인해야 할 두 가지입니다.
{% endhint %}

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

허용된 최대 조명 수 외에도 그림자는 플레이어와의 거리에도 영향을 받습니다. 정확한 거리는 조명 유형과 플레이어의 품질 설정에 따라 달라지지만, 일반적으로는 다음과 같습니다:

* 10미터 미만: 그림자는 부드러운 그림자(고품질)로 렌더링됩니다
* 10미터에서 20미터 사이: 그림자는 단단한 그림자(저품질)로 렌더링됩니다
* 20미터 이상: 그림자가 렌더링되지 않습니다

광원 자체는 훨씬 더 먼 거리에서도 장면을 계속 비춥니다. 플레이어가 160미터(10 parcel) 이상 떨어져 있을 때만 비활성화됩니다. 따라서 조명은 대부분의 관객이 광원에서 멀리 떨어져 있는 라이브 이벤트의 무대 조명 같은 대규모 연출에 적합합니다.

또한 플레이어가 장면 내부에 서 있을 때만 조명이 렌더링된다는 점도 중요합니다. 플레이어가 장면 밖에 있으면 조명은 렌더링되지 않습니다.

## 조명 범위

lightSource 컴포넌트에는 `range`  속성이 있어 조명이 보이는 최대 거리를 설정할 수 있습니다. 기본적으로 `range` 속성 값은 -1이며, 이는 조명 범위가 조명 강도에 따라 결정된다는 뜻입니다.

범위는 강도 값의 네제곱근으로 계산됩니다(`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-1c5642751dfc0b0047732fbbb86e611b492e392f%2Flightmask1.png?alt=media\&token=18ce6d0f-109b-420f-9402-1cbe85f5d123)

흑백 이미지를 사용하면 조명이 해당 영역에 닿거나 그렇지 않거나 둘 중 하나입니다. 색상이 있는 이미지를 사용할 수도 있으며, 이 색상은 각 영역의 조명에 색조를 입혀 표면에 컬러 로고나 이미지를 투사하는 데 사용할 수 있습니다.

{% 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-b68fe34eaab8dbaec996c3dca754e4742076f523%2Fpoint-light-mask1.png?alt=media\&token=d8d5037c-0d0e-4098-a45d-3b944f579b6a)

{% hint style="info" %}
**💡 팁**: 조명을 [입자 시스템](/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 %}


---

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