游戏引擎 / 系统课时
用信号连接角色与交互对象
用信号连接角色与交互对象
如果玩家脚本直接控制机关开关、修改 UI 文本,新增第二种机关时就容易牵动多处代码。本课用 Godot 4 信号让角色只报告交互意图,机关只报告状态变化,再由场景协调器负责连接,完成一个按键切换机关的可运行示例。
学习目标
- 理解信号发布者、订阅者和场景协调器的职责。
- 定义带参数的自定义信号并通过代码连接。
- 验证交互距离、状态更新和连接生命周期。
让每个对象只负责自己的事件
玩家按下交互键时,只发送 interact_requested,不需要知道附近是哪种机关。场景根节点收到事件后检查距离,决定是否调用机关的 activate()。机关切换自身状态后发送 state_changed,由协调器通知 UI 更新。
这种结构并不是完全消除引用,而是把必要的依赖集中到场景协调器:玩家不引用机关,机关也不引用标签。以后把开关换成门、宝箱或电梯时,可以替换处理逻辑而不修改玩家输入脚本。

准备最小交互场景
新建 Main(Node3D)场景,添加 Player(CharacterBody3D)、Lever(Node3D)、CanvasLayer,并在 CanvasLayer 下添加 StatusLabel(Label)。为了让三维场景可见,可以再放置 Camera3D 和机关模型;它们不参与信号逻辑。
把 Player 的位置设为 (0, 0, 0),Lever 设为 (1, 0, 0),初始距离为 1。打开“项目 → 项目设置 → 输入映射”,新建动作 interact,绑定键盘 E。三个脚本分别挂到指定节点,文件名与下面一致。
角色发布意图,机关发布状态
将 player_interactor.gd 挂到 Player。它只关心何时产生输入事件,不保存机关或 HUD 引用。_unhandled_input() 适合让已处理的 UI 输入优先消费,避免操作菜单时顺带触发游戏交互。
extends CharacterBody3D
class_name PlayerInteractor
signal interact_requested(actor: Node3D)
func _unhandled_input(event: InputEvent) -> void:
# 角色只描述交互意图,不指定交互对象。
if event.is_action_pressed("interact"):
interact_requested.emit(self)
get_viewport().set_input_as_handled()将 switch_lever.gd 挂到 Lever。机关负责维护自身开关状态,只有完成切换后才发布新状态。
extends Node3D
class_name SwitchLever
signal state_changed(is_active: bool)
var is_active: bool = false
func activate() -> void:
# 状态先在机关内部改变,再向订阅者广播结果。
is_active = not is_active
state_changed.emit(is_active)以上两份脚本是同一场景示例的组成部分;它们需要下一节的连接脚本协作,不能单独验证完整交互结果。
在场景根节点集中连接
将 main.gd 挂到 Main。根节点负责接线和距离判定,而不是把这些逻辑塞进角色或机关。@onready 引用中的节点名必须与场景一致。
extends Node3D
@export var interaction_distance: float = 2.0
@onready var player: PlayerInteractor = $Player
@onready var lever: SwitchLever = $Lever
@onready var status_label: Label = $CanvasLayer/StatusLabel
func _ready() -> void:
# 所有跨对象连接都在协调器中建立。
player.interact_requested.connect(_on_interact_requested)
lever.state_changed.connect(_on_lever_state_changed)
status_label.text = "机关:关闭"
func _on_interact_requested(actor: Node3D) -> void:
# 距离不满足时,不允许修改机关状态。
if actor.global_position.distance_to(lever.global_position) > interaction_distance:
status_label.text = "距离过远"
return
lever.activate()
func _on_lever_state_changed(is_active: bool) -> void:
# UI 根据事件载荷显示结果,不反向操纵机关。
status_label.text = "机关:开启" if is_active else "机关:关闭"
print(status_label.text)预期结果:启动场景后标签显示“机关:关闭”。角色与机关相距 1 单位时连续按两次 E,标签依次显示“机关:开启”和“机关:关闭”,输出面板依次出现:
机关:开启
机关:关闭把 Player 移到距离 Lever 超过 2 单位的位置重新运行,再按 E,标签显示“距离过远”,机关状态不变化,输出面板也不会新增开关日志。
排查连接与生命周期问题
若按键没有效果,先确认动作名 interact 的拼写、游戏窗口是否接收输入,以及事件是否被其他控件提前处理。若按钮触发了但 UI 不更新,应检查两个 .connect() 是否都执行、回调参数是否匹配信号声明、节点路径是否对应实际层级。
信号不会自动把所有机关广播给所有角色:本例只有一个 Lever,由 Main 明确选择目标。多机关场景可在协调器里结合射线检测或交互区域选中对象,再连接当前目标的信号。Godot 会在对象释放时清理相关连接;如果只是切换目标而对象仍存在,则应先断开旧目标的连接,避免收到无关事件或发生重复订阅。
需要新增提示音、任务日志时,可以让它们也监听状态变化,而不用让机关脚本逐个调用这些模块。