使用指南
Cocos 组件 / 渲染 / LightProbeGroup节点
Cocos 组件 / 渲染 / LightProbeGroup 节点手册，包含 16 个节点的用途、引脚、使用场景和注意事项。
16
学习目标
访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。
覆盖范围
- 节点数量：16
- 分类路径：Cocos 组件 / 渲染 / LightProbeGroup
典型使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
通用注意事项
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
- 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。
节点索引
| 节点 | 节点 ID | 输入/输出 | 执行方式 |
|---|---|---|---|
| 获取 X 方向探针数 | lightProbeGroupGetNProbesX | 1 / 1 | 立即继续 |
| 获取 Y 方向探针数 | lightProbeGroupGetNProbesY | 1 / 1 | 立即继续 |
| 获取 Z 方向探针数 | lightProbeGroupGetNProbesZ | 1 / 1 | 立即继续 |
| 获取包围盒最大值 | lightProbeGroupGetMaxPos | 1 / 1 | 立即继续 |
| 获取包围盒最小值 | lightProbeGroupGetMinPos | 1 / 1 | 立即继续 |
| 获取全部属性 | lightProbeGroupGetProperties | 1 / 7 | 立即继续 |
| 获取生成方式 | lightProbeGroupGetMethod | 1 / 1 | 立即继续 |
| 获取探针数组 | lightProbeGroupGetProbes | 1 / 1 | 立即继续 |
| 设置 X 方向探针数 | lightProbeGroupSetNProbesX | 3 / 2 | 立即继续 |
| 设置 Y 方向探针数 | lightProbeGroupSetNProbesY | 3 / 2 | 立即继续 |
| 设置 Z 方向探针数 | lightProbeGroupSetNProbesZ | 3 / 2 | 立即继续 |
| 设置包围盒最大值 | lightProbeGroupSetMaxPos | 3 / 2 | 立即继续 |
| 设置包围盒最小值 | lightProbeGroupSetMinPos | 3 / 2 | 立即继续 |
| 设置全部属性 | lightProbeGroupSetProperties | 7 / 2 | 立即继续 |
| 生成光照探针 | lightProbeGroupGenerateLightProbes | 2 / 2 | 立即继续 |
| 探针变化同步 | lightProbeGroupOnProbeChanged | 4 / 2 | 立即继续 |
获取 X 方向探针数
获取 X 方向探针数量：返回包围盒 X 轴（世界空间的水平方向）上的探针采样点数。范围 265535，默认 3。
三个方向的探针数相乘就是探针总数。默认 3×3×3=27 个探针。探针越多，间接光照越细腻，但计算量也越大。对于大多数中小型场景，每个方向 310 个探针通常足够。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetNProbesX |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
nProbesX | X 方向探针数 | 数据 | number | X 方向探针数量 包围盒 X 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取 Y 方向探针数
获取 Y 方向探针数量：返回包围盒 Y 轴（世界空间的高度方向）上的探针采样点数。范围 2~65535，默认 3。 Y 方向控制垂直空间的探针密度。如果你的场景是多层建筑或有高低差的地形，需要更多 Y 向探针来捕捉不同高度的光照变化。平面场景（如俯视角游戏）保持较小值即可。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetNProbesY |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
nProbesY | Y 方向探针数 | 数据 | number | Y 方向探针数量 包围盒 Y 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取 Z 方向探针数
获取 Z 方向探针数量：返回包围盒 Z 轴（世界空间的深度方向）上的探针采样点数。范围 2~65535，默认 3。 Z 方向和 X 方向一起决定了地面平面上的探针网格密度。两个方向的数值通常保持一致，除非场景在一个方向上明显更长。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetNProbesZ |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
nProbesZ | Z 方向探针数 | 数据 | number | Z 方向探针数量 包围盒 Z 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取包围盒最大值
获取包围盒最大角坐标：返回探针生成范围的最大角位置。默认值为 (5, 5, 5)，与默认最小角 (-5, -5, -5) 围成一个 10×10×10 的立方体空间。 包围盒决定了光照探针的覆盖范围。原则很简单：包围盒越大，覆盖的场景区域越多，但在探针总数不变的情况下，每个探针之间的间距也越大，细节精度会下降。反之，包围盒越小精度越高，但覆盖不全。调整时应在”覆盖范围”和”采样精度”之间取平衡。 修改包围盒后，需要执行 生成光照探针 才会按新范围重新放置探针。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetMaxPos |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
maxPos | 包围盒最大值 | 数据 | vector3 | 包围盒最大值 探针生成范围的最大角坐标。 默认值 (5, 5, 5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取包围盒最小值
获取包围盒最小角坐标：返回探针生成范围的最小角位置。默认值为 (-5, -5, -5)，即世界原点周围 10×10×10 范围的一个角。 包围盒是一个虚拟的长方体空间，由最小角和最大角共同确定。所有光照探针都在这个长方体内部均匀分布。调整包围盒就是在调整”哪些区域需要计算间接光照”——把包围盒放在场景中动态物体可能出现的区域即可。 修改包围盒范围后，需要执行 生成光照探针 才会按新范围重新放置探针。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetMinPos |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
minPos | 包围盒最小值 | 数据 | vector3 | 包围盒最小值 探针生成范围的最小角坐标。 默认值 (-5, -5, -5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取全部属性
一次性读取 LightProbeGroup 全部配置：同时输出 7 个属性——探针位置列表、生成方式、包围盒两个角、三个方向的密度。 当你需要了解当前光照探针组的完整状态时，用这个节点比逐个连接 7 个单独节点更方便。拿到全部数据后，可以根据需要用后续节点只处理你关心的属性。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
probes | 探针数组 | 数据 | vector3 / array | 探针位置列表 当前生成的所有光照探针三维位置数组。 探针位置由 生成光照探针 根据包围盒范围和密度自动计算得出。 | - | 可选 |
method | 生成方式 | 数据 | number | 探针生成方式 0=UNIFORM（均匀生成）：在包围盒内等间距排列探针 1=ADAPTIVE（自适应生成）：预留的智能放置模式，当前版本与均匀生成效果相同 该属性为只读，不能在游戏运行时通过节点修改。 | - | 可选 |
minPos | 包围盒最小值 | 数据 | vector3 | 包围盒最小值 探针生成范围的最小角坐标。 默认值 (-5, -5, -5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
maxPos | 包围盒最大值 | 数据 | vector3 | 包围盒最大值 探针生成范围的最大角坐标。 默认值 (5, 5, 5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
nProbesX | X 方向探针数 | 数据 | number | X 方向探针数量 包围盒 X 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
nProbesY | Y 方向探针数 | 数据 | number | Y 方向探针数量 包围盒 Y 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
nProbesZ | Z 方向探针数 | 数据 | number | Z 方向探针数量 包围盒 Z 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取生成方式
获取探针生成方式：返回当前的探针放置策略。 0 = 均匀生成（UNIFORM）：在包围盒内按等间距排列探针，简单稳定，是默认的生成方式。 1 = 自适应生成（ADAPTIVE）：预留给未来的智能放置策略——会根据场景形状自动调整探针位置。 注意： 该属性为只读，不能在游戏运行时通过节点修改。如需切换生成方式，请在编辑器中选中 LightProbeGroup 组件，在属性面板中修改。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetMethod |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
method | 生成方式 | 数据 | number | 探针生成方式 0=UNIFORM（均匀生成）：在包围盒内等间距排列探针 1=ADAPTIVE（自适应生成）：预留的智能放置模式，当前版本与均匀生成效果相同 该属性为只读，不能在游戏运行时通过节点修改。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
获取探针数组
获取探针位置列表：返回当前光照探针组生成的所有探针三维位置数组。光照探针是场景中预先计算好的采样点，引擎根据这些采样点的亮度信息，为附近的动态物体（如移动的角色）提供逼真的间接光照效果。 探针位置由 生成光照探针 节点根据你配置的包围盒范围和三个方向的密度自动计算得出。如果尚未调用生成操作，这里返回的是空列表。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGetProbes |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
probes | 探针数组 | 数据 | vector3 / array | 探针位置列表 当前生成的所有光照探针三维位置数组。 探针位置由 生成光照探针 根据包围盒范围和密度自动计算得出。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置 X 方向探针数
设置 X 方向探针数量：调整包围盒 X 轴（水平方向）上的探针密度。范围 2~65535，默认 3，最少需要 2 个点。 探针总数 = 三个方向数量的乘积。例如 5×3×5 = 75 个探针。数值越大间接光照越精细，但计算开销也越大。建议先在编辑器中测试效果再确定合适的值。修改后需要执行 生成光照探针 才会应用新密度。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupSetNProbesX |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
nProbesX | X 方向探针数 | 数据 | number | X 方向探针数量 包围盒 X 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 输入框 默认值：3 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置 Y 方向探针数
设置 Y 方向探针数量：调整包围盒 Y 轴（高度方向）上的探针密度。范围 265535，默认 3，最少需要 2 个点。
高度方向的探针密度需要根据场景来定：平面场景（俯视角游戏）设 23 即可；多层建筑或多层平台场景应适当增大，确保每一层都有探针覆盖。修改后需要执行 生成光照探针 才会应用新密度。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupSetNProbesY |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
nProbesY | Y 方向探针数 | 数据 | number | Y 方向探针数量 包围盒 Y 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 输入框 默认值：3 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置 Z 方向探针数
设置 Z 方向探针数量：调整包围盒 Z 轴（深度方向）上的探针密度。范围 2~65535，默认 3，最少需要 2 个点。 三个方向的密度应该协调配置。举例：10×3×10 适合宽扁的户外场景（水平方向密集、垂直方向稀疏），5×5×5 适合立体的室内场景（三轴均匀）。修改后需要执行 生成光照探针 才会应用新密度。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupSetNProbesZ |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
nProbesZ | Z 方向探针数 | 数据 | number | Z 方向探针数量 包围盒 Z 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 输入框 默认值：3 | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置包围盒最大值
设置包围盒最大角坐标：修改探针生成空间的另一个角的位置。默认值 (5, 5, 5)，通常应该比最小角的值大。 属性修改后会立刻保存，但已有的探针位置不会自动更新。推荐的配置流程是：先把两个角和三个方向的密度都设好，最后调用一次 生成光照探针 统一生成。如果改了包围盒却忘了重新生成，场景中的物体会继续使用旧探针数据，导致间接光照效果不正确。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupSetMaxPos |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
maxPos | 包围盒最大值 | 数据 | vector3 | 包围盒最大值 探针生成范围的最大角坐标。 默认值 (5, 5, 5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 可编辑控件 默认值：{“x”:5,“y”:5,“z”:5} | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置包围盒最小值
设置包围盒最小角坐标：修改探针生成空间的一个角的位置。默认值 (-5, -5, -5)，通常应该比最大角的值小。 属性修改后会立刻保存，但已有的探针位置不会自动更新。推荐的配置流程是：先把包围盒的两个角、三个方向的密度都设好，最后调用一次 生成光照探针 统一生成。如果改了包围盒却忘了重新生成，场景中的物体仍然会使用旧的探针数据，可能导致间接光照效果不正确。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupSetMinPos |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
minPos | 包围盒最小值 | 数据 | vector3 | 包围盒最小值 探针生成范围的最小角坐标。 默认值 (-5, -5, -5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 可编辑控件 默认值：{“x”:-5,“y”:-5,“z”:-5} | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
设置全部属性
批量修改 LightProbeGroup 配置：一次性写入包围盒两个角的位置和三个方向的密度，共 5 个属性。 默认情况下，每个属性输入引脚是隐藏的。在画布上点击你想修改的属性引脚旁的”公开”按钮，它才会显示出来并参与写入；不公开的属性保持原值不变——这样你可以只改需要改的字段，不用关心其他属性。 注意： 这个节点只修改属性值，不会自动生成探针。修改包围盒或密度之后，别忘了再执行 生成光照探针 才会真正更新场景中的探针位置和间接光照效果。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupSetProperties |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
minPos | 包围盒最小值 | 数据 | vector3 | 包围盒最小值 探针生成范围的最小角坐标。 默认值 (-5, -5, -5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 可编辑控件 默认值：{“x”:-5,“y”:-5,“z”:-5} | 可选 默认隐藏 |
maxPos | 包围盒最大值 | 数据 | vector3 | 包围盒最大值 探针生成范围的最大角坐标。 默认值 (5, 5, 5)。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 可编辑控件 默认值：{“x”:5,“y”:5,“z”:5} | 可选 默认隐藏 |
nProbesX | X 方向探针数 | 数据 | number | X 方向探针数量 包围盒 X 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 输入框 默认值：3 | 可选 默认隐藏 |
nProbesY | Y 方向探针数 | 数据 | number | Y 方向探针数量 包围盒 Y 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 输入框 默认值：3 | 可选 默认隐藏 |
nProbesZ | Z 方向探针数 | 数据 | number | Z 方向探针数量 包围盒 Z 轴方向的探针采样点数。 范围 [2, 65535]，默认值 3。修改后需要执行 生成光照探针 才会更新实际探针位置。 | 输入框 默认值：3 | 可选 默认隐藏 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
生成光照探针
自动生成光照探针：根据当前配置（包围盒范围、三个方向的密度、生成方式）自动计算出所有探针的三维位置并保存。 执行后会有两个效果：① 探针位置数组被更新为新的采样点网格；② 场景中的间接光照数据自动刷新，所有使用光照探针的物体会立即看到变化。 典型用法：先通过一系列设置节点配置好包围盒范围和密度，最后执行一次 生成光照探针 完成所有更新。不需要在每次修改属性后都生成——攒到一起最后生成一次即可。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupGenerateLightProbes |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
探针变化同步
手动同步探针数据：如果你通过其他方式（如脚本代码）直接修改了探针位置，用这个节点来通知场景”探针数据已变更”，让引擎刷新间接光照。 两个参数都是开关（勾选 = true，不勾选 = false）：更新四面体（默认开启）——用于重建内部的快速查找结构，一般保持开启即可；发射事件（默认开启）——通知其他系统刷新显示，一般也保持开启。 注意： 大多数情况下你不需要手动调用这个节点——生成光照探针 节点内部已经自动完成了同步。只有在你用脚本等方式绕过工作流直接改了探针数据时，才需要手动同步。
节点信息
| 字段 | 值 |
|---|---|
| 节点 ID | lightProbeGroupOnProbeChanged |
| 分类 | Cocos 组件 |
| 二级分类 | 渲染 |
| 分组 | LightProbeGroup |
| 是否需要等待结果 | 否 |
| 是否需要先选择目标 | 否 |
输入引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
exe | - | 执行流 | 执行流 | 执行入口 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 要操作的光照探针组组件。 它负责定义探针的生成范围、密度，并自动生成探针位置数据。 | - | 必填 |
updateTet | 更新四面体 | 数据 | boolean | 刷新内部查找结构 探针数据变更后，是否刷新内部的快速查找结构。 默认开启。普通使用时保持默认即可，无需修改。 | 开关 默认值：true | 可选 |
emitEvent | 发射事件 | 数据 | boolean | 通知场景其他系统 探针数据变更后，是否通知场景中的其他系统（如调试面板）刷新显示。 默认开启。普通使用时保持默认即可，无需修改。 | 开关 默认值：true | 可选 |
输出引脚
| 引脚 ID | 名称 | 连接方式 | 值类型 | 用途 | 默认或选择 | 连接要求 |
|---|---|---|---|---|---|---|
out | - | 执行流 | 执行流 | 执行完成 | - | 可选 |
lightProbeGroup | 光照探针组 | 数据 | cc.Component / LightProbeGroup | 目标 LightProbeGroup 组件 透传当前操作的 LightProbeGroup 组件。 将此端口连接到下一个节点后，可以继续对同一个组件进行操作，无需重新指定目标。 | - | 可选 |
使用场景
- 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
- 读取组件状态后驱动游戏逻辑
- 批量设置组件属性完成游戏运行时效果
注意事项
- 适合的工作流类型：component、library、method、function、class。
- 目标组件引脚必须连接正确的组件实例。
- 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。