使用指南
Cocos 组件 / 灯光 / DirectionalLight节点
Cocos 组件 / 灯光 / DirectionalLight 节点手册，包含 32 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：32
- 分类路径：Cocos 组件 / 灯光 / DirectionalLight
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取 PCF 采样类型 | directionalLightGetShadowPcf | 1 / 1 | 立即继续 |
| 获取法线偏移 | directionalLightGetShadowNormalBias | 1 / 1 | 立即继续 |
| 获取固定区域阴影 | directionalLightGetShadowFixedArea | 1 / 1 | 立即继续 |
| 获取光照强度 | directionalLightGetIlluminance | 1 / 1 | 立即继续 |
| 获取级联分配系数 | directionalLightGetCsmLayerLambda | 1 / 1 | 立即继续 |
| 获取级联过渡范围 | directionalLightGetCsmTransitionRange | 1 / 1 | 立即继续 |
| 获取级联过渡开关 | directionalLightGetCsmLayersTransition | 1 / 1 | 立即继续 |
| 获取级联阴影开关 | directionalLightGetEnableCSM | 1 / 1 | 立即继续 |
| 获取近截面距离 | directionalLightGetShadowNear | 1 / 1 | 立即继续 |
| 获取全部属性 | directionalLightGetProperties | 1 / 15 | 立即继续 |
| 获取阴影饱和度 | directionalLightGetShadowSaturation | 1 / 1 | 立即继续 |
| 获取阴影距离 | directionalLightGetShadowDistance | 1 / 1 | 立即继续 |
| 获取阴影开关 | directionalLightGetShadowEnabled | 1 / 1 | 立即继续 |
| 获取阴影偏移 | directionalLightGetShadowBias | 1 / 1 | 立即继续 |
| 获取远截面距离 | directionalLightGetShadowFar | 1 / 1 | 立即继续 |
| 获取正交阴影范围 | directionalLightGetShadowOrthoSize | 1 / 1 | 立即继续 |
| 设置 PCF 采样类型 | directionalLightSetShadowPcf | 3 / 2 | 立即继续 |
| 设置法线偏移 | directionalLightSetShadowNormalBias | 3 / 2 | 立即继续 |
| 设置固定区域阴影 | directionalLightSetShadowFixedArea | 3 / 2 | 立即继续 |
| 设置光照强度 | directionalLightSetIlluminance | 3 / 2 | 立即继续 |
| 设置级联分配系数 | directionalLightSetCsmLayerLambda | 3 / 2 | 立即继续 |
| 设置级联过渡范围 | directionalLightSetCsmTransitionRange | 3 / 2 | 立即继续 |
| 设置级联过渡开关 | directionalLightSetCsmLayersTransition | 3 / 2 | 立即继续 |
| 设置级联阴影开关 | directionalLightSetEnableCSM | 3 / 2 | 立即继续 |
| 设置近截面距离 | directionalLightSetShadowNear | 3 / 2 | 立即继续 |
| 设置全部属性 | directionalLightSetProperties | 17 / 2 | 立即继续 |
| 设置阴影饱和度 | directionalLightSetShadowSaturation | 3 / 2 | 立即继续 |
| 设置阴影距离 | directionalLightSetShadowDistance | 3 / 2 | 立即继续 |
| 设置阴影开关 | directionalLightSetShadowEnabled | 3 / 2 | 立即继续 |
| 设置阴影偏移 | directionalLightSetShadowBias | 3 / 2 | 立即继续 |
| 设置远截面距离 | directionalLightSetShadowFar | 3 / 2 | 立即继续 |
| 设置正交阴影范围 | directionalLightSetShadowOrthoSize | 3 / 2 | 立即继续 |
获取 PCF 采样类型
获取 PCF 采样类型：返回阴影的 PCF（Percentage Closer Filtering）软化模式。 返回值含义： • 0（HARD）：1 次采样，硬阴影边缘 • 1（SOFT）：4 次采样，基础软阴影 • 2（SOFT_2X）：9 次采样，更平滑 • 3（SOFT_4X）：16 次采样，最柔和，性能消耗最大 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowPcf |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型 0=HARD（1次采样）, 1=SOFT（4次）, 2=SOFT_2X（9次）, 3=SOFT_4X（16次，最耗性能） | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取法线偏移
获取法线偏移（shadowNormalBias）：返回沿法线方向的阴影偏移量，与 shadowBias 共同作用以减少阴影痤疮。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowNormalBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowNormalBias | 法线偏移 | 数据 | number | 法线偏移 沿法线方向的阴影偏移，与 shadowBias 协同减少阴影痤疮。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取固定区域阴影
获取固定区域阴影（shadowFixedArea）：返回是否使用固定正交投影区域渲染阴影。 为 true 时，通过 shadowNear / shadowFar / shadowOrthoSize 精确控制阴影范围；为 false 时，通过 shadowDistance 与 enableCSM 动态管理。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowFixedArea |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowFixedArea | 固定区域阴影 | 数据 | boolean | 固定区域阴影 true：通过 shadowNear/shadowFar/shadowOrthoSize 精确控制阴影范围。false：通过 shadowDistance 动态管理。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取光照强度
获取平行光光照强度：读取当前场景主光源的明暗强度。 强度值越高，整个场景越亮。常用于昼夜循环中检测当前是白天还是黑夜。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetIlluminance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
illuminance | 光照强度 | 数据 | number | 光照强度 (lux) 场景明暗值。数值越大越亮。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取级联分配系数
获取级联分配系数（csmLayerLambda）：返回控制 CSM 各层级距离划分的 lambda 系数。 注意： 仅在 enableCSM = true 时有效；数值越靠近 1，越偏向按比例分配级联层级（对数型分割），越靠近 0 则越均匀分割。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetCsmLayerLambda |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
csmLayerLambda | 级联分配系数 | 数据 | number | CSM 级联分配系数 范围 [0,1]。仅在 enableCSM=true 时有效。越靠近 1 越按比例分配（对数型），越靠近 0 越均匀分割。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取级联过渡范围
获取级联过渡范围（csmTransitionRange）：返回 CSM 层级之间过渡区域的宽度比例 [0, 1]。 注意： 仅在 enableCSM = true 时有效；关闭 CSM 时这些参数不会改变单层阴影结果。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetCsmTransitionRange |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
csmTransitionRange | 级联过渡范围 | 数据 | number | CSM 级联过渡范围 范围 [0,1]。仅在 enableCSM=true 时有效。值越大，层级过渡区域越宽。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取级联过渡开关
获取级联过渡开关（csmLayersTransition）：返回是否启用 CSM 层级之间的平滑过渡。 注意： 仅在 enableCSM = true 时有效；关闭 CSM 时这些参数不会改变单层阴影结果。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetCsmLayersTransition |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
csmLayersTransition | 级联过渡 | 数据 | boolean | CSM 级联过渡 仅在 enableCSM=true 时有效。启用后级联层级之间会平滑渐变。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取级联阴影开关
获取级联阴影开关（enableCSM）：返回是否启用级联阴影（CSM，Cascaded Shadow Maps）。 此属性是 csmLevel > LEVEL_1 的布尔包装：true 表示使用 4 层级联，false 表示使用单层阴影。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetEnableCSM |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
enableCSM | 级联阴影 | 数据 | boolean | 级联阴影（CSM）开关 true=4层级联阴影，false=单层阴影。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取近截面距离
获取近截面距离（shadowNear）：返回固定区域阴影正交投影的近截面距离。 注意： 仅在 shadowFixedArea = true 时有效。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowNear |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowNear | 近截面距离 | 数据 | number | 阴影近截面距离 仅在 shadowFixedArea=true 时有效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读取 DirectionalLight 常用日光与阴影配置：聚合读取 illuminance、shadowEnabled、shadowPcf、shadowBias、shadowNormalBias、shadowSaturation、shadowDistance、shadowFixedArea、shadowNear、shadowFar、shadowOrthoSize、enableCSM、csmLayerLambda、csmLayersTransition、csmTransitionRange。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
illuminance | 光照强度 | 数据 | number | 光照强度（勒克斯），HDR/LDR 自动适配 | - | 可选 |
shadowEnabled | 阴影开关 | 数据 | boolean | 是否开启实时阴影 | - | 可选 |
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型 (0=HARD, 1=SOFT, 2=SOFT_2X, 3=SOFT_4X) | - | 可选 |
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移，减少阴影痤疮 | - | 可选 |
shadowNormalBias | 法线偏移 | 数据 | number | 法线方向阴影偏移 | - | 可选 |
shadowSaturation | 阴影饱和度 | 数据 | number | 阴影深浅程度 [0,1]，1 为全黑 | - | 可选 |
shadowDistance | 阴影距离 | 数据 | number | 阴影可见范围，shadowFixedArea=false 时有效 | - | 可选 |
shadowFixedArea | 固定区域阴影 | 数据 | boolean | 是否使用固定正交投影阴影区域 | - | 可选 |
shadowNear | 近截面距离 | 数据 | number | 阴影近截面，shadowFixedArea=true 时有效 | - | 可选 |
shadowFar | 远截面距离 | 数据 | number | 阴影远截面，shadowFixedArea=true 时有效 | - | 可选 |
shadowOrthoSize | 正交阴影范围 | 数据 | number | 正交阴影半径，shadowFixedArea=true 时有效 | - | 可选 |
enableCSM | 级联阴影 | 数据 | boolean | 是否启用级联阴影（CSM） | - | 可选 |
csmLayerLambda | 级联分配系数 | 数据 | number | CSM 层级分配系数 [0,1]，enableCSM=true 时有效 | - | 可选 |
csmLayersTransition | 级联过渡 | 数据 | boolean | 是否启用 CSM 层级过渡，enableCSM=true 时有效 | - | 可选 |
csmTransitionRange | 级联过渡范围 | 数据 | number | CSM 过渡范围 [0,1]，enableCSM=true 时有效 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取阴影饱和度
获取阴影饱和度（shadowSaturation）：返回阴影区域的深度饱和度。1 表示全黑阴影，0 表示完全透明。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowSaturation |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowSaturation | 阴影饱和度 | 数据 | number | 阴影饱和度 范围 [0, 1]。1 表示全黑阴影，0 表示完全透明。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取阴影距离
获取阴影距离（shadowDistance）：返回阴影的可见范围距离（世界单位）。 注意： 仅在 shadowFixedArea = false 时有效；值越大覆盖范围越远，但阴影精度通常越低。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowDistance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowDistance | 阴影距离 | 数据 | number | 阴影距离 仅在 shadowFixedArea=false 时有效。越大覆盖范围越远，精度越低。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取阴影开关
获取阴影开关：返回平行光是否开启实时阴影投射。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowEnabled |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowEnabled | 阴影开关 | 数据 | boolean | 阴影开关 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取阴影偏移
获取阴影偏移（shadowBias）：返回阴影深度偏移量，用于减少阴影痤疮（shadow acne）。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移 减少阴影痤疮（shadow acne）的深度偏移量。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取远截面距离
获取远截面距离（shadowFar）：返回固定区域阴影正交投影的远截面距离。 注意： 仅在 shadowFixedArea = true 时有效。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowFar |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowFar | 远截面距离 | 数据 | number | 阴影远截面距离 仅在 shadowFixedArea=true 时有效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取正交阴影范围
获取正交阴影范围（shadowOrthoSize）：返回固定区域阴影正交投影的可见范围半径（世界单位）。 注意： 仅在 shadowFixedArea = true 时有效。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightGetShadowOrthoSize |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowOrthoSize | 正交阴影范围 | 数据 | number | 正交阴影范围 固定区域阴影的正交投影半径，仅在 shadowFixedArea=true 时有效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置 PCF 采样类型
设置 PCF 采样类型：设置阴影的 PCF 软化模式。采样数越多，阴影越柔和，但性能消耗越高。 选项含义： • 0（HARD）：1 次采样，性能最好 • 1（SOFT）：4 次采样，基础软阴影 • 2（SOFT_2X）：9 次采样 • 3（SOFT_4X）：16 次采样，最柔和 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowPcf |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型 0=HARD, 1=SOFT, 2=SOFT_2X, 3=SOFT_4X | 下拉选择 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置法线偏移
设置法线偏移（shadowNormalBias）：设置沿法线方向的阴影偏移量，与 shadowBias 共同作用以减少阴影痤疮与条纹伪影。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowNormalBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowNormalBias | 法线偏移 | 数据 | number | 法线偏移 沿法线方向的阴影偏移，与 shadowBias 协同减少阴影痤疮。 | 输入框 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置固定区域阴影
设置固定区域阴影（shadowFixedArea）：切换阴影投影模式。 • true：使用 shadowNear / shadowFar / shadowOrthoSize 精确控制阴影范围，适合需要精准裁剪的场景 • false：使用 shadowDistance 与 enableCSM 动态管理 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowFixedArea |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowFixedArea | 固定区域阴影 | 数据 | boolean | 固定区域阴影 true：通过 shadowNear/Far/OrthoSize 精确控制；false：通过 shadowDistance 动态管理。 | 开关 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置光照强度
设置平行光光照强度：调节场景主光源的明暗。 0 = 完全黑暗（如同日食），65000 = 正午日光，500~1000 = 室内光线。 常见用例：制作昼夜循环——白天设为 65000，黄昏渐暗至 5000，夜晚设为 100 或 0。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetIlluminance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
illuminance | 光照强度 | 数据 | number | 光照强度（勒克斯 lux） HDR/LDR 模式下自动适配底层存储。最小值 0。 | 输入框 默认值：65000 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置级联分配系数
设置级联分配系数（csmLayerLambda）：设置控制 CSM 各层距离划分的 lambda 系数，取值 [0, 1]。 注意： 仅在 enableCSM = true 时有效；数值越靠近 1，越偏向按比例分配级联层级，近处层级更密集；修改此参数会触发级联阴影重新计算（csmNeedUpdate = true）。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetCsmLayerLambda |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
csmLayerLambda | 级联分配系数 | 数据 | number | CSM 级联分配系数 范围 [0,1]。仅在 enableCSM=true 时有效。 | 输入框 默认值：0.75 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置级联过渡范围
设置级联过渡范围（csmTransitionRange）：设置 CSM 层级之间过渡区域的宽度比例，取值 [0, 1]。 注意： 仅在 enableCSM = true 时有效；关闭 CSM 时这些参数不会改变单层阴影结果。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetCsmTransitionRange |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
csmTransitionRange | 级联过渡范围 | 数据 | number | CSM 级联过渡范围 范围 [0,1]。仅在 enableCSM=true 时有效。 | 输入框 默认值：0.05 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置级联过渡开关
设置级联过渡开关（csmLayersTransition）：开启或关闭 CSM 层级之间的平滑过渡混合。 注意： 仅在 enableCSM = true 时有效；关闭 CSM 时这些参数不会改变单层阴影结果。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetCsmLayersTransition |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
csmLayersTransition | 级联过渡 | 数据 | boolean | CSM 级联过渡 仅在 enableCSM=true 时有效。 | 开关 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置级联阴影开关
设置级联阴影开关（enableCSM）：开启或关闭级联阴影。 设置为 true 会将 csmLevel 切换到 LEVEL_4（4层级联），设置为 false 会切换到 LEVEL_1（单层）。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetEnableCSM |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
enableCSM | 级联阴影 | 数据 | boolean | 级联阴影（CSM）开关 true=4层级联（LEVEL_4），false=单层（LEVEL_1）。 | 开关 默认值：true | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置近截面距离
设置近截面距离（shadowNear）：设置固定区域阴影正交投影的近截面距离。 注意： 仅在 shadowFixedArea = true 时有效。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowNear |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowNear | 近截面距离 | 数据 | number | 阴影近截面距离 仅在 shadowFixedArea=true 时有效。 | 输入框 默认值：0.1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置全部属性
批量修改 DirectionalLight 常用日光与阴影配置：聚合写入全部 15 个可写属性。 说明：除 exe 与 directionalLight 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开且有值的属性才参与写入；未公开属性保持原值不变。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
illuminance | 光照强度 | 数据 | number | 光照强度（勒克斯），HDR/LDR 自动适配 | 输入框 默认值：65000 | 可选 默认隐藏 |
shadowEnabled | 阴影开关 | 数据 | boolean | 是否开启实时阴影 | 开关 默认值：false | 可选 默认隐藏 |
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型 (0=HARD, 1=SOFT, 2=SOFT_2X, 3=SOFT_4X) | 下拉选择 默认值：0 | 可选 默认隐藏 |
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移 | 输入框 默认值：0.00001 | 可选 默认隐藏 |
shadowNormalBias | 法线偏移 | 数据 | number | 法线方向阴影偏移 | 输入框 默认值：0 | 可选 默认隐藏 |
shadowSaturation | 阴影饱和度 | 数据 | number | 阴影深浅 [0,1] | 输入框 默认值：1 | 可选 默认隐藏 |
shadowDistance | 阴影距离 | 数据 | number | 阴影可见范围，shadowFixedArea=false 时有效 | 输入框 默认值：50 | 可选 默认隐藏 |
shadowFixedArea | 固定区域阴影 | 数据 | boolean | 是否使用固定正交投影阴影区域 | 开关 默认值：false | 可选 默认隐藏 |
shadowNear | 近截面距离 | 数据 | number | 阴影近截面，shadowFixedArea=true 时有效 | 输入框 默认值：0.1 | 可选 默认隐藏 |
shadowFar | 远截面距离 | 数据 | number | 阴影远截面，shadowFixedArea=true 时有效 | 输入框 默认值：10 | 可选 默认隐藏 |
shadowOrthoSize | 正交阴影范围 | 数据 | number | 正交阴影半径，shadowFixedArea=true 时有效 | 输入框 默认值：5 | 可选 默认隐藏 |
enableCSM | 级联阴影 | 数据 | boolean | 是否启用级联阴影（CSM） | 开关 默认值：true | 可选 默认隐藏 |
csmLayerLambda | 级联分配系数 | 数据 | number | CSM 层级分配系数 [0,1] | 输入框 默认值：0.75 | 可选 默认隐藏 |
csmLayersTransition | 级联过渡 | 数据 | boolean | 是否启用 CSM 层级过渡 | 开关 默认值：false | 可选 默认隐藏 |
csmTransitionRange | 级联过渡范围 | 数据 | number | CSM 过渡范围 [0,1] | 输入框 默认值：0.05 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置阴影饱和度
设置阴影饱和度（shadowSaturation）：控制阴影区域的深浅程度。1 为全黑阴影，0 为完全透明（无阴影效果）。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowSaturation |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowSaturation | 阴影饱和度 | 数据 | number | 阴影饱和度 范围 [0, 1]。1 为全黑，0 为透明。 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置阴影距离
设置阴影距离（shadowDistance）：设置阴影的可见范围距离。 注意： 仅在 shadowFixedArea = false 时有效；值越大覆盖范围越远，但阴影精度通常越低。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowDistance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowDistance | 阴影距离 | 数据 | number | 阴影距离 仅在 shadowFixedArea=false 时有效。最小值 0。 | 输入框 默认值：50 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置阴影开关
设置阴影开关：开启或关闭平行光的实时阴影投射。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowEnabled |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowEnabled | 阴影开关 | 数据 | boolean | 阴影开关 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 开关 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置阴影偏移
设置阴影偏移（shadowBias）：设置阴影深度偏移量，用于减少阴影痤疮。数值过大会导致阴影悬浮，过小会出现阴影条纹。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移 减少阴影痤疮（shadow acne）。过大导致阴影悬浮，过小产生条纹。 | 输入框 默认值：0.00001 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置远截面距离
设置远截面距离（shadowFar）：设置固定区域阴影正交投影的远截面距离。 注意： 仅在 shadowFixedArea = true 时有效。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowFar |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowFar | 远截面距离 | 数据 | number | 阴影远截面距离 仅在 shadowFixedArea=true 时有效。最小值 0。 | 输入框 默认值：10 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置正交阴影范围
设置正交阴影范围（shadowOrthoSize）：设置固定区域阴影正交投影的可见范围半径。值越大，单个阴影纹理覆盖区域越大，精度越低。 注意： 仅在 shadowFixedArea = true 时有效。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | directionalLightSetShadowOrthoSize |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | DirectionalLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 要操作的平行光（场景主光源）。平行光模拟太阳——从固定方向照射整个场景，所有物体都被照亮。用于控制场景整体明暗、色调和实时阴影。 | - | 必填 |
shadowOrthoSize | 正交阴影范围 | 数据 | number | 正交阴影范围 仅在 shadowFixedArea=true 时有效。最小值 0。 | 输入框 默认值：5 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
directionalLight | 平行光 | 数据 | cc.Component / DirectionalLight | 目标 DirectionalLight 组件 透传当前操作的 DirectionalLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。