Table of Contents

Class ReflectionProbe

Captures its surroundings to create fast, accurate reflections from a given point.

Inheritance
ReflectionProbe

Remarks

Captures its surroundings as a cubemap, and stores versions of it with increasing levels of blur to simulate different material roughnesses.

The ReflectionProbe is used to create high-quality reflections at a low performance cost (when update_mode is ReflectionProbe.UPDATE_ONCE). ReflectionProbes can be blended together and with the rest of the scene smoothly. ReflectionProbes can also be combined with VoxelGI, SDFGI (sdfgi_enabled) and screen-space reflections (ssr_enabled) to get more accurate reflections in specific areas. ReflectionProbes render all objects within their cull_mask, so updating them can be quite expensive. It is best to update them once with the important static objects and then leave them as-is.

Note: Unlike VoxelGI and SDFGI, ReflectionProbes only source their environment from a WorldEnvironment node. If you specify an Environment resource within a Camera3D node, it will be ignored by the ReflectionProbe. This can lead to incorrect lighting within the ReflectionProbe.

Note: Reflection probes are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 reflection probes can be displayed on each mesh resource. Attempting to display more than 8 reflection probes on a single mesh resource will result in reflection probes flickering in and out as the camera moves.

Note: When using the Mobile rendering method, reflection probes will only correctly affect meshes whose visibility AABB intersects with the reflection probe's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, extra_cull_margin must be increased on the mesh. Otherwise, the reflection probe may not be visible on the mesh.

See Also

Reflection probes

Properties

ambient_color

The custom ambient color to use within the ReflectionProbe's box defined by its size. Only effective if ambient_mode is ReflectionProbe.AMBIENT_COLOR.

var ambient_color : Color = Color(0, 0, 0, 1)

Property Value

Color

Remarks

  • void set_ambient_color(Color value)
  • Color get_ambient_color

ambient_color_energy

The custom ambient color energy to use within the ReflectionProbe's box defined by its size. Only effective if ambient_mode is ReflectionProbe.AMBIENT_COLOR.

var ambient_color_energy : float = 1.0

Property Value

float

Remarks

  • void set_ambient_color_energy(float value)
  • float get_ambient_color_energy

ambient_mode

The ambient color to use within the ReflectionProbe's box defined by its size. The ambient color will smoothly blend with other ReflectionProbes and the rest of the scene (outside the ReflectionProbe's box defined by its size).

var ambient_mode : int = 1

Property Value

int

Remarks

  • void set_ambient_mode(int value)
  • int get_ambient_mode

blend_distance

Defines the distance in meters over which a probe blends into the scene.

var blend_distance : float = 1.0

Property Value

float

Remarks

  • void set_blend_distance(float value)
  • float get_blend_distance

box_projection

If true, enables box projection. This makes reflections look more correct in rectangle-shaped rooms by offsetting the reflection center depending on the camera's location.

Note: To better fit rectangle-shaped rooms that are not aligned to the grid, you can rotate the ReflectionProbe node.

var box_projection : bool = false

Property Value

bool

Remarks

  • void set_enable_box_projection(bool value)
  • bool is_box_projection_enabled

cull_mask

Sets the cull mask which determines what objects are drawn by this probe. Every VisualInstance3D with a layer included in this cull mask will be rendered by the probe. It is best to only include large objects which are likely to take up a lot of space in the reflection in order to save on rendering cost.

This can also be used to prevent an object from reflecting upon itself (for instance, a ReflectionProbe centered on a vehicle).

var cull_mask : int = 1048575

Property Value

int

Remarks

  • void set_cull_mask(int value)
  • int get_cull_mask

enable_shadows

If true, computes shadows in the reflection probe. This makes the reflection probe slower to render; you may want to disable this if using the ReflectionProbe.UPDATE_ALWAYS update_mode.

var enable_shadows : bool = false

Property Value

bool

Remarks

  • void set_enable_shadows(bool value)
  • bool are_shadows_enabled

intensity

Defines the reflection intensity. Intensity modulates the strength of the reflection.

var intensity : float = 1.0

Property Value

float

Remarks

  • void set_intensity(float value)
  • float get_intensity

interior

If true, reflections will ignore sky contribution.

var interior : bool = false

Property Value

bool

Remarks

  • void set_as_interior(bool value)
  • bool is_set_as_interior

max_distance

The maximum distance away from the ReflectionProbe an object can be before it is culled. Decrease this to improve performance, especially when using the ReflectionProbe.UPDATE_ALWAYS update_mode.

Note: The maximum reflection distance is always at least equal to the probe's extents. This means that decreasing max_distance will not always cull objects from reflections, especially if the reflection probe's box defined by its size is already large.

var max_distance : float = 0.0

Property Value

float

Remarks

  • void set_max_distance(float value)
  • float get_max_distance

mesh_lod_threshold

The automatic LOD bias to use for meshes rendered within the ReflectionProbe (this is analog to mesh_lod_threshold). Higher values will use less detailed versions of meshes that have LOD variations generated. If set to 0.0, automatic LOD is disabled. Increase mesh_lod_threshold to improve performance at the cost of geometry detail, especially when using the ReflectionProbe.UPDATE_ALWAYS update_mode.

Note: mesh_lod_threshold does not affect GeometryInstance3D visibility ranges (also known as "manual" LOD or hierarchical LOD).

var mesh_lod_threshold : float = 1.0

Property Value

float

Remarks

  • void set_mesh_lod_threshold(float value)
  • float get_mesh_lod_threshold

origin_offset

Sets the origin offset to be used when this ReflectionProbe is in box_projection mode. This can be set to a non-zero value to ensure a reflection fits a rectangle-shaped room, while reducing the number of objects that "get in the way" of the reflection.

var origin_offset : Vector3 = Vector3(0, 0, 0)

Property Value

Vector3

Remarks

reflection_mask

Sets the reflection mask which determines what objects have reflections applied from this probe. Every VisualInstance3D with a layer included in this reflection mask will have reflections applied from this probe. See also cull_mask, which can be used to exclude objects from appearing in the reflection while still making them affected by the ReflectionProbe.

var reflection_mask : int = 1048575

Property Value

int

Remarks

  • void set_reflection_mask(int value)
  • int get_reflection_mask

size

The size of the reflection probe. The larger the size, the more space covered by the probe, which will lower the perceived resolution. It is best to keep the size only as large as you need it.

Note: To better fit areas that are not aligned to the grid, you can rotate the ReflectionProbe node.

var size : Vector3 = Vector3(20, 20, 20)

Property Value

Vector3

Remarks

update_mode

Sets how frequently the ReflectionProbe is updated. Can be ReflectionProbe.UPDATE_ONCE or ReflectionProbe.UPDATE_ALWAYS.

var update_mode : int = 0

Property Value

int

Remarks

  • void set_update_mode(int value)
  • int get_update_mode