游戏引擎 / 系统课时
输入事件怎样避免被界面穿透
输入事件怎样避免被界面穿透
点击菜单按钮时,角色也执行了攻击或场景选取,通常是游戏逻辑在界面消费事件之前就响应了鼠标。本课用 Godot 4.6 的输入传播顺序搭建最小案例,让菜单接管自己的点击区域,只有剩余事件才能触发角色操作。
学习目标
- 区分
_input()、Control._gui_input()与_unhandled_input()的用途。 - 用菜单和角色的点击日志验证事件是否被正确消费。
- 理解
mouse_filter和Input单例轮询的不同边界。
事件会依次经过哪些入口
在同一个 Viewport 内,普通事件先交给节点的 _input(),再尝试由命中的 Control 通过 _gui_input() 处理。如果仍未被标记为已处理,才会进入快捷键、未处理按键和 _unhandled_input() 等后续阶段。鼠标事件不经过仅针对按键的快捷键回调。

因此,世界点击、拾取、攻击这类允许界面优先拦截的行为,通常应放在 _unhandled_input()。若放在 _input(),角色可能在按钮收到事件之前就完成了动作;如果还提前调用 get_viewport().set_input_as_handled(),按钮甚至无法收到这次事件。
用鼠标过滤设置界面边界
Control.mouse_filter 决定控件是否接收鼠标事件,以及事件能否继续向父级控件传播。
| 取值 | 行为 | 常见用途 |
|---|---|---|
MOUSE_FILTER_STOP |
接收并自动标记鼠标事件为已处理 | 按钮、阻挡场景点击的菜单面板 |
MOUSE_FILTER_PASS |
接收事件;未处理时向父级控件传递 | 需要由父容器接管的 UI |
MOUSE_FILTER_IGNORE |
不接收或阻挡鼠标事件 | 覆盖在按钮上的纯装饰图片 |
自定义控件可以在 _gui_input(event) 中调用 accept_event() 主动消费某次事件。过滤属性影响的是 Control 的鼠标事件分发;键盘操作还需考虑焦点以及事件是否被控件处理。
搭建菜单与场景点击案例
创建 Main(Node2D),添加同级的 Player(Node2D)和 Menu(Panel),再给 Menu 添加 Button。让菜单显示在场景前方,但只占窗口一角:例如面板位置设为 (32, 32)、尺寸为 (300, 180),按钮放在面板内部。保留面板外可点击的空白区域。
为 Player 绑定 Player.gd:
extends Node2D
func _unhandled_input(event: InputEvent) -> void:
# 仅接管没有被界面消费的左键按下事件
if event is InputEventMouseButton:
if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
print("角色执行场景点击")
get_viewport().set_input_as_handled()为 Menu 绑定 Menu.gd,并确保按钮节点名是 Button:
extends Panel
@onready var menu_button: Button = $Button
func _ready() -> void:
# 面板和按钮均阻止点击继续进入场景逻辑
mouse_filter = Control.MOUSE_FILTER_STOP
menu_button.mouse_filter = Control.MOUSE_FILTER_STOP
menu_button.pressed.connect(_on_button_pressed)
func _on_button_pressed() -> void:
print("菜单按钮触发")预期结果:运行 Main,完整按下并释放菜单按钮,输出只有:
菜单按钮触发再点击面板外的空白场景,预期输出只有:
角色执行场景点击用输出验证事件消费
点击面板内部、按钮之外的区域不应出现上述日志,因为面板会消耗鼠标事件。按钮的 pressed 信号负责菜单行为,不需要场景脚本猜测鼠标是否命中按钮。因此不要让本不需要拦截全屏点击的面板铺满窗口。
作为反例,把 Player.gd 的 _unhandled_input 改成 _input,并保留标记已处理的调用,角色就可能抢先消费按钮点击,导致菜单按钮不再触发。这是入口顺序的差异,而不是按钮层级出错。
为什么轮询仍可能触发角色
Input.is_action_pressed() 与 Input.is_action_just_pressed() 查询的是全局输入状态,不会因为 accept_event() 或 set_input_as_handled() 而变成未按下。因此,把攻击直接写在 _process() 的轮询中,仍可能在点击 UI 时触发关联动作。
连续移动等需要轮询的行为可以保留,但打开模态菜单时要显式暂停玩家输入,或由输入上下文决定是否执行。对单次点击交互,优先使用可被 GUI 消费的事件回调;对持续状态,另行管理游戏模式。参考 Godot 输入事件传播文档。