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

OmniLight3D

节点继承关系

继承链：Node → Node3D → Light3D → OmniLight3D

Light3D

类型	名称	说明
属性	LightColor	灯光颜色
属性	LightEnergy	灯光强度
属性	ShadowEnabled	是否开启阴影

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

定义

点光源/灯泡，从一个点向四面八方均匀发光。

就像一个裸露的灯泡挂在房间中央。离灯泡近的地方很亮，离得越远越暗，到一定距离后就完全照不到了。

使用频率：★★★★ 常用——室内场景和局部光照经常使用。

节点用途

• 模拟灯泡、蜡烛、火把等从一点向四周发光的光源
• 模拟爆炸闪光效果
• 模拟魔法球发光效果
• 作为室内场景的局部照明

使用场景

典型场景

• 房间里的灯泡：悬挂在天花板上，向四周均匀照射
• 地牢通道里的火把：发出橙红色的暖光
• 魔法球发光效果：发出蓝色或紫色的冷光
• 爆炸时的闪光：瞬间增强光照强度

不适用场景

• 照亮整个室外场景 → 使用 DirectionalLight3D
• 需要锥形照射区域 → 使用 SpotLight3D

常用节点搭配

搭配节点	用途	必需？
MeshInstance3D（灯泡模型）	视觉上显示灯泡/火把的外观	推荐
GPUParticles3D	火把的火焰粒子效果	可选

典型节点树：

Torch (Node3D)
├── MeshInstance3D       ← 火把的3D模型
├── OmniLight3D          ← 火把的灯光
└── GPUParticles3D       ← 火焰粒子效果

生效必备素材/资源

资源	类型	说明
灯泡/火把的 3D 模型	Mesh	赋给 MeshInstance3D，用于视觉展示

节点属性与信号

光照基础

属性	类型	默认值	继承自	说明
light_color	Color	白色	Light3D	光的颜色
light_energy	float	1.0	Light3D	光的强度
light_indirect_energy	float	1.0	Light3D	间接光照（反射光）的强度
light_volumetric_fog_energy	float	1.0	Light3D	体积雾受此光照影响的强度
light_specular	float	0.5	Light3D	镜面反射强度
light_size	float	0.0	Light3D	光源大小。值越大阴影越柔和（PCF 软阴影）

阴影设置

属性	类型	默认值	继承自	说明
shadow_enabled	bool	false	Light3D	是否开启阴影。点光源的阴影比较耗性能
shadow_color	Color	黑色	Light3D	阴影的颜色
shadow_blend	float	0.1	Light3D	阴影的混合程度
shadow_normal_bias	float	0.0	Light3D	阴影法线偏移
shadow_bias	float	0.02	Light3D	阴影偏移，减少阴影失真
shadow_reverse_cull_face	bool	false	Light3D	是否反转阴影背面剔除
shadow_transmittance_bias	float	0.0	Light3D	阴影透射偏移

点光源特有

属性	类型	默认值	继承自	说明
omni_range	float	5.0	—	光照范围。超过这个距离就完全没有光了
omni_attenuation	float	1.0	—	光的衰减系数。值越大，光衰减得越快（远处更暗）

信号

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

常用方法

方法	返回值	说明
（无自有方法，所有方法继承自 Light3D 和 Node3D）	—	—

代码示例

C

using Godot;

public partial class FlickeringTorch : OmniLight3D
{
    [Export] public float ExBaseEnergy = 1.5f;
    [Export] public float ExFlickerIntensity = 0.3f;
    [Export] public float ExFlickerSpeed = 10.0f;

    private double _time;

    public override void _Ready()
    {
        // 设置火把光的颜色（暖橙红色）
        LightColor = new Color(1.0f, 0.7f, 0.3f);

        // 设置光照范围
        OmniRange = 8.0f;

        // 设置衰减系数
        OmniAttenuation = 2.0f;

        // 不开启阴影（性能考虑，火把通常很多）
        ShadowEnabled = false;
    }

    public override void _Process(double delta)
    {
        _time += delta;

        // 模拟火把的闪烁效果
        // 使用正弦波叠加来模拟不规则的亮度变化
        var flicker = Mathf.Sin(_time * ExFlickerSpeed) * 0.5f
                    + Mathf.Sin(_time * ExFlickerSpeed * 2.7f) * 0.3f
                    + Mathf.Sin(_time * ExFlickerSpeed * 5.1f) * 0.2f;
        LightEnergy = ExBaseEnergy + flicker * ExFlickerIntensity;
    }
}

GDScript

extends OmniLight3D

@export var base_energy: float = 1.5
@export var flicker_intensity: float = 0.3
@export var flicker_speed: float = 10.0

var _time: float = 0.0

func _ready():
    # 设置火把光的颜色（暖橙红色）
    light_color = Color(1.0, 0.7, 0.3)

    # 设置光照范围
    omni_range = 8.0

    # 设置衰减系数
    omni_attenuation = 2.0

    # 不开启阴影（性能考虑，火把通常很多）
    shadow_enabled = false

func _process(delta):
    _time += delta

    # 模拟火把的闪烁效果
    # 使用正弦波叠加来模拟不规则的亮度变化
    var flicker = sin(_time * flicker_speed) * 0.5 \
                + sin(_time * flicker_speed * 2.7) * 0.3 \
                + sin(_time * flicker_speed * 5.1) * 0.2
    light_energy = base_energy + flicker * flicker_intensity

性能提示

OmniLight3D 开启阴影后比较耗性能（因为要渲染 6 个方向的阴影贴图）。如果场景中有很多 OmniLight3D，建议只对离玩家最近的几个开阴影，其他的关掉。