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

DirectionalLight3D

节点继承关系

继承链：Node → Node3D → Light3D → DirectionalLight3D

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

定义

平行光/太阳光，所有光线从同一个方向平行射来，照亮整个场景。

就像现实中的太阳光。太阳离我们非常远，所以阳光到达地面时几乎是平行的。不管你的角色站在地图的左边还是右边，太阳光的角度都一样。

使用频率：★★★★ 维度专用常用——室外 3D 场景必备。

节点用途

• 模拟太阳光，照亮整个 3D 场景
• 投射阴影，让场景更有立体感
• 模拟日夜循环，通过改变光照角度和颜色
• 做补光，填充场景暗部

使用场景

典型场景

• 室外开放世界：一个 DirectionalLight3D 做太阳光
• 室内+室外混合：DirectionalLight3D 做太阳光，OmniLight3D 做室内灯
• 日夜循环系统：通过代码动态改变光照角度、颜色和强度

不适用场景

• 室内场景的灯光 → 使用 OmniLight3D 或 SpotLight3D
• 2D 游戏光照 → 使用 DirectionalLight2D

常用节点搭配

搭配节点	用途	必需？
WorldEnvironment	设置天空盒、环境光，配合太阳光营造氛围	推荐
OmniLight3D / SpotLight3D	室内或局部补光	可选

典型节点树：

World (Node3D)
├── DirectionalLight3D  ← 太阳光
├── WorldEnvironment    ← 天空和环境设置
└── Player

生效必备素材/资源

资源	类型	说明
Environment 资源	Environment	赋给 WorldEnvironment，设置天空盒、环境光、色调映射

节点属性与信号

光照基础

属性	类型	默认值	继承自	说明
light_color	Color	白色	Light3D	光的颜色。暖色偏黄模拟午后阳光，冷色偏蓝模拟月光
light_energy	float	1.0	Light3D	光的强度。1.0 是正常亮度，大于 1 更亮，小于 1 更暗
light_indirect_energy	float	1.0	Light3D	间接光照（反射光）的强度
light_volumetric_fog_energy	float	1.0	Light3D	体积雾受此光照影响的强度
light_specular	float	0.5	Light3D	镜面反射强度。0 = 无高光，1 = 正常高光

阴影设置

属性	类型	默认值	继承自	说明
shadow_enabled	bool	false	Light3D	是否开启阴影。强烈建议开启，没有阴影的 3D 场景看起来很假
shadow_color	Color	黑色	Light3D	阴影的颜色
shadow_blend	float	0.1	Light3D	阴影的混合程度
directional_shadow_mode	枚举	Orthogonal	—	阴影模式。Orthogonal（正交，性能好）或 Parallel2Splits/Pssm2Split/Pssm4Split（级联阴影，质量高）
directional_shadow_max_distance	float	100.0	—	阴影可见的最大距离
directional_shadow_split_1	float	0.1	—	PSSM 阴影第一段分割比例
directional_shadow_split_2	float	0.2	—	PSSM 阴影第二段分割比例
directional_shadow_split_3	float	0.5	—	PSSM 阴影第三段分割比例
directional_shadow_fade_start	float	0.8	—	阴影淡出起始比例
directional_shadow_normal_bias	float	1.0	—	阴影法线偏移，减少阴影闪烁
directional_shadow_bias_split_scale	float	0.25	—	阴影偏移缩放因子

光源特性

属性	类型	默认值	继承自	说明
light_angular_distance	float	0.0	—	光源的角直径。值越大会产生越柔和的阴影（模拟太阳的视觉大小）
sky_top_color	Color	Color(0.385, 0.453, 0.55)	—	天空顶部颜色（配合 Sky 材质使用）
sky_bottom_color	Color	Color(0.4, 0.625, 1)	—	天空底部颜色
sky_curve	float	0.25	—	天空颜色渐变曲线
sky_energy	float	1.0	—	天空光的强度

信号

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

常用方法

方法	返回值	说明
GetDirectionalShadowTransform()	Transform3D[]	获取方向光阴影的变换矩阵数组（PSSM 模式下返回多个）

代码示例

C

using Godot;

public partial class SunLight : DirectionalLight3D
{
    public override void _Ready()
    {
        // 设置太阳光的颜色（暖白色，模拟午后阳光）
        LightColor = new Color(1.0f, 0.95f, 0.8f);

        // 设置光照强度
        LightEnergy = 1.2f;

        // 开启阴影（强烈建议！）
        ShadowEnabled = true;

        // 使用级联阴影（质量更高，适合大场景）
        DirectionalShadowMode = DirectionalLight3D.ShadowMode.Pssm2Split;

        // 阴影最大可见距离
        DirectionalShadowMaxDistance = 200.0f;

        // 让阴影更柔和
        LightAngularDistance = 0.5f;

        // 旋转光源来模拟太阳的角度
        // X 轴旋转控制太阳高度，Y 轴旋转控制东西方向
        RotationDegrees = new Vector3(-45, -30, 0);
    }

    // 模拟日夜循环：改变光照角度和颜色
    public void SetTimeOfDay(float time01)
    {
        // time01 范围 0~1，0 = 午夜，0.5 = 正午
        var sunAngle = time01 * 360.0f - 90.0f;
        RotationDegrees = new Vector3(sunAngle, -30, 0);

        // 正午白色，早晚暖橙色，夜晚深蓝色
        if (time01 is > 0.25f and < 0.75f)
        {
            LightColor = new Color(1.0f, 0.95f, 0.85f);
            LightEnergy = Mathf.Lerp(0.3f, 1.2f, Mathf.Sin(time01 * Mathf.Pi));
        }
        else
        {
            LightColor = new Color(0.3f, 0.4f, 0.7f);
            LightEnergy = 0.1f;
        }
    }
}

GDScript

extends DirectionalLight3D

func _ready():
    # 设置太阳光的颜色（暖白色，模拟午后阳光）
    light_color = Color(1.0, 0.95, 0.8)

    # 设置光照强度
    light_energy = 1.2

    # 开启阴影（强烈建议！）
    shadow_enabled = true

    # 使用级联阴影（质量更高，适合大场景）
    directional_shadow_mode = DirectionalLight3D.SHADOW_PSSM_2_SPLIT

    # 阴影最大可见距离
    directional_shadow_max_distance = 200.0

    # 让阴影更柔和
    light_angular_distance = 0.5

    # 旋转光源来模拟太阳的角度
    # X 轴旋转控制太阳高度，Y 轴旋转控制东西方向
    rotation_degrees = Vector3(-45, -30, 0)

# 模拟日夜循环：改变光照角度和颜色
func set_time_of_day(time01: float):
    # time01 范围 0~1，0 = 午夜，0.5 = 正午
    var sun_angle = time01 * 360.0 - 90.0
    rotation_degrees = Vector3(sun_angle, -30, 0)

    # 正午白色，早晚暖橙色，夜晚深蓝色
    if time01 > 0.25 and time01 < 0.75:
        light_color = Color(1.0, 0.95, 0.85)
        light_energy = lerpf(0.3, 1.2, sin(time01 * PI))
    else:
        light_color = Color(0.3, 0.4, 0.7)
        light_energy = 0.1

使用建议

• 一个场景通常放 1~2 个 DirectionalLight3D 就够了
• 一个做主光源（太阳），另一个可以用来填充暗部（模拟天空散射光）
• 一定要开启阴影，阴影是让 3D 场景看起来真实的关键因素之一
• 大场景建议使用 PSSM（级联阴影）模式，质量更高