Cocos 组件 / 灯光 / Light节点

学习目标

访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。

覆盖范围

• 节点数量：13
• 分类路径：Cocos 组件 / 灯光 / Light

典型使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

通用注意事项

• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
• 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。

节点索引

节点	节点 ID	输入/输出	执行方式
读取灯光属性	lightGetProperties	1 / 6	立即继续
获取灯光类型	lightGetType	1 / 1	立即继续
获取灯光颜色	lightGetColor	1 / 1	立即继续
获取烘焙开关	lightGetBaked	1 / 1	立即继续
获取可见性掩码	lightGetVisibility	1 / 1	立即继续
获取色温开关	lightGetUseColorTemperature	1 / 1	立即继续
获取色温值	lightGetColorTemperature	1 / 1	立即继续
批量设置灯光属性	lightSetProperties	7 / 1	立即继续
设置灯光颜色	lightSetColor	3 / 1	立即继续
设置烘焙开关	lightSetBaked	3 / 1	立即继续
设置可见性掩码	lightSetVisibility	3 / 1	立即继续
设置色温开关	lightSetUseColorTemperature	3 / 1	立即继续
设置色温值	lightSetColorTemperature	3 / 1	立即继续

读取灯光属性

一次性读取灯光的全部公共属性：同时获取颜色、色温开关、色温值、烘焙开关、可见性掩码和灯光类型。 适合在场景切换或灯光初始化时批量记录当前灯光状态，或用于调试面板展示。

节点信息

字段	值
节点 ID	lightGetProperties
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
color	颜色	数据	color	灯光颜色	-	可选
useColorTemperature	启用色温	数据	boolean	是否启用色温	-	可选
colorTemperature	色温（K）	数据	number	色温值（K）	-	可选
baked	参与烘焙	数据	boolean	是否参与烘焙	-	可选
visibility	可见性掩码	数据	number	可见性层级掩码	-	可选
type	灯光类型	数据	enum / renderer.scene.LightType	灯光类型（只读枚举）	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取灯光类型

获取灯光类型：判断当前灯光属于哪种类型。只读。 类型在组件初始化时自动确定，不可修改。常见类型：DIRECTIONAL（平行光/日光）、SPHERE（球形光）、SPOT（聚光灯）、POINT（点光源）、RANGED_DIRECTIONAL（范围平行光）。 可用于根据灯光类型执行不同逻辑——例如，只对聚光灯调整角度，对平行光调整朝向。

节点信息

字段	值
节点 ID	lightGetType
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
type	灯光类型	数据	enum / renderer.scene.LightType	灯光类型 只读。DIRECTIONAL=平行光，SPHERE=球形光，SPOT=聚光灯，POINT=点光源，RANGED_DIRECTIONAL=范围平行光。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取灯光颜色

获取灯光颜色：读取灯光的当前主色。 颜色决定了灯光打在物体上呈现的色调——红色光让场景变红，蓝色光让场景变冷。 如果启用了色温（useColorTemperature 为 true），最终颜色 = 主色 × 色温颜色。

节点信息

字段	值
节点 ID	lightGetColor
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
color	颜色	数据	color	灯光颜色 灯光的当前主色。白 = 不改变物体原色。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取烘焙开关

获取烘焙开关：读取灯光是否参与静态光照烘焙。 烘焙开关决定灯光是”预计算”还是”实时”：true → 灯光信息预烘焙到光照贴图，适合固定光源，性能更优；false → 实时动态计算，适合会移动或变化的光源。

节点信息

字段	值
节点 ID	lightGetBaked
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
baked	参与烘焙	数据	boolean	是否参与烘焙 true = 预烘焙（性能好），false = 实时计算。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取可见性掩码

获取灯光可见性掩码：读取灯光影响哪些摄像机层级的位掩码。 该值决定灯光对哪些摄像机可见。只有摄像机的可见掩码与灯光的可见掩码有重叠时，该摄像机才能看到这个灯光的效果。 默认值为 DEFAULT 层（1073741824），表示灯光对默认摄像机可见。

节点信息

字段	值
节点 ID	lightGetVisibility
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
visibility	可见性掩码	数据	number	可见性掩码 控制灯光对哪些摄像机可见。默认 1073741824（DEFAULT 层）。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取色温开关

获取色温开关：读取灯光当前是否启用色温功能。 启用色温后，灯光颜色会叠加暖色或冷色效果：色温值越低越偏暖（橙红），越高越偏冷（蓝白）。 常用于模拟不同时间段的光照——清晨暖光、正午白光、夜晚冷光。

节点信息

字段	值
节点 ID	lightGetUseColorTemperature
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
useColorTemperature	启用色温	数据	boolean	是否启用色温 true = 启用，灯光颜色叠加暖/冷效果。false = 禁用，只使用主颜色。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取色温值

获取灯光色温：读取当前的色温数值（单位：开尔文 K）。 色温控制灯光的冷暖倾向：2700K → 暖黄（烛光、日落），6500K → 正白（正午日光），9000K → 冷蓝（阴天、夜空）。 仅在启用色温开关时生效。

节点信息

字段	值
节点 ID	lightGetColorTemperature
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
colorTemperature	色温（K）	数据	number	色温值（K） 范围 1000～15000K。低=暖，高=冷。需启用色温开关。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

批量设置灯光属性

批量设置灯光属性：同时修改颜色、色温开关、色温值、烘焙开关和可见性掩码。 未连接的属性引脚保持原值不变，只修改你显式连接了的属性。 适合在灯光预设切换时一键应用全套灯光参数（如”夜间模式”、“警戒模式”、“庆祝模式”）。

节点信息

字段	值
节点 ID	lightSetProperties
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填
color	颜色	数据	color	灯光颜色（可选） 不连接时保持当前值。	可编辑控件 默认值：{“r”:255,“g”:255,“b”:255,“a”:255}	可选
useColorTemperature	启用色温	数据	boolean	是否启用色温（可选） 不连接时保持当前值。	开关 默认值：false	可选
colorTemperature	色温（K）	数据	number	色温值（可选） 不连接时保持当前值。	输入框 默认值：6550	可选
baked	参与烘焙	数据	boolean	是否参与烘焙（可选） 不连接时保持当前值。	开关 默认值：false	可选
visibility	可见性掩码	数据	number	可见性掩码（可选） 不连接时保持当前值。	输入框 默认值：1073741824	可选

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置灯光颜色

设置灯光颜色：修改灯光的颜色。 可用于制作玩法反馈：受伤时场景闪红光、解谜成功时变金色、进入水下区域变蓝色。 如果启用了色温，最终颜色 = 主色 × 色温。默认白色（255, 255, 255）表示不改变物体原色。

节点信息

字段	值
节点 ID	lightSetColor
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填
color	颜色	数据	color	灯光颜色 要设置的灯光主色。默认白色 (255, 255, 255)。	可编辑控件 默认值：{“r”:255,“g”:255,“b”:255,“a”:255}	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置烘焙开关

设置烘焙开关：切换灯光是否参与预烘焙。 true → 灯光烘焙到光照贴图，适合不会移动的固定光源（路灯、天花板灯等）。false → 实时计算，适合动态光源（手电筒、移动的灯）。 注意：游戏运行时切换不影响已完成的烘焙贴图，需重新烘焙才能生效。

节点信息

字段	值
节点 ID	lightSetBaked
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填
baked	参与烘焙	数据	boolean	是否参与烘焙 true = 预烘焙，false = 实时计算。	开关 默认值：false	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置可见性掩码

设置灯光可见性掩码：控制灯光对哪些摄像机可见。 每个摄像机有一个可见性掩码，灯光也有一个。两者有交集时，摄像机才能看到该灯光的效果。 常见用法：在分屏游戏中，让灯光只对玩家 1 的摄像机可见，不对玩家 2 的摄像机产生影响。

节点信息

字段	值
节点 ID	lightSetVisibility
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填
visibility	可见性掩码	数据	number	可见性掩码 决定灯光影响哪些摄像机。默认 1073741824（DEFAULT 层）。	输入框 默认值：1073741824	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置色温开关

设置色温开关：开启或关闭灯光的色温功能。 设置为 true → 启用色温，配合「色温值」节点调节暖/冷色调。 设置为 false → 关闭色温，灯光只使用主颜色。 常见用例：白天用暖色温营造黄昏氛围，或进入寒冷区域时切换为冷色温。

节点信息

字段	值
节点 ID	lightSetUseColorTemperature
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填
useColorTemperature	启用色温	数据	boolean	是否启用色温 true = 启用，false = 禁用。	开关 默认值：false	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置色温值

设置灯光色温：调整灯光的暖/冷色调。 常见用法：2700K → 模拟烛光/篝火等暖色照明；6500K → 标准日光；9000K+ → 月光/寒冰场景等冷色效果。 可用在区域切换时平滑过渡色温——进入山洞时调暖，进入雪地时调冷。

节点信息

字段	值
节点 ID	lightSetColorTemperature
分类	Cocos 组件
二级分类	灯光
分组	Light
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
light	灯光	数据	cc.Component / Light	目标 Light 组件 要操作的灯光组件。 所有灯光类型（DirectionalLight、PointLight、SpotLight 等）均可传入此端口。本节点操作灯光公共属性。	-	必填
colorTemperature	色温（K）	数据	number	色温值（K） 范围 1000～15000K，建议步进 100。需启用色温开关。默认 6550。	输入框 默认值：6550	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。