使用指南
Cocos 组件 / 灯光 / RangedDirectionalLight节点
Cocos 组件 / 灯光 / RangedDirectionalLight 节点手册，包含 5 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：5
- 分类路径：Cocos 组件 / 灯光 / RangedDirectionalLight
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取光照强度 | rangedDirectionalLightGetIlluminance | 1 / 1 | 立即继续 |
| 获取空间信息 | rangedDirectionalLightGetSpaceInfo | 1 / 4 | 立即继续 |
| 获取全部属性 | rangedDirectionalLightGetProperties | 1 / 5 | 立即继续 |
| 设置光照强度 | rangedDirectionalLightSetIlluminance | 3 / 2 | 立即继续 |
| 设置全部属性 | rangedDirectionalLightSetProperties | 3 / 2 | 立即继续 |
获取光照强度
获取局部平行光光照强度：读取当前局部平行光的明暗强度值。 强度值越高，场景被照亮的区域越亮。适合在游戏运行时根据环境变化（如进入黑暗区域、时间流逝）动态读取当前亮度，用于 UI 显示或调试。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | rangedDirectionalLightGetIlluminance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | RangedDirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 要操作的局部平行光组件。局部平行光在一个有限区域内模拟方向光效果，适合室内补光、近景照明、手电筒式定向光等场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
illuminance | 光照强度 | 数据 | number | 光照强度（勒克斯 lux） 光源的明暗值。数值越大越亮。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取空间信息
获取局部平行光空间信息：读取光源的位置、朝向和缩放信息。 这些值反映光源节点在 3D 场景中的实际摆放状态——光往哪个方向照、光源在世界中的坐标位置、以及覆盖盒的大小。 注意： 这些值来自游戏运行时变换同步，反映节点当前世界变换状态，只读展示，不能通过组件直接写回。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | rangedDirectionalLightGetSpaceInfo |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | RangedDirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 要操作的局部平行光组件。局部平行光在一个有限区域内模拟方向光效果，适合室内补光、近景照明、手电筒式定向光等场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
direction | 光照朝向 | 数据 | vector3 | 光照朝向 光源的照射方向。只读。 | - | 可选 |
right | 局部右方向 | 数据 | vector3 | 局部右方向 光源局部坐标系的右方向。只读。 | - | 可选 |
position | 世界坐标 | 数据 | vector3 | 世界坐标 光源节点在世界空间中的位置。只读。 | - | 可选 |
scale | 节点世界缩放 | 数据 | vector3 | 节点世界缩放 光源的覆盖范围大小。如需修改覆盖范围，请使用节点变换节点。只读。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读取局部平行光所有属性：同时获取光照强度和空间信息（朝向、右方向、位置、缩放）。 适合在灯光切换或场景过渡时批量记录当前灯光的完整状态。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | rangedDirectionalLightGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | RangedDirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 要操作的局部平行光组件。局部平行光在一个有限区域内模拟方向光效果，适合室内补光、近景照明、手电筒式定向光等场景。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
illuminance | 光照强度 | 数据 | number | 光照强度 (lux) 光源明暗值 | - | 可选 |
direction | 光照朝向 | 数据 | vector3 | 光照朝向 光源照射方向。只读。 | - | 可选 |
right | 局部右方向 | 数据 | vector3 | 局部右方向 光源右方向。只读。 | - | 可选 |
position | 世界坐标 | 数据 | vector3 | 世界坐标 光源位置。只读。 | - | 可选 |
scale | 节点世界缩放 | 数据 | vector3 | 节点世界缩放 覆盖范围。只读。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置光照强度
设置局部平行光光照强度：调整局部平行光的明暗强度。 强度 = 0 → 光源完全熄灭，不产生照明效果。强度越大，照明越亮。 常见用例：玩家进入洞穴时把强度从 65000（日光）调低到 500（昏暗室内），营造黑暗环境氛围；或定时切换昼夜光照效果。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | rangedDirectionalLightSetIlluminance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | RangedDirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 要操作的局部平行光组件。局部平行光在一个有限区域内模拟方向光效果，适合室内补光、近景照明、手电筒式定向光等场景。 | - | 必填 |
illuminance | 光照强度 | 数据 | number | 光照强度（勒克斯 lux） 光源明暗值。0 = 熄灭。默认 65000。 | 输入框 默认值：65000 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 透传当前操作的 RangedDirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置全部属性
批量设置局部平行光属性：目前支持修改光照强度（illuminance）。 未连接的属性引脚保持原值不变，只修改你显式连接了的属性。 适合在场景过渡或灯光切换时一键调整灯光亮度。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | rangedDirectionalLightSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | RangedDirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 要操作的局部平行光组件。局部平行光在一个有限区域内模拟方向光效果，适合室内补光、近景照明、手电筒式定向光等场景。 | - | 必填 |
illuminance | 光照强度 | 数据 | number | 光照强度 (lux) 光源明暗值。0 = 熄灭。默认 65000。 | 输入框 默认值：65000 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
rangedDirectionalLight | 局部平行光 | 数据 | cc.Component / RangedDirectionalLight | 目标 RangedDirectionalLight 组件 透传当前操作的 RangedDirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。