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

Light3D

节点继承关系

继承链：Node → Node3D → Light3D

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 光源的"老祖宗"——一个抽象基类。无论是平行光、点光源还是聚光灯，都继承自它。

打个比方：Light3D 就像是"所有能发光的东西"的统称。它定义了光源的基本属性（颜色、能量、是否开启阴影等），而它的子类（DirectionalLight3D、OmniLight3D、SpotLight3D）决定了光怎么"发"出来。

使用频率：★★★ 一般常用——不直接使用。这是理解 3D 光照系统的基础。

节点用途

• 不直接使用，作为所有 3D 光源的基类
• 理解 3D 光照系统共享属性的基础

派生节点一览

派生节点	说明	链接
DirectionalLight3D	平行光（太阳光）	★★★
OmniLight3D	点光源（灯泡）	★★
SpotLight3D	聚光灯	★★

所有子类共享的属性

属性	类型	默认值	说明
Enabled	bool	true	是否启用光源
Color	Color	(1,1,1,1)	光源颜色
Energy	float	1.0	光源强度
BakeMode	int	1	烘焙模式
ShadowEnabled	bool	false	是否投射阴影
ShadowColor	Color	(0,0,0,0)	阴影颜色
ShadowBias	float	0.15	阴影偏移（防止阴影条纹）
ShadowNormalBias	float	1.0	阴影法线偏移
ShadowReverseCullFace	bool	false	是否翻转阴影面剔除
ShadowTransmittance	float	0.0	阴影透射度
ShadowOpacity	float	1.0	阴影不透明度
ShadowBlur	float	1.0	阴影模糊程度
DistanceFade	bool	false	是否启用距离淡出
CullMask	int	1048575	光照层掩码
LightLayer	int	1	光源所在层
VolumeFadeEnabled	bool	false	是否启用体积雾淡出
VolumeFadeBegin	float	0.0	体积雾淡出起始距离
VolumeFadeLength	float	10.0	体积雾淡出长度

如何选择子类？

我需要 3D 光源
├── 模拟太阳光（整个场景均匀照射）  → DirectionalLight3D
├── 模拟灯泡（一个点向四周发光）     → OmniLight3D
└── 模拟手电筒（锥形区域照射）       → SpotLight3D