游戏引擎 / 系统课时
场景根节点怎样封装对外接口
场景根节点怎样封装对外接口
关卡需要让角色受伤时,不应先找到角色内部的生命或表现节点。本课用一个可运行的 Godot 4 场景,把伤害方法、查询方法和变化信号放在根节点,再移动内部节点,验证关卡调用不受影响。
学习目标
- 根据关卡需求设计场景根节点的最小公共接口。
- 用返回值和信号分别表达操作结果与状态变化。
- 调整场景内部结构后,验证外部调用仍然有效。
从关卡需求确定接口边界
把角色场景当成可以放入任意关卡的对象。关卡只需要告诉它“受到多少伤害”,以及在必要时查询当前生命值;至于显示什么颜色、播放哪段动画,都属于角色场景内部决策。
约定根节点暴露 take_damage(amount: int) -> int,返回实际扣除的生命值,避免把传入的伤害量误当成最终结果;get_health() -> int 返回当前生命值;health_changed(current_hp, maximum_hp) 通知外部刷新 HUD。负数、零伤害和已经死亡的目标均返回 0,不发出变化信号。

在根节点实现受伤契约
新建 Character.tscn:根节点使用 Node2D,命名 DamageableCharacter;添加一个名为 Visual 的 ColorRect 子节点,在检查器中将其尺寸设为约 48 × 48,作为可见的占位角色。给根节点挂载 character.gd,完整代码如下:
extends Node2D
class_name DamageableCharacter
signal health_changed(current_hp: int, maximum_hp: int)
@export_range(1, 500, 1) var max_hp: int = 100
@onready var _visual: ColorRect = $Visual as ColorRect
var _hp: int = 0
func _ready() -> void:
_hp = max_hp
_visual.color = Color(0.25, 0.75, 0.5)
func take_damage(amount: int) -> int:
# 无效请求不修改状态,也不产生虚假的变化通知。
if amount <= 0 or _hp == 0:
return 0
var applied: int = mini(amount, _hp)
# 先完成状态修改,再驱动表现并通知外部。
_hp -= applied
_visual.color = Color(0.95, 0.35, 0.3)
health_changed.emit(_hp, max_hp)
return applied
func get_health() -> int:
return _hp预期结果:单独运行 Character.tscn 时,Visual 显示为绿色且不会自行打印日志;扣血后的红色反馈与数值输出由下面的关卡脚本验证。
_hp 的下划线仅表示项目约定的内部字段,并不是语言强制的私有权限;真正的封装来自调用方只依赖根节点约定的方法和信号。@onready 在节点就绪后获取 Visual,不要求关卡知道它在哪里。
让关卡只调用场景实例
创建 Level.tscn,以 Node2D 为根节点,拖入 Character.tscn 作为子场景实例,并将实例命名为 Target。给关卡根节点挂载以下 level.gd,运行当前关卡场景:
extends Node2D
@onready var target: DamageableCharacter = $Target as DamageableCharacter
func _ready() -> void:
# 在发起伤害请求前订阅,才能捕获本次变化。
target.health_changed.connect(_on_target_health_changed)
print("初始 HP=%d" % target.get_health())
print("实际扣血=%d" % target.take_damage(30))
print("剩余 HP=%d" % target.get_health())
func _on_target_health_changed(current_hp: int, maximum_hp: int) -> void:
print("生命变化=%d/%d" % [current_hp, maximum_hp])预期输出:
初始 HP=100
生命变化=70/100
实际扣血=30
剩余 HP=70信号在扣血方法内部同步发出,所以“生命变化”先于该方法返回后的“实际扣血”出现。关卡能够得到结果,却没有使用 $Target/Visual 之类的内部路径。
移动内部节点检验封装
回到 Character.tscn,在根节点下新增 Node2D,命名 Graphics,把 Visual 移入其中。此时仅在 character.gd 中将内部引用改为 @onready var _visual: ColorRect = $Graphics/Visual as ColorRect,保存源场景。
重新运行 Level.tscn,预期四行输出与之前完全一致,颜色反馈也应仍然有效。若出现节点路径错误,修复位置应在角色场景脚本,而不是让所有关卡改为访问新的子节点路径。
根节点不是必须承载全部业务逻辑;以后即使把生命处理和动画拆成内部组件,关卡依旧只需要持有这个场景实例的根节点。