> 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-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/lights.md).

# 灯光

了解如何在你的场景中使用灯光

灯光是 3D 图形的基础组成部分。它们用于照亮场景并营造深度和真实感，还可用于创造不同的情绪和氛围。

默认情况下，场景使用一个单向光照明。这是一种沿特定方向照射的光，用于模拟太阳或月亮。请参见 [天空盒控制](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/skybox-control.md) 了解更多信息。

你可以在场景中每个地块最多添加 1 个光源。

支持两种光源类型：

* 点光源：从某个特定点向四面八方照射的光。
* 聚光灯：朝特定方向照射、并只覆盖锥形区域的光。

{% hint style="warning" %}
**📔 注意**：嵌入在一个 `.glb` 或 `.gltf` 文件中的灯光会被 Decentraland 忽略。如果你的 3D 模型导出时包含灯光，它们不会照亮场景中的任何东西。唯一有效的光源是具有 `LightSource` 组件的实体。如果你想让灯具模型发光，请向 `LightSource` 同一个实体添加一个，或添加到位于灯泡位置的子实体。
{% endhint %}

{% hint style="info" %}
**💡 提示**：Creator Hub 资源目录中提供了现成的 **聚光灯** 和 **点光源** 智能物件，位于 **lights** 类别中。每个都捆绑了一个模型、一个已配置的 `LightSource`LightSource **聚光灯** 下的 **装饰性**，它只是一个模型，不会发出任何光。请从 **lights** 类别中选择，当你需要真正的照明时。
{% 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-zh/chang-jing-sdk7/jiao-hu-xing/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` 是外锥角度，在这个角度外灯光会向锥体边缘逐渐淡出。你可以调整这些值来创建不同效果，让灯光更聚焦或更柔和。

## 强度和颜色

所有灯光，无论点光源还是聚光灯，都有颜色和强度。颜色由 `颜色` 属性从 `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` 对象，如果未指定则默认为白色。你可以将其设置为任何你想要的颜色，这会对场景氛围产生很大影响。

强度以坎德拉表示（1 米距离处的流明/平方米，或流明除以 4\*pi）。

默认强度为 16000，这相当于现实世界中普通灯泡的亮度，并且在距离光源约 10 米内都能看见。如果你需要让灯光在更远处或白天可见，可以提高强度。

灯光可见的距离是强度值的四次方根（`intensity^0.25`).

* 当强度为 625 时，灯光可见范围约为 5 米。
* 当强度为 10000 时，灯光可见范围约为 10 米。
* 当强度为 160000 时，灯光可见范围约为 20 米。

## 阴影

每个灯光都可以选择是否投射阴影。默认情况下不会，但你可以通过设置 `shadow` 属性从 `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
})
```

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

## 光源优化

光源会对场景性能产生相当大的影响。因此，引擎会自动优化场景，禁用部分灯光或其阴影，并优先从距离更远的灯光开始处理。

场景中允许启用的灯光数量上限为每个地块 1 个，超过此数量后则取决于用户选择的画质设置。

* 低画质：最多 4 盏灯（在地块数量足够的场景中）
* 中画质：最多 6 盏灯（在地块数量足够的场景中）
* 高画质：最多 10 盏灯（在地块数量足够的场景中）

如果灯光数量超过允许上限，引擎会根据光源与玩家的距离自动禁用部分灯光。随着玩家移动，引擎会重新启用距离玩家足够近的灯光。

在任何情况下，引擎最多只会为 3 个光源渲染阴影。如果带阴影的灯光超过 3 个，引擎会自动为其余更远的灯光禁用阴影。

除了允许的最大灯光数量外，阴影也取决于与玩家的距离。具体距离会因光源类型和玩家的画质设置而异，但一般来说：

* 距离小于 10 米：阴影以柔和阴影渲染（高画质）
* 距离在 10 到 20 米之间：阴影以硬阴影渲染（低画质）
* 距离超过 20 米：不渲染阴影

光源本身会在更远的距离继续照亮场景：只有当玩家距离超过 160 米（10 个地块）时，它们才会被禁用。这使得灯光适合用于大型布置，例如现场活动中的舞台照明，因为大多数观众都离光源很远。

还要注意，只有当玩家站在场景内部时，灯光才会被渲染。如果玩家在场景外，灯光将不会被渲染。

## 灯光范围

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://2460066822-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://2460066822-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-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/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-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/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.