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

LightmapGI

节点继承关系

继承链：Node → Node3D → VisualInstance3D → LightmapGI

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()	获取父节点

定义

光照贴图全局光照——提前把场景中的光影信息"画"成贴图，运行时直接贴到物体表面，不再需要实时计算。

打个比方：VoxelGI 像现场直播，每时每刻都在计算光影；LightmapGI 像拍一张照片，提前把光影效果拍好存起来，游戏运行时直接展示这张"照片"。

使用频率：★★ 偶尔使用——静态场景的标准光照方案。

节点用途

• 预烘焙静态场景的光照
• 获得高质量的间接光照效果
• 运行时零性能消耗（因为光照已经提前算好了）

使用场景

典型场景

• 室内关卡：建筑、走廊、房间等不会移动的场景
• 城市街道：固定的建筑和道路
• 静态室外场景：不会变化的室外环境

不适用场景

• 场景中有大量动态光源 → 使用 VoxelGI
• 2D 游戏 → 不支持

常用节点搭配

搭配节点	用途	必需？
各种 Light3D	提供光照	推荐
MeshInstance3D	接收和投射光照的物体	推荐

典型节点树：

Level (Node3D)
├── LightmapGI              ← 光照烘焙
├── DirectionalLight3D
├── Building (MeshInstance3D)  ← 参与烘焙
└── Ground (MeshInstance3D)    ← 参与烘焙

生效必备素材/资源

节点属性	类型	说明
LightmapGIData	Resource	烘焙后生成的数据，存储光照贴图

节点属性与信号

烘焙设置

属性	类型	默认值	继承自	说明
bake_quality	枚举	Medium	—	烘焙质量。Low/Medium/High/Ultra，质量越高耗时越长
bake_time	float	10.0	—	最大烘焙时间（秒）
max_texture_size	int	1024	—	光照贴图最大分辨率

信号

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

常用方法

方法	返回值	说明
Bake()	void	执行光照烘焙
DebugBake()	void	调试烘焙
Clear()	void	清除烘焙数据

代码示例

C

using Godot;

/// <summary>
/// 关卡烘焙工具
/// 在编辑器模式下一键烘焙场景光照
/// </summary>
#if TOOLS
[Tool]
public partial class LevelBaker : EditorPlugin
{
    public override void _EnterTree()
    {
        AddToolMenuItem("烘焙场景光照", new Callable(this, MethodName.BakeScene));
    }

    private void BakeScene()
    {
        var lightmapGI = GetViewport()
            .FindChildrenByType<LightmapGI>()
            .FirstOrDefault();

        if (lightmapGI != null)
        {
            GD.Print("开始烘焙光照...");
            lightmapGI.Bake();
            GD.Print("烘焙完成！");
        }
        else
        {
            GD.PrintErr("场景中未找到 LightmapGI 节点");
        }
    }
}
#endif

GDScript

## 关卡烘焙工具
## 在编辑器模式下一键烘焙场景光照
@tool
extends EditorPlugin

func _enter_tree():
    add_tool_menu_item("烘焙场景光照", _bake_scene)

func _bake_scene():
    var lightmap_gis := get_viewport().find_children("*", "LightmapGI", false, false)
    if lightmap_gis.size() > 0:
        print("开始烘焙光照...")
        lightmap_gis[0].bake()
        print("烘焙完成！")
    else:
        push_error("场景中未找到 LightmapGI 节点")

使用建议

• 烘焙前确保场景中的 MeshInstance3D 设置了正确的 gi_mode 属性
• 需要参与烘焙的物体设置 Static 或 Static with Lightmap
• 烘焙是编辑器操作，不需要在游戏运行时执行
• 烘焙质量 High 或 Ultra 适合最终发布，开发阶段用 Low 或 Medium 节省时间