Godot 4.3 窗口透明区域点击穿透实现教程

本教程介绍如何在 Godot 4.3 以上项目中，使用纯 GDScript 实现“窗口透明区域点击穿透”效果，适用于桌面宠物、悬浮工具等无边框窗口场景。
适用平台：Windows、macOS

可下载 时钟仙途 查看点击穿透的效果。

---

1. 基本原理

Godot 4.3 提供了 DisplayServer.window_set_mouse_passthrough() 接口，可以让你指定窗口的哪些区域可以“鼠标穿透”，即点击时事件会传递到下层应用。
该接口需要传入一个多边形顶点数组（PackedVector2Array），用来描述可穿透的区域。

---

2. 步骤详解

步骤一：设置窗口为无边框和透明

在 project.godot 配置文件中，设置如下参数：

[display]
window/size/borderless = true
window/per_pixel_transparency/allowed = true

步骤二：用 Path2D 绘制穿透区域

1. 在主场景中添加一个 Path2D 节点。
2. 用编辑器绘制一条闭合曲线，曲线包围的区域即为“可穿透区域”。
3. 你也可以用 Polygon2D 节点，原理类似。
   

步骤三：代码实现穿透逻辑

在主脚本（如 main_page.gd）中添加如下方法：

func _set_window_mouse_passthrough():
    var path_points = $Path2D.curve.get_baked_points()
    var window_size = get_window().size
    var viewport_size = get_window().content_scale_size # 设计分辨率
    var scale = Vector2(float(window_size.x) / viewport_size.x, float(window_size.y) / viewport_size.y)
    var points = []
    for p in path_points:
        # 如果 Path2D 有父节点或偏移，建议用全局坐标
        var global_p = $Path2D.get_global_transform().xform(p)
        points.append(global_p * scale)
    DisplayServer.window_set_mouse_passthrough(points)

注意：

• get_window().content_scale_size 获取的是设计分辨率，get_window().size 是实际窗口像素。
• 如果 Path2D 有父节点或缩放，建议用 get_global_transform().xform(p) 转为全局坐标。

步骤四：在 _ready() 中调用

func _ready():
    # ... 你的初始化代码 ...
    _set_window_mouse_passthrough()

如果窗口的可点击区域会动态变化，可动态生成闭合曲线并重新应用。

5. 参考

• Godot 官方文档：window_set_mouse_passthrough