游戏引擎 / 系统课时
节点信号向外通知对象状态
节点信号向外通知对象状态
角色扣血后,血条、音效和战斗日志可能都需要响应,但角色不该逐一查找它们的节点路径。本课用 Godot 4 的自定义信号发布生命值变化,分别通过编辑器和代码连接接收者,并检查参数、重复连接及替换接收方的行为。
学习目标
- 声明并发出携带旧值、新值的类型化节点信号。
- 使用编辑器连线或
connect()将事件交给独立的接收节点。 - 验证回调参数、连接数量和接收方替换后的协作边界。
让角色只负责报告变化
建立 Main(Node2D)场景,在其下添加 Player(Node2D)和 StatusLabel(Label)。将下面的 player.gd 挂到 Player。角色只维护数值,不调用 HUD 方法,也不需要知道 HUD 位于场景树何处。
class_name Player
extends Node2D
signal health_changed(previous_hp: int, current_hp: int)
@export_range(1, 1000, 1) var max_hp: int = 100
var hp: int
func _ready() -> void:
hp = max_hp
func take_damage(amount: int) -> void:
if amount <= 0:
return
# 保存变化前数值,订阅者才能计算扣血量。
var previous_hp: int = hp
hp = maxi(hp - amount, 0)
# 已经是零生命值时不重复广播无变化事件。
if hp != previous_hp:
health_changed.emit(previous_hp, hp)信号参数顺序固定为“变化前、变化后”。例如从 100 扣除 25,就发送 (100, 75);接收方法必须能够接收这两个参数。emit() 只报告已经发生的变化,不负责更新任何具体界面。
把订阅留给装配者
给 StatusLabel 挂载 health_label.gd,接收方法签名与信号一致。标签如何展示是接收者自己的职责:
class_name HealthLabel
extends Label
func _on_health_changed(previous_hp: int, current_hp: int) -> void:
# 显示策略只存在于接收者,Player 无需引用本节点。
text = "HP: %d" % current_hp
print("状态更新: %d -> %d" % [previous_hp, current_hp])编辑器连接:选中 Player,打开右侧“节点 / Node”面板的“信号 / Signals”页,双击 health_changed,选择 StatusLabel,将其连接到 _on_health_changed。这条连接随场景保存,适合固定的场景内协作。
代码连接:也可以把下列 main.gd 挂在 Main 根节点。没有编辑器连线时,它会主动连接;即使编辑器已连接相同方法,也会识别并跳过。这里故意装配两次,用来检验重复执行不会造成重复连接。
extends Node2D
@onready var player: Player = $Player
@onready var status_label: HealthLabel = $StatusLabel
func _ready() -> void:
_wire_health()
_wire_health() # 模拟装配逻辑被重复执行。
print("连接数: ", player.health_changed.get_connections().size())
player.take_damage(25)
func _wire_health() -> void:
# 编辑器预先连接过同一个 Callable 时,避免重复 connect 报错。
if not player.health_changed.is_connected(status_label._on_health_changed):
player.health_changed.connect(status_label._on_health_changed)默认 max_hp = 100 且没有其他订阅者时,运行 Main 的预期输出为:
连接数: 1
状态更新: 100 -> 75
核对输出、参数与连接数
画面中的 StatusLabel 会显示 HP: 75。若编辑器已经连接同一个回调,结果仍相同。get_connections().size() 返回该信号当前的连接数量;它统计所有接收者,因此将来额外接入音效监听者时,总数可以大于 1,不应盲目要求永远等于 1。
故意把接收方法改成只接受一个参数,便可验证签名不匹配会造成连接或调用错误。恢复两个 int 参数后再测试。对同一个 Callable 直接重复调用 connect() 会报重复连接错误,而不是悄悄生成两次回调;因此应先用 is_connected() 判断。
更换接收者与退出场景
如果把 StatusLabel 换成战斗日志节点,只需要让新节点实现接收两个生命值参数的方法,再修改 Main 中的连接目标,Player 无需修改。同一信号也可以连接多个不同接收者,让 UI、音效分别响应;不要把这些反向依赖写回角色脚本。
接收节点被释放后,Godot 通常会清理指向该对象方法的连接;但仅隐藏节点不等于释放,它仍可能收到通知。临时监听者若只应在活动期接收事件,应在退出活动期时通过 disconnect() 解绑,并先用 is_connected() 检查。这样信号负责描述“发生了什么”,装配者负责“通知谁”,接收者负责“如何响应”。