Cocos 组件 / 灯光 / PointLight节点

学习目标

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

覆盖范围

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

典型使用场景

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

通用注意事项

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

节点索引

节点	节点 ID	输入/输出	执行方式
获取光度学单位	pointLightGetTerm	1 / 1	立即继续
获取光亮度	pointLightGetLuminance	1 / 1	立即继续
获取光通量	pointLightGetLuminousFlux	1 / 1	立即继续
获取光源范围	pointLightGetRange	1 / 1	立即继续
获取全部属性	pointLightGetProperties	1 / 4	立即继续
设置光度学单位	pointLightSetTerm	3 / 2	立即继续
设置光亮度	pointLightSetLuminance	3 / 2	立即继续
设置光通量	pointLightSetLuminousFlux	3 / 2	立即继续
设置光源范围	pointLightSetRange	3 / 2	立即继续
设置全部属性	pointLightSetProperties	6 / 2	立即继续

获取光度学单位

获取亮度调节模式：查看点光源当前使用的是”光通量”模式还是”亮度”模式。 0 = 光通量模式（流明 lm），适合用灯泡总功率的思路调节亮度。1 = 亮度模式（cd/m²），适合精确控制。 提示：切换模式不会自动换算已有数值。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
term	光度学单位	数据	number	亮度模式 0 = 光通量模式（流明），1 = 亮度模式（cd/m²）。切换不换算已有数值。	-	可选

使用场景

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

注意事项

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

---

获取光亮度

获取点光源亮度：读取点光源的亮度数值（cd/m²）。 这是以”单位面积亮度”的方式衡量光强度，适合需要精确控制亮度的场景。 提示：选择”光通量”模式时使用流明（lm）调节亮度，适合模拟灯泡总功率；选择”亮度”模式时使用 cd/m²，适合精确调光。切换模式不会自动换算已有数值，需手动调整。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
luminance	光亮度	数据	number	光亮度 (cd/m²) 单位面积亮度值。越高越亮。	-	可选

使用场景

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

注意事项

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

---

获取光通量

获取点光源光通量：读取点光源的”总发光量”（流明 lm）。 光通量越高，光源越亮。默认值 1700 相当于普通家用灯泡的亮度。 适合用于监控当前光源亮度状态，或在调试时查看点光是否按预期发光。 提示：选择”光通量”模式时使用流明（lm）调节亮度，适合模拟灯泡总功率；选择”亮度”模式时使用 cd/m²，适合精确调光。切换模式不会自动换算已有数值，需手动调整。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
luminousFlux	光通量	数据	number	光通量 (lm) 光源的总发光量。越高越亮。默认 1700。	-	可选

使用场景

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

注意事项

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

---

获取光源范围

获取点光源照射范围：读取点光源照亮区域的半径。 范围越大，光源覆盖的房间面积越广；范围越小，光源只照亮局部区域。 适合用于检查当前光源覆盖范围是否满足关卡设计需求。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
range	光源范围	数据	number	照射半径 光源覆盖范围。越大照亮越广。默认 1。	-	可选

使用场景

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

注意事项

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

---

获取全部属性

一次性读取点光源全部属性：同时获取亮度、亮度模式、照射范围。 适合在场景切换时批量记录光源完整配置，或用于调试面板展示光源参数。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
luminousFlux	光通量	数据	number	光通量 (lm) 光源总发光量。	-	可选
luminance	光亮度	数据	number	光亮度 (cd/m²) 单位面积亮度。	-	可选
term	光度学单位	数据	number	亮度模式 0 = 光通量，1 = 亮度。	-	可选
range	光源范围	数据	number	照射半径 光源覆盖范围。	-	可选

使用场景

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

注意事项

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

---

设置光度学单位

切换亮度调节模式：在”光通量”和”亮度”两种模式之间切换。 选择 0（光通量） → 使用流明（lm）调节，像选择灯泡瓦数一样直观。选择 1（亮度） → 使用 cd/m² 精确控制。 注意：切换模式不会自动换算已有亮度数值。如果切换后亮度变化不合预期，请手动调整对应数值。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填
term	光度学单位	数据	number	亮度模式 0 = 光通量，1 = 亮度。切换不会换算已有数值。	下拉选择 默认值：0	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 透传当前操作的 PointLight 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置光亮度

设置点光源亮度：以单位面积亮度方式调整光源明暗。 亮度值越高，光源越亮。适合需要精确控制光照强度的场合。 提示：选择”光通量”模式时使用流明（lm）调节亮度，适合模拟灯泡总功率；选择”亮度”模式时使用 cd/m²，适合精确调光。切换模式不会自动换算已有数值，需手动调整。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填
luminance	光亮度	数据	number	光亮度 (cd/m²) 单位面积亮度。0 = 熄灭。步进 10。默认 1700。	输入框 默认值：1700	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 透传当前操作的 PointLight 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置光通量

设置点光源光通量：调节点光源的总发光量（流明 lm）。 数值越大光源越亮——0 = 完全熄灭，1700 = 日常灯泡亮度，5000+ = 强光照明。 常见用例：玩家拾取”增亮”道具时增大光通量让灯更亮；进入黑暗区域时调低以实现光影对比效果。 提示：选择”光通量”模式时使用流明（lm）调节亮度，适合模拟灯泡总功率；选择”亮度”模式时使用 cd/m²，适合精确调光。切换模式不会自动换算已有数值，需手动调整。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填
luminousFlux	光通量	数据	number	光通量 (lm) 光源总发光量。0 = 熄灭。步进 100。默认 1700。	输入框 默认值：1700	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 透传当前操作的 PointLight 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置光源范围

设置点光源照射范围：调整点光源照亮区域的半径。 范围越大，光源能照亮的区域越广——1 照亮小房间，5 照亮大广场，10+ 照亮整个场景。 常见用例：玩家使用”扩光”技能时增大范围以照亮更大区域；或火把在风中摇晃时调小范围营造闪烁感。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填
range	光源范围	数据	number	照射半径 光源覆盖范围。默认 1，步进 0.1。	输入框 默认值：1	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 透传当前操作的 PointLight 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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

---

设置全部属性

批量设置点光源属性：同时修改亮度、亮度模式和照射范围。 未连接的属性引脚保持原值不变，只修改你显式连接了的属性。 适合在灯光预设切换时一键应用到全部点光源参数（如”昏暗模式”、“强光模式”）。

节点信息

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

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 要操作的点光源。点光源从中心向四周均匀发光，像灯泡、火把、魔法光球一样照亮周围区域。	-	必填
luminousFlux	光通量	数据	number	光通量 (lm) 光源总发光量。默认 1700。	输入框 默认值：1700	可选 默认隐藏
luminance	光亮度	数据	number	光亮度 (cd/m²) 单位面积亮度。默认 1700。	输入框 默认值：1700	可选 默认隐藏
term	光度学单位	数据	number	亮度模式 0 = 光通量，1 = 亮度。切换不换算已有数值。	下拉选择 默认值：0	可选 默认隐藏
range	光源范围	数据	number	照射半径 光源覆盖范围。默认 1。	输入框 默认值：1	可选 默认隐藏

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
pointLight	点光源	数据	cc.Component / PointLight	目标 PointLight 组件 透传当前操作的 PointLight 组件，便于链式操作。	-	可选

使用场景

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

注意事项

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