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

DirectionalLight2D

节点继承关系

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

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 世界里的"太阳光"。

和 3D 的 DirectionalLight3D 类似，只不过它工作在 2D 平面上。不管光源放在哪里，它发出的光都是从同一个方向照射过来的。

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

节点用途

• 模拟 2D 世界中的全局环境光（类似太阳光或月光）
• 为 2D 场景提供均匀的基底光照
• 配合 LightOccluder2D 产生阴影

使用场景

典型场景

• 2D 横版游戏：模拟太阳从某个方向照来，地面上的物体产生阴影
• 2D 潜行游戏：模拟环境光，配合阴影营造暗处藏身的效果
• 2D 地牢游戏：模拟顶部照下来的微弱光线

不适用场景

• 只需要一个点光源照亮周围 → 使用 PointLight2D
• 3D 场景光照 → 使用 DirectionalLight3D

常用节点搭配

搭配节点	用途	必需？
LightOccluder2D	遮挡体，让物体产生阴影	推荐
PointLight2D	配合使用，做局部点光源	可选

典型节点树：

Level (Node2D)
├── DirectionalLight2D     ← 全局平行光（太阳光）
├── PointLight2D           ← 局部点光源（火把）
└── Wall (StaticBody2D)
    └── LightOccluder2D    ← 墙壁遮挡体（产生阴影）

生效必备素材/资源

资源	类型	说明
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（5点柔和）/ PCF13（13点更柔和）
shadow_filter_smooth	float	3.0	Light2D	阴影滤镜平滑度
blend_mode	枚举	Add	Light2D	光照混合模式。Add（叠加）/ Sub（减去）/ Mix（混合）

平行光特有

属性	类型	默认值	继承自	说明
height	float	1.0	—	光源高度。影响阴影的长度。值越大阴影越短，值越小阴影越长
max_distance	float	10000.0	—	阴影最大距离。超过这个距离的阴影不渲染
direction	Vector2	(1, 0)	—	光线的方向向量。默认 (1, 0) 表示光从左往右照

信号

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

常用方法

方法	返回值	说明
GetDirection()	Vector2	获取光线的方向向量
SetDirection(direction)	void	设置光线的方向向量
GetHeight()	float	获取光源高度
SetHeight(height)	void	设置光源高度
GetMaxDistance()	float	获取阴影最大距离
SetMaxDistance(distance)	void	设置阴影最大距离

代码示例

C

using Godot;

public partial class DayNightCycle2D : DirectionalLight2D
{
    [Export] public float ExCycleSpeed = 0.05f;

    private double _time;

    public override void _Ready()
    {
        // 开启阴影
        ShadowEnabled = true;

        // 设置阴影滤镜，让阴影边缘柔和
        ShadowFilter = Light2D.ShadowFilterEnum.Pcf5;
        ShadowFilterSmooth = 3.0f;
    }

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

        // 模拟太阳从左到右的移动
        float angle = (float)(_time % (Mathf.Tau));
        Vector2 dir = new Vector2(Mathf.Cos(angle), Mathf.Sin(angle));
        Direction = dir;

        // 根据太阳角度改变光色和强度
        // 太阳在上方时最亮（模拟正午），在下方时最暗（模拟夜晚）
        float sunHeight = -dir.Y; // Y 轴向上为正，太阳在上方时 Y 为负
        if (sunHeight > 0)
        {
            // 白天：暖白色
            Color = new Color(1.0f, 0.95f, 0.85f);
            Energy = Mathf.Lerp(0.5f, 1.2f, sunHeight);
            Height = Mathf.Lerp(0.3f, 2.0f, sunHeight);
        }
        else
        {
            // 夜晚：深蓝色，低能量
            Color = new Color(0.2f, 0.3f, 0.6f);
            Energy = 0.1f;
            Height = 0.2f;
        }
    }
}

GDScript

extends DirectionalLight2D

@export var cycle_speed: float = 0.05

var _time: float = 0.0

func _ready():
    # 开启阴影
    shadow_enabled = true

    # 设置阴影滤镜，让阴影边缘柔和
    shadow_filter = Light2D.SHADOW_FILTER_PCF5
    shadow_filter_smooth = 3.0

func _process(delta):
    _time += delta * cycle_speed

    # 模拟太阳从左到右的移动
    var angle: float = fmod(_time, TAU)
    var dir := Vector2(cos(angle), sin(angle))
    direction = dir

    # 根据太阳角度改变光色和强度
    # 太阳在上方时最亮（模拟正午），在下方时最暗（模拟夜晚）
    var sun_height: float = -dir.y  # Y 轴向上为正，太阳在上方时 Y 为负
    if sun_height > 0:
        # 白天：暖白色
        color = Color(1.0, 0.95, 0.85)
        energy = lerpf(0.5, 1.2, sun_height)
        height = lerpf(0.3, 2.0, sun_height)
    else:
        # 夜晚：深蓝色，低能量
        color = Color(0.2, 0.3, 0.6)
        energy = 0.1
        height = 0.2

使用说明

DirectionalLight2D 需要 2D 场景中的 Occluder（遮挡器）配合才能产生阴影效果。如果只是在场景中放了光而没有设置遮挡器，光会照到所有地方，看不到阴影。遮挡器通过 LightOccluder2D 节点添加。