Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

ReflectionProbe

继承： VisualInstance3D < Node3D < Node < Object

捕捉某个位置周围的环境，用于快速创建准确的反射。

描述

将其周围环境捕捉为立方体贴图，并存储不同版本，其模糊级别递增以模拟不同的材质粗糙度。

ReflectionProbe 用于以低性能成本（当 update_mode 为 UPDATE_ONCE 时），创建高质量反射。ReflectionProbe 可以与场景的其余部分，平滑地混合在一起。ReflectionProbe 还可以与 VoxelGI、SDFGI（Environment.sdfgi_enabled）和屏幕空间反射（Environment.ssr_enabled）结合使用，以在特定区域获得更准确的反射。ReflectionProbe 渲染其 cull_mask 内的所有对象，因此更新它们可能会非常昂贵。最好仅用重要的静态对象更新一次，然后保持原样。

注意：与 VoxelGI 和 SDFGI 不同，ReflectionProbe 仅从一个 WorldEnvironment 节点获取环境。如果你在一个 Camera3D 节点中指定了一个 Environment 资源，它将被该 ReflectionProbe 忽略。这可能会导致 ReflectionProbe 内的照明不正确。

注意：反射探针仅支持 Forward+ 和 Mobile 渲染方法，不支持 Compatibility。使用移动渲染方法时，每个网格资源上最多只能显示 8 个反射探针。尝试在单个网格资源上显示 8 个以上的反射探针，将导致反射探针随着相机移动而闪烁。

注意：当使用移动渲染方法时，反射探针只会正确地影响可见 AABB 与反射探针的 AABB 相交的网格。如果使用着色器以使网格超出其 AABB 的方式变形该网格，则必须在网格上增加 GeometryInstance3D.extra_cull_margin。否则，反射探针可能在网格上不可见。

教程

属性

Color

ambient_color

Color(0, 0, 0, 1)

float

ambient_color_energy

1.0

AmbientMode

ambient_mode

1

bool

box_projection

false

int

cull_mask

1048575

bool

enable_shadows

false

float

intensity

1.0

bool

interior

false

float

max_distance

0.0

float

mesh_lod_threshold

1.0

Vector3

origin_offset

Vector3(0, 0, 0)

Vector3

size

Vector3(20, 20, 20)

UpdateMode

update_mode

0

枚举

enum UpdateMode:

UpdateMode UPDATE_ONCE = 0

在下一帧更新一次探针（建议大多数对象使用）。对应的辐照度贴图会在后续六帧中陆续生成。更新所花费的时间比 UPDATE_ALWAYS 多，但消耗的性能比它少、产生的反射质量也更高。ReflectionProbe 的变换发生变化时也会进行更新，但不会在周围几何体变化时更新。你可以通过将该 ReflectionProbe 在任意方向上进行小幅度移动来强制更新 ReflectionProbe。

UpdateMode UPDATE_ALWAYS = 1

每一帧都更新该探针。可以为快速移动的对象（如汽车）提供更好的结果。然而，带来的性能消耗也是显著的。因此，建议同一个场景中最多只使用一个 UPDATE_ALWAYS 的 ReflectionProbe。其他用途请使用 UPDATE_ONCE。

enum AmbientMode:

AmbientMode AMBIENT_DISABLED = 0

不在 ReflectionProbe 的大小为 size 的框内部应用环境光照。

AmbientMode AMBIENT_ENVIRONMENT = 1

在 ReflectionProbe 的大小为 size 的框内部应用自动来源的环境光照。

AmbientMode AMBIENT_COLOR = 2

在 ReflectionProbe 的大小为 size 的框内部应用自定义环境光照。见 ambient_color 和 ambient_color_energy。

属性说明

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

  • void set_ambient_color ( Color value )

  • Color get_ambient_color ( )

ReflectionProbe 的大小为 size 的框中使用的自定义环境光颜色。仅在 ambient_mode 为 AMBIENT_COLOR 时有效。

float ambient_color_energy = 1.0

  • void set_ambient_color_energy ( float value )

  • float get_ambient_color_energy ( )

ReflectionProbe 的大小为 size 的框中使用的自定义环境光颜色能量。仅在 ambient_mode 为 AMBIENT_COLOR 时有效。

AmbientMode ambient_mode = 1

ReflectionProbe 的大小为 size 的框中使用的环境光颜色。环境光颜色会和其他 ReflectionProbe 和场景（ReflectionProbe 的大小为 size 的框之外）的其他部分进行平滑混合。

bool box_projection = false

  • void set_enable_box_projection ( bool value )

  • bool is_box_projection_enabled ( )

为 true 时将启用箱体投影。通过根据相机的位置偏移反射中心，这使得在矩形房间中的反射看起来更正确。

注意：为了更好地适应未与网格对齐的区域，你可以旋转 ReflectionProbe 节点。

int cull_mask = 1048575

  • void set_cull_mask ( int value )

  • int get_cull_mask ( )

设置剔除掩码，该掩码确定该探针绘制的对象。每个 VisualInstance3D，若它有一个层被包含在该剔除掩码中，则它将由该探针渲染。为了提高性能，最好只包含可能在反射中占用大量空间的大型对象。

bool enable_shadows = false

  • void set_enable_shadows ( bool value )

  • bool are_shadows_enabled ( )

如果为 true，则在反射探测中计算阴影。这使得反射探针渲染更慢;如果想禁用它,可以使用 UPDATE_ALWAYS update_mode。

float intensity = 1.0

  • void set_intensity ( float value )

  • float get_intensity ( )

定义反射强度。

bool interior = false

  • void set_as_interior ( bool value )

  • bool is_set_as_interior ( )

如果为 true，则反射将忽略天空的贡献。

float max_distance = 0.0

  • void set_max_distance ( float value )

  • float get_max_distance ( )

对象在被剔除之前可以距该 ReflectionProbe 的最大距离。减少它可以提高性能，尤其是在使用 UPDATE_ALWAYS 作为 update_mode 时。

注意：最大反射距离始终至少等于探针的范围。这意味着减少 max_distance 并不总是会从反射中剔除对象，尤其是在反射探针由 size 定义的框已经很大的情况下。

float mesh_lod_threshold = 1.0

  • void set_mesh_lod_threshold ( float value )

  • float get_mesh_lod_threshold ( )

用于在 ReflectionProbe 内渲染网格的自动 LOD 偏置（这类似于 Viewport.mesh_lod_threshold）。较高的值将使用生成了 LOD 变化的不太详细的网格版本。如果设置为 0.0，则自动 LOD 将被禁用。增加 mesh_lod_threshold 以牺牲几何细节为代价提高性能，尤其是在使用 UPDATE_ALWAYS 的 update_mode 时。

注意：mesh_lod_threshold 不影响 GeometryInstance3D 可见性范围（也称为“手动”LOD 或分层 LOD）。

Vector3 origin_offset = Vector3(0, 0, 0)

  • void set_origin_offset ( Vector3 value )

  • Vector3 get_origin_offset ( )

设置当该 ReflectionProbe 处于 box_projection 模式时要使用的原点偏移量。这可以被设置为一个非零值，以确保反射适合矩形房间，同时减少“妨碍”反射的对象数量。

Vector3 size = Vector3(20, 20, 20)

反射探针的大小。大小越大，探针覆盖的空间就越大，这将降低感知的分辨率。最好将大小保持在需要的大小。

注意：为了更好地适应未与网格对齐的区域，可以旋转 ReflectionProbe 节点。

UpdateMode update_mode = 0

设置该 ReflectionProbe 的更新频率。可以是 UPDATE_ONCE 或 UPDATE_ALWAYS。