> 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 图形的重要组成部分。它们用于照亮场景、营造景深和真实感，也可以用来创造不同的情绪和氛围。

默认情况下，场景由单个定向光照亮。定向光会沿特定方向照射，用于模拟太阳或月亮。有关详细信息，请参阅 [天空盒控制](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/skybox-control.md) 。

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

支持以下两种灯光类型：

* 点光源：从特定点向各个方向照射的灯光。
* 聚光灯：沿特定方向照射、仅覆盖锥形区域的灯光。

{% hint style="warning" %}
**📔 注意**：Decentraland 会忽略嵌入在 `.glb` 或 `.gltf` 文件中的灯光。如果 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-zh/chang-jing-sdk7/jiao-hu-xing/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 `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` 对象；如果未指定，颜色默认为白色。你可以将其设为任意颜色，这会显著影响场景的氛围。

强度以坎德拉为单位（距离 1 米处的流明/平方米，或流明除以 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
	}
)
```

## 灯光优化

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

场景中允许启用的灯光数量上限为每块地块一盏，除此之外，具体数量取决于用户选择的画质设置。

* 低画质：不启用任何场景灯光
* 中画质：最多 6 盏灯光（场景中的地块数量足够时）
* 高画质：最多 10 盏灯光（场景中的地块数量足够时）
* 移动设备：应用使用自己的预设，场景灯光数量从“极低”画质下的 0 盏到“高”画质下的 8 盏不等。请参阅 [移动设备上的灯光和粒子](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/optimize-performance.md#lights-and-particles).

画质设置滑块还可以进一步降低预设的上限。

如果灯光数量超过上限，引擎会根据灯光源与玩家之间的距离自动禁用灯光。玩家移动时，引擎会重新启用距离足够近的灯光。

{% hint style="warning" %}
**📔 注意**：在“低”画质预设下，场景灯光会完全关闭。即使 `LightSource` 组件配置正确，也不会产生任何效果；无论如何调整强度、范围或材质，都无法改变这一点。如果灯光“没有效果”，首先检查画质设置。应将“中”画质视为场景能够支持的最低设置，而不是要求玩家使用“高”画质。

发光的自发光材质并不能证明灯光正常工作。发光的灯具网格与它投射到附近表面的光是两件不同的事，需要分别检查。
{% endhint %}

由于部分玩家完全看不到场景灯光（桌面端“低”画质、移动端“极低”画质），请确保场景在没有灯光的情况下仍能正常使用。玩家需要看到的内容，例如前进路线或可交互物体，应通过自发光材质、纹理或天空盒突出显示。将 `LightSource` 作为辅助，而不要把它当作唯一提示。阴影也是如此：不要让玩家只能通过阴影来判断物体的位置。

无论哪种情况，引擎最多只会为 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-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://2460066822-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-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 %}

## 黑暗中的灯光

天空不与灯光争辉时，灯光最容易展现其效果。 `Skybox`, `Sun` 和 `EnvironmentFog` 组件可以将阳光、天空颜色（以及随之而来的环境光）、雾、云和星星全部变暗，让灯光成为唯一的照明来源。请参阅 [完全黑暗](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/skybox-control.md#complete-darkness).

在低画质预设下，场景灯光不会渲染，因此对这些玩家而言，完全黑暗的场景会呈现为一片漆黑。使用自发光材质，确保重要内容仍然可见。移动应用和 Bevy Explorer 暂不支持这些组件，因此使用这些客户端的玩家仍会看到常规天空。


---

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