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

PointLight2D

节点继承关系

继承链：Node → CanvasItem → Node2D → Light2D → PointLight2D

Light2D

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

Node2D

类型	名称	说明
属性	Position	本地位置（相对于父节点）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（弧度）
属性	Scale	缩放比例
属性	Skew	倾斜角度（弧度）
方法	Rotate()	旋转指定弧度
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

2D 点光源，从一个点向四周发光的 2D 光源。

2D 世界里的蜡烛或灯泡。光从一个中心点向四周扩散，越远越暗，到一定距离后完全消失。

使用频率：★★★★ 常用——需要 2D 光影效果的 2D 游戏中经常使用。

节点用途

• 模拟蜡烛、灯泡、火把等局部光源
• 模拟爆炸闪光
• 模拟魔法发光效果
• 创造氛围光效（暖色灯光、冷色月光等）

使用场景

典型场景

• 2D 地牢游戏：火把和蜡烛照亮黑暗的走廊
• 2D 恐怖游戏：手电筒照亮周围一小片区域
• 2D RPG：村庄里的路灯、房间里的灯光
• 2D 潜行游戏：利用光照范围做敌人视野检测

不适用场景

• 需要 2D 全局均匀光照 → 使用 DirectionalLight2D
• 3D 场景光照 → 使用 OmniLight3D

常用节点搭配

搭配节点	用途	必需？
LightOccluder2D	遮挡体，让物体在光照下产生阴影	推荐
Sprite2D	显示灯泡/蜡烛的图片	推荐
GPUParticles2D	火焰粒子效果	可选

典型节点树：

Torch (Node2D)
├── Sprite2D             ← 火把的图片
├── PointLight2D         ← 火把的灯光
└── GPUParticles2D       ← 火焰粒子效果

生效必备素材/资源

资源	类型	说明
光影贴图	Texture2D	赋给 texture 属性，决定光的形状。通常是一张径向渐变图片（中心白色→边缘透明）
灯具图片	Texture2D	赋给 Sprite2D，显示灯具外观
OccluderPolygon2D	OccluderPolygon2D 资源	赋给 LightOccluder2D，定义阴影遮挡轮廓

节点属性与信号

光照基础

属性	类型	默认值	继承自	说明
color	Color	白色	Light2D	光的颜色
energy	float	1.0	Light2D	光的强度
z_range_min	int	-1024	Light2D	光照生效的最小 Z 层
z_range_max	int	1024	Light2D	光照生效的最大 Z 层
layer_range_min	int	0	Light2D	光照生效的最小渲染层
layer_range_max	int	0	Light2D	光照生效的最大渲染层
item_cull_mask	int	1	Light2D	光照可见层掩码
shadow_enabled	bool	false	Light2D	是否开启阴影
shadow_color	Color	黑色半透明	Light2D	阴影的颜色
shadow_filter	枚举	None	Light2D	阴影滤镜模式。None/PCF5/PCF13
shadow_filter_smooth	float	3.0	Light2D	阴影滤镜平滑度
blend_mode	枚举	Add	Light2D	光照混合模式。Add（叠加）/ Sub（减去）/ Mix（混合）

点光源特有

属性	类型	默认值	继承自	说明
texture	Texture2D	null	—	光影贴图。决定了光的形状，通常用一个径向渐变图片。不设置则为默认的方形光
texture_scale	float	1.0	—	光影贴图的缩放
range	float	128.0	—	光照范围（像素）
height	float	1.0	—	光源高度。影响阴影效果的长度和方向

信号

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

常用方法

方法	返回值	说明
GetTexture()	Texture2D	获取光影贴图
SetTexture(texture)	void	设置光影贴图
GetTextureScale()	float	获取光影贴图缩放
SetTextureScale(scale)	void	设置光影贴图缩放
GetRange()	float	获取光照范围
SetRange(range)	void	设置光照范围
GetHeight()	float	获取光源高度
SetHeight(height)	void	设置光源高度

代码示例

C

using Godot;

public partial class TorchLight : PointLight2D
{
    [Export] public float ExBaseEnergy = 1.0f;
    [Export] public float ExFlickerIntensity = 0.2f;
    [Export] public float ExFlickerSpeed = 8.0f;

    private double _time;

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

        // 设置光照范围
        Range = 150.0f;

        // 设置光源高度（影响阴影长度）
        Height = 1.5f;

        // 开启阴影
        ShadowEnabled = true;
        ShadowFilter = Light2D.ShadowFilterEnum.Pcf5;

        Energy = ExBaseEnergy;
    }

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

        // 模拟火把闪烁效果
        var flicker = Mathf.Sin(_time * ExFlickerSpeed) * 0.5f
                    + Mathf.Sin(_time * ExFlickerSpeed * 3.1f) * 0.3f
                    + Mathf.Sin(_time * ExFlickerSpeed * 7.3f) * 0.2f;
        Energy = ExBaseEnergy + flicker * ExFlickerIntensity;
    }
}

GDScript

extends PointLight2D

@export var base_energy: float = 1.0
@export var flicker_intensity: float = 0.2
@export var flicker_speed: float = 8.0

var _time: float = 0.0

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

    # 设置光照范围
    range = 150.0

    # 设置光源高度（影响阴影长度）
    height = 1.5

    # 开启阴影
    shadow_enabled = true
    shadow_filter = Light2D.SHADOW_FILTER_PCF5

    energy = base_energy

func _process(delta):
    _time += delta

    # 模拟火把闪烁效果
    var flicker = sin(_time * flicker_speed) * 0.5 \
                + sin(_time * flicker_speed * 3.1) * 0.3 \
                + sin(_time * flicker_speed * 7.3) * 0.2
    energy = base_energy + flicker * flicker_intensity

关于 texture 属性

PointLight2D 的 texture 属性很关键。它决定了光的"形状"。最常用的做法是用一张径向渐变的图片（从中心白色渐变到边缘透明），这样光就会呈现从中心向外逐渐变暗的效果。如果不设置 texture，默认是一个方形的光照区域，看起来很不自然。