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

ReflectionProbe

节点继承关系

继承链：Node → Node3D → VisualInstance3D → ReflectionProbe

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

定义

反射探针——在 3D 空间中放置一个"假相机"，它拍摄周围环境的画面，然后把这个画面作为反射贴图应用到附近的物体表面，让金属、水面、玻璃等材质看起来有真实的反射效果。

打个比方：想象你站在一个光亮的金属球旁边。你能看到金属球上映出了周围环境的倒影——蓝天、建筑、你自己。ReflectionProbe 就是那个"拍照的人"，它从金属球的位置拍一张 360 度的照片，然后贴到金属球上。

使用频率：★★ 偶尔使用——需要反射效果的场景使用。

节点用途

• 让金属材质物体产生环境反射
• 让水面产生反射效果
• 让玻璃、大理石等光滑表面产生真实反射
• 室内镜面反射

使用场景

典型场景

• 赛车游戏：车身上的环境反射
• 水面效果：湖面反射天空和周围建筑
• 金属物体：剑、盔甲、门把手上的高光反射
• 室内场景：大理石地板、玻璃窗的反射

不适用场景

• 2D 游戏 → 不支持
• 不需要反射的场景 → 不需要使用

常用节点搭配

搭配节点	用途	必需？
StandardMaterial3D（metallic > 0）	需要反射的材质	需要
WorldEnvironment	天空盒为反射提供内容	推荐

典型节点树：

Room (Node3D)
├── WorldEnvironment
├── ReflectionProbe    ← 在金属物体附近放置
├── Floor (MeshInstance3D)  ← 大理石地板
└── Armor (MeshInstance3D)  ← 金属盔甲

生效必备素材/资源

资源	类型	说明
环境（天空盒等）	Environment	为反射提供基础内容，没有天空反射就是黑色

节点属性与信号

反射设置

属性	类型	默认值	继承自	说明
update_mode	枚举	Once	—	更新模式。Once = 只拍一次（静态场景），Realtime = 实时更新（动态场景）
intensity	float	1.0	—	反射强度。1.0 = 正常，越大反射越强
max_distance	float	0.0	—	反射的最大影响范围。0 = 无限远
extents	Vector3	(10, 10, 10)	—	探针的覆盖范围大小
origin_offset	Vector3	(0, 0, 0)	—	探针中心的偏移
box_projection	bool	false	—	是否使用盒投影。开启后反射只在盒内生效，效果更精确
enable_shadows	bool	false	—	反射中是否包含阴影
ambient_mode	枚举	Environment	—	环境光模式

实时更新设置

属性	类型	默认值	继承自	说明
refresh_speed	float	0.0	—	实时更新的刷新速度
interior	bool	false	—	是否为室内探针。室内探针忽略天空盒

信号

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

常用方法

方法	返回值	说明
无特有方法	—	大部分操作通过属性控制

代码示例

C

using Godot;

/// <summary>
/// 反射探针管理器
/// 根据玩家位置动态启用/禁用反射探针以优化性能
/// </summary>
public partial class ReflectionProbeManager : Node
{
    [Export] private Node3D _player;
    [Export] public float ExEnableDistance = 50f;
    [Export] public float ExDisableDistance = 80f;

    private ReflectionProbe[] _probes;

    public override void _Ready()
    {
        _probes = GetParent().FindChildrenByType<ReflectionProbe>().ToArray();
    }

    public override void _PhysicsProcess(double delta)
    {
        foreach (var probe in _probes)
        {
            float dist = probe.GlobalPosition.DistanceTo(_player.GlobalPosition);

            // 根据距离启用或禁用反射探针
            if (dist < ExEnableDistance && !probe.Visible)
            {
                probe.Visible = true;
            }
            else if (dist > ExDisableDistance && probe.Visible)
            {
                probe.Visible = false;
            }
        }
    }
}

GDScript

## 反射探针管理器
## 根据玩家位置动态启用/禁用反射探针以优化性能
extends Node

@export var player: Node3D
@export var enable_distance: float = 50.0
@export var disable_distance: float = 80.0

var probes: Array[ReflectionProbe] = []

func _ready():
    probes.assign(get_parent().find_children("*", "ReflectionProbe", false, false))

func _physics_process(_delta: float):
    for probe in probes:
        var dist := probe.global_position.distance_to(player.global_position)

        # 根据距离启用或禁用反射探针
        if dist < enable_distance and not probe.visible:
            probe.visible = true
        elif dist > disable_distance and probe.visible:
            probe.visible = false

使用建议

• 室内场景开启 interior 属性，否则反射会包含不需要的天空
• 静态场景用 update_mode = Once（只拍一次），动态场景用 Realtime（实时更新）
• Realtime 模式很耗性能，尽量少用或设置合理的 refresh_speed
• 反射探针的 extents 不要设太大，覆盖需要的区域即可
• 放置探针时让它处于场景中最重要的反射物体附近