游戏引擎 / 系统课时
理解场景实例与节点生命周期
理解场景实例与节点生命周期
本课用一份 Coin.tscn 连续创建两个运行时对象,再删除其中一个,观察实际的回调顺序。你将区分存储在磁盘上的场景资源、尚未加入场景树的实例,以及真正参与运行和被释放的节点,避免把加载、创建和销毁混为一谈。
学习目标
- 区分
PackedScene资源、instantiate()创建的节点实例与运行中的场景树。 - 识别
_enter_tree()、_ready()、_exit_tree()的触发时机和顺序。 - 使用
add_child()与queue_free()管理实例,并通过日志确认生命周期。
资源文件不等于活动节点
.tscn 保存的是可复用的场景结构;通过 preload() 取得的 PackedScene 是资源对象,并非屏幕中正在运行的节点。instantiate() 根据这份资源创建一套新的节点层级,但尚未将它接入当前 SceneTree。只有把实例通过 add_child() 加到运行中的节点下面,才会触发进入树和就绪回调。
同一个 PackedScene 可以实例化多次,得到独立的节点对象。为 A 修改节点名称或位置不会同步改变 B;但它们引用的纹理、材质等 Resource 可能仍是共享资源,因此“实例独立”不等于“所有资源都复制”。

创建可复用的 Coin 场景
以下是一个配套的完整示例,使用 Godot 4.x 的两个场景和两个脚本;单独复制某个脚本不能代替其对应的场景文件。
- 新建 3D 场景,根节点选择
Node3D并命名Coin,保存为项目根目录的res://Coin.tscn。 - 给
Coin附加res://Coin.gd,记录进入场景树、准备完成和退出场景树时的日志。 - 新建另一个 3D 场景,根节点命名
Main(Node3D),保存为res://Main.tscn,并给它附加res://Main.gd。
Coin.gd 的完整内容:
extends Node3D
func _enter_tree() -> void:
# 只有接入活动场景树后才触发
print(name, ": enter")
func _ready() -> void:
print(name, ": ready")
func _exit_tree() -> void:
# 移出场景树或销毁时均会触发
print(name, ": exit")Main.gd 负责从同一资源创建两个实例:
extends Node3D
const COIN_SCENE: PackedScene = preload("res://Coin.tscn")
func _ready() -> void:
var coin_a := COIN_SCENE.instantiate() as Node3D
var coin_b := COIN_SCENE.instantiate() as Node3D
coin_a.name = "CoinA"
coin_b.name = "CoinB"
# 加入已运行的Main,才开始进入树与就绪回调
add_child(coin_a)
add_child(coin_b)
print("instances: ", coin_a.name, ", ", coin_b.name)
# A在当前帧结束时删除;B继续存在
coin_a.queue_free()预期输出:按 F6 运行 Main.tscn,在“输出(Output)”面板按顺序看到以下日志:
CoinA: enter
CoinA: ready
CoinB: enter
CoinB: ready
instances: CoinA, CoinB
CoinA: exit这里没有绘制模型,因此运行视窗可以是空的,验证重点是日志和远程场景树。停止运行时,剩余的 CoinB 还会收到退出场景树的通知。
解释回调顺序与销毁边界
instantiate() 只构造节点对象,不会直接触发 _enter_tree() 或 _ready()。add_child(coin_a) 把 A 放入已运行的树后,先执行 A 的 _enter_tree(),再执行 _ready();之后添加 B 才出现 B 的两行日志。代码打印两个名称后,queue_free() 把 A 排入当前帧结束时的释放队列,因此 A 的 _exit_tree() 最后出现。
若实例包含子节点,进入树时父节点的 _enter_tree() 先于子节点;就绪时子节点的 _ready() 先于父节点;退出时通常按子节点到父节点的顺序。_ready() 对同一节点默认只运行一次,移出再加回场景树并不会自动再次执行它;确需重新触发时可先调用 request_ready()。
remove_child() 与 queue_free() 不能混用为同一个意思:前者只解除父子关系,并不销毁对象;后者在帧末释放节点及其子节点。节点释放后,原先保存的引用不能再安全使用;必要时通过 is_instance_valid() 判断引用是否仍有效。
检查实例是否仍然存在
运行时打开编辑器“场景(Scene)”停靠面板的“远程(Remote)”树,查看 Main 下剩余的子节点:帧末释放后应只剩 CoinB。再注释掉 coin_a.queue_free() 运行一次,此时两份实例都会保留,不会打印 A 的 exit,直到停止场景。
这组验证区分了三个不同动作:场景资源负责复用配置,实例化负责创建节点对象,而进入场景树与离开场景树决定它何时参与运行。把这些时机分开,才能可靠地生成、复用和清理游戏对象。