> 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) 자세한 정보는

장면의 각 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" %}
**📔 참고**: 기본 밝기의 조명은 정오의 태양 아래에서는 현실 세계처럼 거의 보이지 않습니다.  [스카이박스 제어](/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` 객체입니다. 지정하지 않으면 흰색이 됩니다. 원하는 어떤 색이든 설정할 수 있으며, 이는 장면의 분위기에 큰 영향을 줄 수 있습니다.

광도는 칸델라(candela)로 표시됩니다(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: '클릭',
		},
	},
	function () {
		const lightSource = LightSource.getMutable(light)
		lightSource.active = !lightSource.active
	}
)
```

## 조명 최적화

광원은 장면 성능에 꽤 큰 영향을 줄 수 있습니다. 이런 이유로 엔진은 더 멀리 있는 조명부터 일부 조명이나 그 그림자를 자동으로 비활성화하여 장면을 최적화합니다.

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

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

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

어떤 경우에도 엔진은 최대 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)

흑백 이미지를 사용하면 빛은 해당 영역에 닿거나 닿지 않거나 둘 중 하나입니다. 색상이 있는 이미지를 전달하는 것도 가능하며, 이 색상들이 각 영역에서 조명의 색조를 입혀줍니다. 이는 표면에 색이 있는 로고나 이미지를 투사하는 데 사용할 수 있습니다.

{% 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)

{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/lights.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.