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

SpotLight3D

节点继承关系

继承链：Node → Node3D → Light3D → SpotLight3D

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

定义

聚光灯，光从一点出发只照亮一个锥形区域。

就像舞台上的聚光灯，或者手电筒。光线只照亮前方的一个锥形区域，其他地方是暗的。

使用频率：★★★ 一般常用——室内场景和特效场景经常使用。

节点用途

• 模拟手电筒、探照灯效果
• 模拟舞台聚光灯
• 模拟汽车前灯、矿灯
• 模拟保安巡逻灯
• 创造氛围光效（局部高亮区域）

使用场景

典型场景

• 恐怖游戏的手电筒：锥形光束只照亮前方，其他地方漆黑
• 舞台场景：聚光灯照射表演区域
• 车辆前灯：照亮前方道路
• 博物馆射灯：照射展品

不适用场景

• 需要向四面八方均匀照射 → 使用 OmniLight3D
• 照亮整个室外场景 → 使用 DirectionalLight3D

常用节点搭配

搭配节点	用途	必需？
MeshInstance3D（手电筒模型）	视觉上显示灯具外观	推荐
GPUParticles3D	光束中的灰尘粒子效果	可选

典型节点树：

Flashlight (Node3D)
├── MeshInstance3D       ← 手电筒的3D模型
└── SpotLight3D          ← 手电筒的锥形光束

生效必备素材/资源

资源	类型	说明
灯具的 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	光源大小。值越大阴影越柔和

阴影设置

属性	类型	默认值	继承自	说明
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	阴影透射偏移

聚光灯特有

属性	类型	默认值	继承自	说明
spot_range	float	5.0	—	光照距离（锥体长度）
spot_angle	float	45.0	—	锥体角度（度数）。越大照射范围越宽
spot_attenuation	float	1.0	—	光随距离的衰减系数
spot_light_angle	float	1.0	—	锥体边缘的柔和度（内锥体与外锥体的比例差）

信号

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

常用方法

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

代码示例

C

using Godot;

public partial class Flashlight : SpotLight3D
{
    [Export] public float ExMaxEnergy = 3.0f;
    [Export] public float ExDrainSpeed = 0.5f;
    [Export] public float ExRechargeSpeed = 0.3f;

    private bool _isOn = true;
    private float _battery;

    public override void _Ready()
    {
        // 设置手电筒光的颜色（冷白色）
        LightColor = new Color(0.95f, 0.95f, 1.0f);

        // 设置光照范围（手电筒能照多远）
        SpotRange = 30.0f;

        // 设置锥体角度（手电筒光束宽度）
        SpotAngle = 30.0f;

        // 设置衰减系数
        SpotAttenuation = 1.5f;

        // 开启阴影
        ShadowEnabled = true;

        _battery = 100.0f;
        LightEnergy = ExMaxEnergy;
    }

    public override void _Process(double delta)
    {
        float dt = (float)delta;

        // 切换手电筒开关
        if (Input.IsActionJustPressed("flashlight"))
        {
            _isOn = !_isOn;
            LightEnergy = _isOn ? _battery / 100.0f * ExMaxEnergy : 0.0f;
        }

        // 电池消耗和充电
        if (_isOn)
        {
            _battery = Mathf.Max(0, _battery - ExDrainSpeed * dt);
            LightEnergy = _battery / 100.0f * ExMaxEnergy;
        }
        else
        {
            _battery = Mathf.Min(100, _battery + ExRechargeSpeed * dt);
        }
    }
}

GDScript

extends SpotLight3D

@export var max_energy: float = 3.0
@export var drain_speed: float = 0.5
@export var recharge_speed: float = 0.3

var _is_on: bool = true
var _battery: float = 100.0

func _ready():
    # 设置手电筒光的颜色（冷白色）
    light_color = Color(0.95, 0.95, 1.0)

    # 设置光照范围（手电筒能照多远）
    spot_range = 30.0

    # 设置锥体角度（手电筒光束宽度）
    spot_angle = 30.0

    # 设置衰减系数
    spot_attenuation = 1.5

    # 开启阴影
    shadow_enabled = true

    light_energy = max_energy

func _process(delta):
    # 切换手电筒开关
    if Input.is_action_just_pressed("flashlight"):
        _is_on = !_is_on
        light_energy = _battery / 100.0 * max_energy if _is_on else 0.0

    # 电池消耗和充电
    if _is_on:
        _battery = max(0.0, _battery - drain_speed * delta)
        light_energy = _battery / 100.0 * max_energy
    else:
        _battery = min(100.0, _battery + recharge_speed * delta)

spot_angle 与 spot_light_angle 的区别

• spot_angle 控制整个锥体的总角度（即光能照到的最大范围）
• spot_light_angle 控制锥体边缘的柔和程度。值越大，锥体边缘越柔和（渐变过渡）；值越小，边缘越锐利（明显的明暗分界线）