使用指南
Cocos 组件 / 灯光 / SpotLight节点
Cocos 组件 / 灯光 / SpotLight 节点手册，包含 24 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：24
- 分类路径：Cocos 组件 / 灯光 / SpotLight
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取 PCF 采样类型 | spotLightGetShadowPcf | 1 / 1 | 立即继续 |
| 获取边缘衰减强度 | spotLightGetAngleAttenuationStrength | 1 / 1 | 立即继续 |
| 获取发光面尺寸 | spotLightGetSize | 1 / 1 | 立即继续 |
| 获取法线偏移 | spotLightGetShadowNormalBias | 1 / 1 | 立即继续 |
| 获取光度学单位 | spotLightGetTerm | 1 / 1 | 立即继续 |
| 获取光亮度 | spotLightGetLuminance | 1 / 1 | 立即继续 |
| 获取光通量 | spotLightGetLuminousFlux | 1 / 1 | 立即继续 |
| 获取光源范围 | spotLightGetRange | 1 / 1 | 立即继续 |
| 获取全部属性 | spotLightGetProperties | 1 / 11 | 立即继续 |
| 获取阴影开关 | spotLightGetShadowEnabled | 1 / 1 | 立即继续 |
| 获取阴影偏移 | spotLightGetShadowBias | 1 / 1 | 立即继续 |
| 获取锥角 | spotLightGetSpotAngle | 1 / 1 | 立即继续 |
| 设置 PCF 采样类型 | spotLightSetShadowPcf | 3 / 2 | 立即继续 |
| 设置边缘衰减强度 | spotLightSetAngleAttenuationStrength | 3 / 2 | 立即继续 |
| 设置发光面尺寸 | spotLightSetSize | 3 / 2 | 立即继续 |
| 设置法线偏移 | spotLightSetShadowNormalBias | 3 / 2 | 立即继续 |
| 设置光度学单位 | spotLightSetTerm | 3 / 2 | 立即继续 |
| 设置光亮度 | spotLightSetLuminance | 3 / 2 | 立即继续 |
| 设置光通量 | spotLightSetLuminousFlux | 3 / 2 | 立即继续 |
| 设置光源范围 | spotLightSetRange | 3 / 2 | 立即继续 |
| 设置全部属性 | spotLightSetProperties | 13 / 2 | 立即继续 |
| 设置阴影开关 | spotLightSetShadowEnabled | 3 / 2 | 立即继续 |
| 设置阴影偏移 | spotLightSetShadowBias | 3 / 2 | 立即继续 |
| 设置锥角 | spotLightSetSpotAngle | 3 / 2 | 立即继续 |
获取 PCF 采样类型
获取 PCF 采样类型（shadowPcf）：返回聚光灯阴影的 PCF（Percentage Closer Filtering）软阴影质量级别。 返回值枚举： • 0（HARD）：1 次采样，硬边缘，性能最高 • 1（SOFT）：4 次采样，基础软阴影 • 2（SOFT_2X）：9 次采样，更平滑 • 3（SOFT_4X）：16 次采样，最柔和，性能开销最大 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetShadowPcf |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型 0 = HARD（1次采样，硬边缘） 1 = SOFT（4次采样，基础软阴影） 2 = SOFT_2X（9次采样，更平滑） 3 = SOFT_4X（16次采样，最柔和） 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取边缘衰减强度
获取边缘衰减强度（angleAttenuationStrength）：返回聚光锥体边缘的衰减曲线强度。 范围 0～1；0 表示边缘处光照骤降（硬边），1 表示边缘过渡更柔和（软边）。与 spotAngle 共同决定光锥的视觉特征。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetAngleAttenuationStrength |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
angleAttenuationStrength | 边缘衰减强度 | 数据 | number | 边缘衰减强度 范围 0～1。0 = 硬边（骤降），1 = 软边（渐变）。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取发光面尺寸
获取发光面尺寸（size）：返回聚光灯发光面的尺寸。 该参数不仅影响视觉外观，在 HDR 模式下还会通过 nt2lm(size) = 4π²size² 参与 luminousFlux 与内部亮度存储之间的换算。数值越大，通常会让聚光边缘显得更柔和，但注意相同光通量下内部亮度分布也会随之变化。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetSize |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
size | 发光面尺寸 | 数据 | number | 发光面尺寸 范围 0～10。HDR 模式下影响 luminousFlux 与内部亮度的换算关系。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取法线偏移
获取法线偏移（shadowNormalBias）：返回沿法线方向的阴影偏移量，与 shadowBias 共同作用以减少阴影痤疮。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetShadowNormalBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowNormalBias | 法线偏移 | 数据 | number | 法线偏移 沿法线方向的阴影偏移，与 shadowBias 协同减少阴影痤疮。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取光度学单位
获取光度学单位（term）：返回当前聚光灯使用的光度学单位类型。 返回值含义： • 0（LUMINOUS_FLUX）：Inspector 展示 luminousFlux（光通量，流明） • 1（LUMINANCE）：Inspector 展示 luminance（亮度，cd/m²） 注意： term 只影响 Inspector 展示与业务语义表达，切换 term 不会自动换算之前输入的亮度数值；底层渲染存储始终是同一份数据。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetTerm |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
term | 光度学单位 | 数据 | number | 光度学单位类型 0 = LUMINOUS_FLUX（光通量，流明 lm） 1 = LUMINANCE（亮度，cd/m²） 切换单位语义，不自动换算旧值。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取光亮度
获取光亮度（luminance）：返回聚光灯当前的亮度数值（单位面积亮度入口）。 getter 同样会依据 HDR 状态自动适配底层存储。luminance 是”单位面积光强度”的业务入口，与 luminousFlux 不同，二者都写入同一底层渲染存储，只是物理单位语义不同。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetLuminance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
luminance | 光亮度 | 数据 | number | 光亮度（坎德拉每平方米 cd/m²） 单位面积亮度，HDR/LDR 自动适配。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取光通量
获取聚光灯总发光量：读取聚光灯的亮度（流明 lm）。 光通量越高，光束越亮。默认值 1700 相当于普通灯泡。 ${TERM_CONTEXT_ZH}
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetLuminousFlux |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
luminousFlux | 光通量 | 数据 | number | 光通量（流明 lm） 代表灯泡总发光量，HDR/LDR 自动适配。HDR 模式下与 size 联动换算。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取光源范围
获取光源范围（range）：返回聚光灯的最大照射距离（世界单位）。 渲染层会根据此值与锥角共同决定聚光灯的可视阴影体积与影响范围。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetRange |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
range | 光源范围 | 数据 | number | 最大照射距离（世界单位） 数值越大，聚光灯影响范围越远，渲染开销也越高。最小值 0。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读取 SpotLight 全部属性：聚合读取 luminousFlux、luminance、term、size、range、spotAngle、angleAttenuationStrength、shadowEnabled、shadowPcf、shadowBias、shadowNormalBias。 注意：term 决定 Inspector 展示哪种亮度字段。spotAngle 为完整锥角（度），非半角。阴影相关字段需满足 ShadowMap 前置条件才有效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
luminousFlux | 光通量 | 数据 | number | 光通量（流明 lm），HDR/LDR 自动适配。term=LUMINOUS_FLUX 时与 Inspector 语义一致。 | - | 可选 |
luminance | 光亮度 | 数据 | number | 光亮度（cd/m²），HDR/LDR 自动适配。term=LUMINANCE 时与 Inspector 语义一致。 | - | 可选 |
term | 光度学单位 | 数据 | number | 光度学单位类型：0 = LUMINOUS_FLUX（光通量，流明 lm），1 = LUMINANCE（亮度，cd/m²）。切换单位语义，不自动换算旧值。 | - | 可选 |
size | 发光面尺寸 | 数据 | number | 发光面尺寸，范围 0～10。HDR 模式下影响 luminousFlux 与内部亮度换算。 | - | 可选 |
range | 光源范围 | 数据 | number | 聚光灯最大照射距离（世界单位）。数值越大覆盖范围越广，渲染开销越高。 | - | 可选 |
spotAngle | 锥角（度） | 数据 | number | 完整锥角（度），范围 2°～180°。组件层直观角度，非半角，非 cos(angle/2)。 | - | 可选 |
angleAttenuationStrength | 边缘衰减强度 | 数据 | number | 边缘衰减强度，范围 0～1。0 = 硬边，1 = 软边。 | - | 可选 |
shadowEnabled | 阴影开关 | 数据 | boolean | 阴影开关。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型：0=HARD, 1=SOFT, 2=SOFT_2X, 3=SOFT_4X。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
shadowNormalBias | 法线偏移 | 数据 | number | 法线方向阴影偏移，与 shadowBias 协同。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取阴影开关
获取阴影开关：返回聚光灯是否开启实时阴影投射。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetShadowEnabled |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowEnabled | 阴影开关 | 数据 | boolean | 阴影开关 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取阴影偏移
获取阴影偏移（shadowBias）：返回阴影深度偏移量，用于减少阴影痤疮（shadow acne）。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetShadowBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移 过大导致阴影悬浮（peter-panning），过小导致阴影条纹（acne）。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取锥角
获取锥角（spotAngle）：返回聚光灯的完整锥角（度，非半角）。 注意：组件层的 spotAngle 使用完整锥角（度）语义；它与底层 render-scene 的同名属性（返回 cos(angle / 2)）语义完全不同，请勿混淆。该节点始终读写组件层的直观角度值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightGetSpotAngle |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
spotAngle | 锥角（度） | 数据 | number | 完整锥角（度） 范围 2°～180°。这是组件层直观角度，不是半角，也不是 cos(angle/2)。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置 PCF 采样类型
设置 PCF 采样类型（shadowPcf）：设置聚光灯阴影的软阴影质量级别。 级别越高阴影越柔和，但渲染开销越大；在移动端建议使用 HARD 或 SOFT。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetShadowPcf |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型 0 = HARD（硬边缘） 1 = SOFT（基础软阴影） 2 = SOFT_2X（更平滑） 3 = SOFT_4X（最柔和） 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 下拉选择 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置边缘衰减强度
设置边缘衰减强度（angleAttenuationStrength）：设置聚光锥体边缘的衰减曲线强度。 范围 0～1；0 时边缘光照骤降、有硬边感；1 时边缘过渡更加柔和、自然。常与 spotAngle 一起调整来控制聚光的整体视觉特征。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetAngleAttenuationStrength |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
angleAttenuationStrength | 边缘衰减强度 | 数据 | number | 边缘衰减强度 最小值 0，最大值 1，步进 0.001。0 = 硬边，1 = 软边。 | 输入框 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置发光面尺寸
设置发光面尺寸（size）：设置聚光灯发光面的尺寸。 数值越大通常会让聚光边缘显得更柔和。注意： 在 HDR 模式下，size 会通过 nt2lm(size) 换算参与 luminousFlux 与内部亮度存储之间的转换；因此修改 size 后，相同光通量值所对应的实际发光强度可能发生变化，建议在调整 size 后重新确认亮度设置。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetSize |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
size | 发光面尺寸 | 数据 | number | 发光面尺寸 最小值 0，最大值 10，步进 0.001。HDR 模式下影响 luminousFlux 与内部亮度换算。 | 输入框 默认值：0.15 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置法线偏移
设置法线偏移（shadowNormalBias）：设置沿法线方向的阴影偏移量，与 shadowBias 共同作用以减少阴影痤疮与条纹伪影。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetShadowNormalBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
shadowNormalBias | 法线偏移 | 数据 | number | 法线偏移 步进 0.01。沿法线方向的阴影偏移，与 shadowBias 协同减少阴影痤疮。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 输入框 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置光度学单位
设置光度学单位（term）：切换聚光灯使用的光度学单位类型。 选项含义： • 0（LUMINOUS_FLUX）：切换为光通量模式，Inspector 展示 luminousFlux 字段 • 1（LUMINANCE）：切换为亮度模式，Inspector 展示 luminance 字段 注意： 切换 term 只改变 Inspector 展示与业务语义，不会自动对之前设置的数值进行物理换算；若需要在切换单位的同时保证视觉亮度一致，需要在脚本中手动重新设置对应字段的数值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetTerm |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
term | 光度学单位 | 数据 | number | 光度学单位类型 0 = LUMINOUS_FLUX，1 = LUMINANCE 切换单位语义，不自动换算旧值。 | 下拉选择 默认值：0 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置光亮度
设置光亮度（luminance）：设置聚光灯的亮度数值。 这是”单位面积光强度”的业务入口，当 term = LUMINANCE 时，该字段与 Inspector 展示保持一致。与 luminousFlux 的区别仅在于物理单位语义，底层渲染存储是共享的。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetLuminance |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
luminance | 光亮度 | 数据 | number | 光亮度（cd/m²） 最小值 0，步进 10。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。 | 输入框 默认值：1700 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置光通量
设置光通量（luminousFlux）：设置聚光灯的光通量数值（流明，lm）。 setter 会依据当前渲染管线 HDR 状态自动写入底层存储。默认值 1700 对应约 100W 白炽灯的光通量；值越大聚光越亮，但渲染开销也会因受光范围内对象数量而上升。 注意：HDR 模式下 setter 会通过 nt2lm(size) 换算，因此修改 size 会影响相同光通量对应的内部亮度分布。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetLuminousFlux |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
luminousFlux | 光通量 | 数据 | number | 光通量（流明 lm） 最小值 0，步进 100。HDR 模式下与 size 联动。 提示：选择”光通量”模式时使用流明（lm）调节亮度；选择”亮度”模式时使用 cd/m²。切换模式不会自动换算已有数值。 | 输入框 默认值：1700 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置光源范围
设置光源范围（range）：设置聚光灯的最大照射距离。 数值越大，聚光灯影响的渲染对象越多，整体光照覆盖范围也越广，但渲染开销也会随受光对象数量上升。建议在满足视觉效果的前提下尽量缩小范围，以降低逐像素光照开销。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetRange |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
range | 光源范围 | 数据 | number | 最大照射距离（世界单位） 最小值 0，步进 0.1。数值越大，影响范围越广，渲染开销越高。 | 输入框 默认值：1 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置全部属性
批量修改 SpotLight 全部属性：聚合写入 luminousFlux、luminance、term、size、range、spotAngle、angleAttenuationStrength、shadowEnabled、shadowPcf、shadowBias、shadowNormalBias。 说明：除 exe 与 spotLight 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开且有值的属性才参与写入；未公开属性保持原值不变。 注意： 建议先设置 term 以明确单位语义，再设置对应亮度字段；阴影相关属性需满足 ShadowMap 前置条件才有效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
luminousFlux | 光通量 | 数据 | number | 光通量（lm），term=LUMINOUS_FLUX 时最符合 Inspector 语义。 | 输入框 默认值：1700 | 可选 默认隐藏 |
luminance | 光亮度 | 数据 | number | 光亮度（cd/m²），term=LUMINANCE 时最符合 Inspector 语义。 | 输入框 默认值：1700 | 可选 默认隐藏 |
term | 光度学单位 | 数据 | number | 光度学单位：0 = LUMINOUS_FLUX，1 = LUMINANCE。切换单位语义，不自动换算旧值。 | 下拉选择 默认值：0 | 可选 默认隐藏 |
size | 发光面尺寸 | 数据 | number | 发光面尺寸，最小值 0，最大值 10，步进 0.001。 | 输入框 默认值：0.15 | 可选 默认隐藏 |
range | 光源范围 | 数据 | number | 最大照射距离（世界单位）。最小值 0，步进 0.1。 | 输入框 默认值：1 | 可选 默认隐藏 |
spotAngle | 锥角（度） | 数据 | number | 完整锥角（度），最小值 2°，最大值 180°，步进 1°。 | 输入框 默认值：60 | 可选 默认隐藏 |
angleAttenuationStrength | 边缘衰减强度 | 数据 | number | 边缘衰减强度，最小值 0，最大值 1，步进 0.001。 | 输入框 默认值：0 | 可选 默认隐藏 |
shadowEnabled | 阴影开关 | 数据 | boolean | 阴影开关。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 开关 默认值：false | 可选 默认隐藏 |
shadowPcf | PCF 采样类型 | 数据 | number | PCF 采样类型：0=HARD, 1=SOFT, 2=SOFT_2X, 3=SOFT_4X。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 下拉选择 默认值：0 | 可选 默认隐藏 |
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移，步进 0.00001。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 输入框 默认值：0.00001 | 可选 默认隐藏 |
shadowNormalBias | 法线偏移 | 数据 | number | 法线方向阴影偏移，步进 0.01。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 输入框 默认值：0 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置阴影开关
设置阴影开关：开启或关闭聚光灯的实时阴影投射。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetShadowEnabled |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
shadowEnabled | 阴影开关 | 数据 | boolean | 阴影开关 true 开启，false 关闭。提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 开关 默认值：false | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置阴影偏移
设置阴影偏移（shadowBias）：设置阴影深度偏移量，用于减少阴影痤疮。数值过大会导致阴影悬浮（peter-panning），过小会出现阴影条纹。建议从默认值 0.00001 开始微调。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetShadowBias |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
shadowBias | 阴影偏移 | 数据 | number | 阴影深度偏移 步进 0.00001。过大 → 悬浮，过小 → 条纹。 提示：需要先在项目设置中开启全局阴影（阴影类型设为 ShadowMap），实时阴影才会生效。 | 输入框 默认值：0.00001 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置锥角
设置锥角（spotAngle）：设置聚光灯的完整锥角（度）。 范围 2°～180°，值越小聚光越集中，值越大越发散。 注意：这是”完整锥角”而非”半角”；setter 内部会自动转为弧度写入底层渲染场景。底层 render-scene.spotAngle 返回的是 cos(angle / 2)，语义与此完全不同，请勿混淆。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | spotLightSetSpotAngle |
| 分类 | Cocos 组件 |
| 二级分类 | 灯光 |
| 分组 | SpotLight |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 要操作的聚光灯。聚光灯向特定方向发射锥形光束，像手电筒、舞台追光或探照灯——照亮一个圆锥区域。 | - | 必填 |
spotAngle | 锥角（度） | 数据 | number | 完整锥角（度） 最小值 2°，最大值 180°，步进 1°。组件层直观角度，非半角。 | 输入框 默认值：60 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
spotLight | 聚光灯 | 数据 | cc.Component / SpotLight | 目标 SpotLight 组件 透传当前操作的 SpotLight 组件，便于链式操作。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。