GIProbe

    Real-time global illumination (GI) probe.

    s are used to provide high-quality real-time indirect light to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. GIProbes need to be baked before using, however, once baked, dynamic objects will receive light from them. Further, lights can be fully dynamic or baked.

    Having GIProbes in a scene can be expensive, the quality of the probe can be turned down in exchange for better performance in the using ProjectSettings.rendering/quality/voxel_cone_tracing/high_quality.

    Procedural generation: GIProbe can be baked in an exported project, which makes it suitable for procedurally generated or user-built levels as long as all the geometry is generated in advance.

    Performance: GIProbe is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider instead). To provide a fallback for low-end hardware, consider adding an option to disable GIProbe in your project’s options menus. A GIProbe node can be disabled by hiding it.

    Note: Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. To further prevent light leaks, you can also strategically place temporary MeshInstance nodes with enabled. These temporary nodes can then be hidden after baking the GIProbe node.

    Note: Due to a renderer limitation, emissive ShaderMaterials cannot emit light when used in a GIProbe. Only emissive s can emit light in a GIProbe.

    Tutorials

    Methods

    void

    void

    debug_bake ( )

    enum Subdiv:

    • SUBDIV_64 = 0 —- Use 64 subdivisions. This is the lowest quality setting, but the fastest. Use it if you can, but especially use it on lower-end hardware.

    • SUBDIV_128 = 1 —- Use 128 subdivisions. This is the default quality setting.

    • SUBDIV_256 = 2 —- Use 256 subdivisions.

    • SUBDIV_512 = 3 —- Use 512 subdivisions. This is the highest quality setting, but the slowest. On lower-end hardware, this could cause the GPU to stall.

    • SUBDIV_MAX = 4 —- Represents the size of the Subdiv enum.

    Property Descriptions

    Default

    1.5

    Setter

    set_bias(value)

    Getter

    get_bias()

    Offsets the lookup of the light contribution from the GIProbe. This can be used to avoid self-shadowing, but may introduce light leaking at higher values. This and should be played around with to minimize self-shadowing and light leaking.

    Note: bias should usually be above 1.0 as that is the size of the voxels.

    Default

    false

    Setter

    set_compress(value)

    Getter

    is_compressed()

    Deprecated. This property has been deprecated due to known bugs and no longer has any effect when enabled.

    • data

    The GIProbeData resource that holds the data for this GIProbe.

    Default

    4

    Setter

    set_dynamic_range(value)

    Getter

    get_dynamic_range()

    The maximum brightness that the GIProbe will recognize. Brightness will be scaled within this range.

    • energy

    Default

    1.0

    Setter

    set_energy(value)

    get_energy()

    Energy multiplier. Makes the lighting contribution from the GIProbe brighter.

    Default

    Setter

    set_extents(value)

    Getter

    get_extents()

    The size of the area covered by the GIProbe. If you make the extents larger without increasing the subdivisions with , the size of each cell will increase and result in lower detailed lighting.

    If true, ignores the sky contribution when calculating lighting.

    • normal_bias

    Default

    0.0

    Setter

    set_normal_bias(value)

    Getter

    get_normal_bias()

    Offsets the lookup into the GIProbe based on the object’s normal direction. Can be used to reduce some self-shadowing artifacts.

    Default

    0.7

    Setter

    set_propagation(value)

    Getter

    get_propagation()

    How much light propagates through the probe internally. A higher value allows light to spread further.

    • subdiv

    Default

    1

    Setter

    set_subdiv(value)

    Getter

    get_subdiv()

    Number of times to subdivide the grid that the GIProbe operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance.

    • void bake ( from_node=null, bool create_visual_debug=false )

    Bakes the effect from all s marked with GeometryInstance.use_in_baked_light and s marked with either Light.BAKE_INDIRECT or . If create_visual_debug is true, after baking the light, this will generate a MultiMesh that has a cube representing each solid cell with each cube colored to the cell’s albedo color. This can be used to visualize the GIProbe‘s data and debug any issues that may be occurring.

    Note: works from the editor and in exported projects. This makes it suitable for procedurally generated or user-built levels. Baking a GIProbe generally takes from 5 to 20 seconds in most scenes. Reducing subdiv can speed up baking.

    • void debug_bake ( )

    Calls with create_visual_debug enabled.