> 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 그래픽의 기본적인 요소입니다. 장면을 비추고 깊이감과 사실감을 만들어 주며, 다양한 분위기와 감성을 연출하는 데 사용할 수 있습니다.

기본적으로 장면은 하나의 방향성 조명으로 비춰집니다. 이는 특정 방향으로 비추는 조명으로, 태양이나 달을 시뮬레이션하는 데 사용됩니다. 자세한 내용은 [스카이박스 제어](/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" %}
**📔 참고**기본 밝기의 조명은 한낮의 태양 아래에서는 현실 세계처럼 거의 보이지 않습니다. 다음을 사용하여 [스카이박스 제어](/creator/content-creator-ko/sdk7/interactivity/skybox-control.md) 하늘 상자를 밤 시간대로 강제로 바꾸거나, `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 거리에서의 루멘/㎡, 또는 루멘을 4\*pi로 나눈 값).

기본 강도는 16000이며, 이는 현실 세계의 평균적인 전구 밝기와 같고 조명 원천에서 약 10미터 거리까지 볼 수 있습니다. 더 먼 거리나 낮에도 조명이 보이게 하려면 강도를 높일 수 있습니다.

조명이 보이는 거리는 강도 값의 4제곱근으로 계산됩니다(`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
	}
)
```

## 조명 최적화

조명 원천은 장면 성능에 상당히 큰 영향을 줄 수 있습니다. 이 때문에 엔진은 더 먼 것부터 시작하여 일부 조명이나 그 그림자를 자동으로 비활성화해 장면을 최적화합니다.

장면에서 허용되는 활성 조명 수는 파셀당 1개로 제한되며, 그 이상은 사용자가 선택한 품질 설정에 따라 달라집니다.

* 낮음 품질: 최대 4개 조명(파셀 수가 충분한 장면에서)
* 보통 품질: 최대 6개 조명(파셀 수가 충분한 장면에서)
* 높음 품질: 최대 10개 조명(파셀 수가 충분한 장면에서)

허용 수보다 더 많은 조명이 있으면 엔진은 조명 원천과 플레이어의 근접도를 기준으로 자동으로 조명을 비활성화합니다. 플레이어가 이동하면 엔진은 플레이어와 충분히 가까운 조명을 다시 활성화합니다.

모든 경우에 엔진은 최대 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-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.