游戏引擎 / 系统课时

场景根节点怎样封装对外接口

场景根节点怎样封装对外接口

关卡需要让角色受伤时,不应先找到角色内部的生命或表现节点。本课用一个可运行的 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,完整代码如下:

gdscript
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,运行当前关卡场景:

gdscript
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])

预期输出:

text
初始 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,预期四行输出与之前完全一致,颜色反馈也应仍然有效。若出现节点路径错误,修复位置应在角色场景脚本,而不是让所有关卡改为访问新的子节点路径。

根节点不是必须承载全部业务逻辑;以后即使把生命处理和动画拆成内部组件,关卡依旧只需要持有这个场景实例的根节点。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

场景根节点怎样封装对外接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通