游戏引擎 / 系统课时
PackedScene 动态创建场景
PackedScene 动态创建场景
关卡运行时经常需要动态生成道具、敌人或特效,而不是提前把所有对象放进场景树。本课使用 Godot 4 的 PackedScene 实现一个道具生成器,完成资源加载、实例配置、信号连接和入树初始化,并验证生成位置与生命周期顺序。
学习目标
- 区分
PackedScene场景资源与instantiate()创建的运行时节点实例。 - 按照实例化、配置、连接信号、加入父节点的顺序安全生成道具。
- 验证资源类型、生成位置和初始化时机,并根据使用频率选择加载方式。
场景资源与运行对象
Godot 将保存的场景表示为 PackedScene 资源。它包含节点层级、属性和脚本关联等场景数据,但资源本身不是场景树中的运行对象。
调用 instantiate() 会根据场景资源创建一套新的节点实例。生成器可以持有同一个 PackedScene,连续创建多个道具,而每个道具拥有独立的节点身份、位置和运行状态。
完整生成过程有四个关键动作:
- 加载并持有
PackedScene资源。 - 调用
instantiate()创建尚未加入场景树的实例。 - 设置实例参数,并连接需要提前监听的信号。
- 调用
add_child(),让实例进入目标父节点并执行入树、就绪回调。
其中最重要的边界是:实例化不等于入树。对于运行中已经位于场景树内的父节点,执行 add_child() 时,新子节点会进入树并完成首次就绪初始化。因此,必须在此之前设置 _ready() 需要读取的参数。

准备可实例化的道具场景
先在 Godot 4 项目中创建一个以 Node2D 为根节点的场景,将根节点命名为 Pickup,保存为 res://pickup.tscn,并为根节点挂载 res://pickup.gd。
道具需要一个积分参数和一个出生通知。为了让示例不依赖外部贴图,使用 _draw() 绘制一个小方块,运行后可以直接观察它的位置。
res://pickup.gd 完整代码如下:
extends Node2D
class_name Pickup
signal spawned(points: int)
@export var points: int = 1
func _ready() -> void:
print("道具就绪,分值=", points)
# 出生通知在就绪阶段发出,要求生成器提前连接。
spawned.emit(points)
func _draw() -> void:
# 使用纯色方块观察生成位置,不依赖贴图资源。
draw_rect(Rect2(-8, -8, 16, 16), Color(0.16, 0.68, 0.59))points 使用导出属性声明,既可以保存默认值,也可以由生成器在运行时覆盖。spawned 是自定义信号,向外报告初始化完成及当前积分值。
这里让道具在 _ready() 中发送出生信号,是为了明确验证连接时机。实际项目中的拾取信号通常在玩家进入拾取范围、满足条件后才发出,不应与出生通知混为一谈。
配置并加入父节点
再创建一个根节点为 Node2D 的关卡场景,挂载脚本 res://spawner.gd,将这个关卡设为项目主场景。生成器通过 preload() 保留道具场景资源,并在 _ready() 中生成一个积分为 5 的道具。
res://spawner.gd 完整代码如下:
extends Node2D
const PICKUP_SCENE = preload("res://pickup.tscn")
func _ready() -> void:
spawn_at(Vector2(96, 64), 5)
func spawn_at(world_position: Vector2, points: int) -> void:
var pickup := PICKUP_SCENE.instantiate() as Pickup
if pickup == null:
push_error("pickup.tscn 根节点必须使用 Pickup 脚本")
return
pickup.points = points
# 目标父节点是当前生成器,先转换为父节点局部坐标。
pickup.position = to_local(world_position)
# 必须在 add_child 触发 _ready 前连接出生信号。
pickup.spawned.connect(_on_pickup_spawned)
add_child(pickup)
func _on_pickup_spawned(points: int) -> void:
print("生成器接到信号,分值=", points)两份脚本和场景文件准备好后,运行主场景。
预期输出:
道具就绪,分值=5
生成器接到信号,分值=5运行画面中还应出现一个青绿色小方块,其世界坐标为 (96, 64)。若关卡根节点保持默认变换,该位置也就是方块相对于关卡原点的位置。
这段输出证明:points 在 _ready() 执行前已经设置为 5,而且信号接收者在道具进入场景树之前已经完成连接。
生成位置与父节点归属
Node2D.position 表示相对于父节点的局部位置,而 global_position 表示世界位置。生成器本身如果发生平移、旋转或缩放,直接把世界坐标赋给 position 就可能导致道具出现在错误位置。
示例通过生成器的 to_local(world_position) 将世界坐标转换到当前父节点坐标系。这个写法成立的前提是:生成器自身就是最终接收 add_child() 的父节点。
如果实际对象要加入另一个 Node2D 容器,就应该使用该容器的 to_local() 进行转换。另一种做法是先加入父节点,再设置 global_position,但此时 _ready() 已经执行,不适合依赖出生位置初始化的对象。
父节点还决定对象的组织边界。例如,道具放在关卡的道具容器下,方便统一查询、卸载和清理;不应仅因为生成器能访问玩家节点,就把所有道具都挂到玩家下面。
另外,add_child() 只负责运行时父子关系。普通运行时生成不需要为了入树而手动修改 owner;owner 主要影响场景保存和节点持久化归属,不应与 get_parent() 混淆。
选择加载时机与处理失败
preload() 和 load() 都能取得场景资源,但适用时机不同。
| 方式 | 典型场景 | 主要特点 |
|---|---|---|
preload() |
常驻道具、常用子弹、固定敌人类型 | 路径必须是编译时已知的常量字符串,脚本加载时准备依赖资源 |
load() |
根据配置决定的道具类型、进入关卡后才需要的资源 | 可使用运行时路径,但同步加载可能造成等待或卡顿 |
当资源路径由配置决定时,load(path) 返回的是通用资源对象,应先判断 resource is PackedScene,必要时调用 can_instantiate(),确认有效后再执行 instantiate()。不能假设任何加载成功的资源都可以作为场景实例化。
还需要检查以下边界:
- 路径错误或文件缺失:停止创建并报告资源路径,不要继续调用
instantiate()。 - 场景根节点类型不匹配:使用
as Pickup后检查是否为null,避免访问不存在的业务属性。 - 目标父节点已经释放或正在删除:不要继续向其添加子节点。
- 高频生成:缓存已加载的场景资源,避免每次生成都同步读取;资源体积较大时可考虑 Godot 提供的线程化资源加载接口。
验证时可以连续调用 spawn_at() 并传入不同积分和坐标,观察每个方块是否独立出现、信号是否各自发出。稳定的道具生成器应复用场景资源,而把参数配置、节点入树和后续释放交给各自明确的生命周期阶段。