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

LightOccluder2D

节点继承关系

继承链：Node → CanvasItem → LightOccluder2D

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 灯光下产生阴影。

想象你用手电筒照一棵树，树的背后会有一片阴影。LightOccluder2D 就是那棵"树"——你把它挂在某个物体上，等于告诉引擎："这个物体的形状会挡住光线，请帮我在背后画出阴影。"

使用频率：★★ 偶尔使用——需要 2D 阴影效果的 2D 游戏中使用。

节点用途

• 让 2D 场景中的物体产生阴影效果
• 配合 DirectionalLight2D 或 PointLight2D 产生阴影
• 控制哪些物体挡光、哪些不挡光（比如窗户可以透光）

使用场景

典型场景

• 2D 地牢游戏：墙壁挡住火把的光，背后出现阴影
• 2D 横版游戏：建筑物挡住太阳光，地面出现阴影
• 2D 潜行游戏：利用阴影区域让玩家躲避敌人
• 2D 解谜游戏：利用阴影机制做光影谜题

不适用场景

• 3D 场景的阴影 → 3D 光源自带阴影功能，只需开启 shadow_enabled
• 不需要阴影的 2D 游戏 → 直接不用这个节点

常用节点搭配

搭配节点	用途	必需？
PointLight2D	2D 点光源（需开启 shadow_enabled）	必需
DirectionalLight2D	2D 平行光（需开启 shadow_enabled）	必需
StaticBody2D / RigidBody2D	物理碰撞体，LightOccluder2D 作为其子节点	推荐
CollisionShape2D	物理碰撞形状（与遮挡形状独立）	可选

典型节点树：

Wall (StaticBody2D)
├── Sprite2D           ← 墙壁的图片
├── CollisionShape2D   ← 物理碰撞形状（决定角色能不能穿过）
└── LightOccluder2D    ← 光照遮挡形状（决定光线能不能穿过）

生效必备素材/资源

资源	类型	说明
OccluderPolygon2D	OccluderPolygon2D 资源	必需。在 occluder 属性中创建，定义物体的遮挡轮廓多边形。光照射到这个轮廓时，背后就会产生阴影

节点属性与信号

遮挡设置

属性	类型	默认值	继承自	说明
occluder	OccluderPolygon2D	null	—	遮挡形状资源，定义这个物体的轮廓多边形。这是最核心的属性，没有它就不会产生阴影
occluder_light_mask	int	1	—	遮挡体对哪些光照层生效。可以设置让某些光穿过某些不穿过
sdf_collision	bool	false	—	是否生成 SDF（有符号距离场）碰撞数据。开启后可以在着色器（Shader）中使用 texture_sdf 获取遮挡体的距离信息
sdf_resolution	int	64	—	SDF 纹理的分辨率（像素）。值越高轮廓越精确但性能开销越大

信号

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

常用方法

方法	返回值	说明
GetOccluderPolygon()	OccluderPolygon2D	获取当前的遮挡多边形资源
SetOccluderPolygon(occluderPolygon)	void	设置遮挡多边形资源
GetOccluderLightMask()	int	获取光照层掩码
SetOccluderLightMask(mask)	void	设置光照层掩码

代码示例

场景一：动态创建遮挡形状

C

using Godot;

public partial class DynamicOccluder : LightOccluder2D
{
    public override void _Ready()
    {
        // 创建一个矩形遮挡形状
        var occluderPoly = new OccluderPolygon2D();
        // 设置轮廓点（相对于节点位置的偏移，单位：像素）
        // 这里定义一个 100x60 的矩形
        occluderPoly.Polygon = new Vector2[]
        {
            new(-50, -30),  // 左上
            new(50, -30),   // 右上
            new(50, 30),    // 右下
            new(-50, 30),   // 左下
        };
        // 闭合多边形
        occluderPoly.CullMode = OccluderPolygon2D.CullModeEnum.Disabled;

        Occluder = occluderPoly;
    }
}

GDScript

extends LightOccluder2D

func _ready():
    # 创建一个矩形遮挡形状
    var occluder_poly = OccluderPolygon2D.new()
    # 设置轮廓点（相对于节点位置的偏移，单位：像素）
    # 这里定义一个 100x60 的矩形
    occluder_poly.polygon = PackedVector2Array([
        Vector2(-50, -30),  # 左上
        Vector2(50, -30),   # 右上
        Vector2(50, 30),    # 右下
        Vector2(-50, 30),   # 左下
    ])
    # 闭合多边形
    occluder_poly.cull_mode = OccluderPolygon2D.CULL_DISABLED

    occluder = occluder_poly

场景二：运行时开关阴影

C

using Godot;

public partial class DestructibleWall : StaticBody2D
{
    private LightOccluder2D _occluder;

    public override void _Ready()
    {
        _occluder = GetNode<LightOccluder2D>("LightOccluder2D");
    }

    // 墙壁被破坏时移除遮挡
    public void DestroyWall()
    {
        // 隐藏遮挡体，让光线穿过
        _occluder.Visible = false;

        // 或者直接移除遮挡资源
        // _occluder.Occluder = null;
    }
}

GDScript

extends StaticBody2D

var _occluder: LightOccluder2D

func _ready():
    _occluder = $LightOccluder2D

# 墙壁被破坏时移除遮挡
func destroy_wall():
    # 隐藏遮挡体，让光线穿过
    _occluder.visible = false

    # 或者直接移除遮挡资源
    # _occluder.occluder = null

遮挡形状 vs 碰撞形状

LightOccluder2D 的遮挡形状（occluder）和物理碰撞形状（CollisionShape2D）是两个独立的东西：

• 碰撞形状决定角色能不能穿过
• 遮挡形状决定光线能不能穿过

通常两者形状相似，但不是必须完全一样。比如你可以让遮挡形状比碰撞形状稍大一点，让阴影边缘更柔和。你也可以让一扇窗户有碰撞形状（角色穿不过去）但没有遮挡形状（光线可以穿过）。

如何编辑 OccluderPolygon2D

1. 在场景树中选中 LightOccluder2D 节点
2. 在右侧属性面板找到 Occluder 属性，点击 <空> → 新建 OccluderPolygon2D
3. 在 2D 视口中会出现可编辑的多边形顶点
4. 拖拽顶点来调整遮挡轮廓的形状
5. 也可以在属性面板中设置 Polygon 属性的数值