LightingService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [LightingService]（8 属性）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

光照服务统一管理场景的整体光照表现，可以调整环境光的颜色与强度、主光源的颜色与强度及其朝向，还能开启电影色调映射、控制阴影淡化程度并指定反射立方体贴图。通过修改这些属性，可以在运行过程中平滑地改变画面氛围，例如从明亮的白昼光照过渡到偏暖的黄昏色调。

适用场景

常用于关卡或演出脚本中动态切换光照氛围：先通过 game:GetService("LightingService") 取得服务，再调整 Orientation 改变主光源角度，配合 ShadowFade 与 FilmicTonemapEnabled 调整阴影与色调表现。

使用要点

使用 game:GetService("LightingService") 获取服务实例，之后直接对属性赋值即可生效：AmbientColor 与 Color 需要用 Color.New(r, g, b, a) 构造，Orientation 需要用 Vector3.New(x, y, z) 传入角度制欧拉角，AmbientIntensity、Intensity、ShadowFade 写入数值，FilmicTonemapEnabled 写入布尔值。若要分阶段改变视觉效果，可以在两次赋值之间用 Task:Wait(秒数) 控制节奏，EnvironmentMap 则接收字符串形式的反射贴图资源标识。

注意事项

LightingService 的颜色属性（AmbientColor/Color）类型为 Color（RGBA，0-255 范围），必须用 Color.New(r, g, b, a) 构造，不能用 Color3.New(r, g, b)（Color3 是 RGB 0-1 范围的另一种类型）。例如暖黄色环境光应写 Color.New(255, 229, 178, 255)，不是 Color3.New(1.0, 0.9, 0.7)。Orientation 属性类型为 Vector3（欧拉角，角度制），必须用 Vector3.New(x, y, z) 赋值，不能用 CFrame。

代码示例

设置环境光与主光颜色（Color 类型）

-- @runtime client
local LightingService = game:GetService('LightingService')
-- Color.New(r, g, b, a) 用 0-255 RGBA 范围
LightingService.AmbientColor = Color.New(255, 229, 178, 255)  -- 暖黄色环境光
LightingService.Color = Color.New(255, 255, 255, 255)  -- 白色主光

调整光源方向与阴影淡出

-- @runtime client
local LightingService = game:GetService('LightingService')
-- Orientation 是 Vector3 类型（欧拉角，角度制），不是 CFrame
LightingService.Orientation = Vector3.New(45, -30, 0)  -- 东南方向斜射
LightingService.ShadowFade = 0.5  -- 真实运行示例使用 0.0、0.5、1.0 调节淡化程度

属性 (8)

Name	类型	默认值	说明
AmbientColor	Color	Color.New(104, 104, 104, 255)	环境光颜色，影响场景中非直接光照区域的亮度和色调。
AmbientIntensity	Float	1.0	环境光强度，控制环境光对场景的照亮程度。
Color	Color	Color.New(225, 225, 225, 255)	主光源颜色，决定场景中直接光照的颜色。
Intensity	Float	2.0	主光源强度，控制主方向光的亮度。
Orientation	Vector3	[45, -45, 0]	主光源朝向，类型为 Vector3，用于表示光照服务中主光源的旋转方向。该属性可读取也可修改，公开契约给出的默认值为 (45, -45, 0)。
FilmicTonemapEnabled	Bool	false	是否启用电影色调映射，开启后可获得更具电影感的画面效果。
ShadowFade	Float	0.0	阴影淡化系数，控制阴影随距离淡出的程度。
EnvironmentMap	String	official://cube/28	LightingService 的 EnvironmentMap 属性，类型为字符串，用于指定环境反射所采用的立方体贴图资源标识。该属性可通过 LightingService 服务实例直接读写。

关联类型

• Unit
• Color
• Vector3