最后同步日期：2026-04-15 | Godot 官方原文 — VoxelGI

VoxelGI

节点继承关系

继承链：Node → Node3D → VisualInstance3D → VoxelGI

VisualInstance3D

类型	名称	说明
属性	Layers	渲染层（可视层掩码）
属性	SortingOffset	排序偏移

Node3D

类型	名称	说明
属性	Position	本地位置（X / Y / Z）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（欧拉角，弧度）
属性	Scale	缩放比例
属性	TopLevel	是否脱离父节点的变换
方法	LookAt()	朝向目标点
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标
方法	RotateX/Y/Z()	绕指定轴旋转

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

体素全局光照（Voxel Global Illumination）——把 3D 空间划分成大量小方块（体素），然后实时计算光线在这些方块之间的反弹，让场景中的光影更加真实。

打个比方：想象你在一个房间中间开了一盏红色的灯。光照到白色的墙上，墙壁会反射出红色光，这束反射的红色光又照到旁边的桌子，桌子也微微泛红。VoxelGI 就是自动计算这种"光线反弹"效果的节点。

使用频率：★★ 偶尔使用——需要高质量实时光照的场景使用，性能消耗较大。

节点用途

• 实时计算间接光照（光线反弹）
• 让场景中的彩色光线互相影响
• 动态光照变化时的实时更新（如开关灯）

使用场景

典型场景

• 室内场景：房间中开关灯时，墙壁反射的光实时变化
• 彩色灯光：红色灯光照到白色墙上产生红色反射
• 动态环境：场景中有可移动的光源

不适用场景

• 静态场景且追求最佳性能 → 使用 LightmapGI（预烘焙，性能更好）
• 2D 游戏 → 不支持
• 移动端 → 性能消耗过大，不推荐

常用节点搭配

搭配节点	用途	必需？
DirectionalLight3D / OmniLight3D	光源	推荐
MeshInstance3D（带几何体）	场景物体	推荐

典型节点树：

Room (Node3D)
├── WorldEnvironment
├── VoxelGI               ← 体素全局光照
├── DirectionalLight3D
├── OmniLight3D           ← 可开关的灯
└── RoomMesh (MeshInstance3D)

生效必备素材/资源

资源	类型	说明
VoxelGIData	Resource	通过子化（Bake）生成，存储体素化后的光照数据

节点属性与信号

体素化设置

属性	类型	默认值	继承自	说明
voxel_size	float	0.25	—	体素大小。越小越精细但越耗性能和内存
resolution	Vector3i	(128, 128, 128)	—	体素分辨率，覆盖区域的网格数
subdiv	枚举	Subdiv2	—	细分级别。Subdiv4 = 64^3，Subdiv5 = 128^3，Subdiv6 = 256^3
use_dynamic_range	bool	true	—	是否使用动态范围

渲染质量

属性	类型	默认值	继承自	说明
bias	float	1.5	—	偏移值，减少光照漏光
normal_bias	float	0.0	—	法线偏移
propagation	float	0.5	—	光线传播距离，值越大光照反弹越远

信号

信号	触发时机	继承自	说明
无自有信号	—	—	VoxelGI 自身不发出信号

常用方法

方法	返回值	说明
Bake()	void	执行烘焙，计算体素光照数据
DebugBake()	void	调试烘焙，可视化体素数据

代码示例

C

using Godot;

/// <summary>
/// 房间灯光控制器
/// 配合 VoxelGI 实现开关灯时的实时光照变化
/// </summary>
public partial class RoomLightController : Node
{
    [Export] private OmniLight3D _roomLight;
    [Export] private VoxelGI _voxelGI;

    private bool _lightOn = true;

    public void ToggleLight()
    {
        _lightOn = !_lightOn;
        _roomLight.LightEnergy = _lightOn ? 2.0f : 0.0f;
    }
}

GDScript

## 房间灯光控制器
## 配合 VoxelGI 实现开关灯时的实时光照变化
extends Node

@export var room_light: OmniLight3D
@export var voxel_gi: VoxelGI

var light_on: bool = true

func toggle_light():
    light_on = !light_on
    room_light.light_energy = 2.0 if light_on else 0.0

VoxelGI vs LightmapGI

• VoxelGI：实时计算，适合动态光源，但性能消耗大
• LightmapGI：预烘焙（提前算好），运行时零消耗，但只适合静态场景
• 如果你的场景光源不会变化，优先用 LightmapGI
• 如果需要开关灯等动态效果，用 VoxelGI 或两者结合