游戏引擎 / 系统课时
延迟调用怎样安全修改场景树
延迟调用怎样安全修改场景树
碰撞信号触发时,物理引擎可能仍在处理重叠查询。此刻直接禁用碰撞形状或移除碰撞节点,容易触发受保护状态的修改错误。本课构造一个自动重叠的小场景,把请求排入延迟队列,记录两个时刻,并在真正执行前检查对象是否还有效。
学习目标
- 识别物理回调中直接修改碰撞对象的风险,并用延迟操作修复。
- 使用弱引用、删除标记与父级检查,避免执行过期请求。
- 区分安全时机的延迟调用与明确等待下一次帧信号。
为什么物理回调不能随意修改节点
Area2D.body_entered 可能在物理空间查询处理期间发出。若直接把 CollisionShape2D.disabled 改为 true,或立即从场景树移除正在参与检测的 StaticBody2D,就可能出现物理查询正在刷新(flushing queries)时不允许更改状态的报错。问题不在于“不能删除”,而在于“不能在这个时机改”。
set_deferred("disabled", true) 把属性赋值排到安全时机;call_deferred("_remove_obstacle", ...) 则安排整个方法稍后执行。两者不是延迟若干毫秒,也不保证一定跨过一个渲染帧。

用自动重叠场景验证延迟移除
在 Godot 4.6 中新建一个以 Node2D 为根节点的空场景,将以下脚本附加到根节点并运行当前场景。脚本自行创建同位置的 Area2D 与 StaticBody2D,默认碰撞层和掩码均包含第 1 层,因此会在物理检测开始后收到一次 body_entered。
extends Node2D
var _sensor_shape: CollisionShape2D
var _handled := false
func _ready() -> void:
var sensor := Area2D.new()
sensor.name = "Sensor"
add_child(sensor)
_sensor_shape = CollisionShape2D.new()
var circle := CircleShape2D.new()
circle.radius = 30.0
_sensor_shape.shape = circle
sensor.add_child(_sensor_shape)
var obstacle := StaticBody2D.new()
obstacle.name = "Obstacle"
add_child(obstacle)
var obstacle_shape := CollisionShape2D.new()
var rect := RectangleShape2D.new()
rect.size = Vector2(24.0, 24.0)
obstacle_shape.shape = rect
obstacle.add_child(obstacle_shape)
sensor.body_entered.connect(_on_body_entered)
func _on_body_entered(body: Node2D) -> void:
if _handled or body.name != "Obstacle":
return
_handled = true
print("请求变更 ms=", Time.get_ticks_msec(), " tick=", Engine.get_physics_frames())
# 物理查询期间不立即修改碰撞形状
_sensor_shape.set_deferred("disabled", true)
# 弱引用不阻止节点被其他逻辑销毁
call_deferred("_remove_obstacle", weakref(body))
func _remove_obstacle(body_ref: WeakRef) -> void:
var body := body_ref.get_ref() as Node2D
if not is_instance_valid(body) or body.is_queued_for_deletion():
print("跳过:目标已失效")
return
if body.get_parent() != self:
print("跳过:父级已改变")
return
print("执行变更 ms=", Time.get_ticks_msec(), " tick=", Engine.get_physics_frames())
remove_child(body)
body.queue_free()
print("已安全移除 Obstacle")预期输出(正常路径;<TIME> 为引擎运行毫秒数,<TICK> 为物理帧计数,实际值随运行而变):
请求变更 ms=<TIME> tick=<TICK>
执行变更 ms=<TIME> tick=<TICK>
已安全移除 Obstacle为了复现错误,可以在测试副本中暂时将 _sensor_shape.set_deferred("disabled", true) 改为直接设置 _sensor_shape.disabled = true,把延迟调用改为在回调中直接 remove_child(body)。运行时可能在调试器中看到与物理查询锁定相关的报错;具体提示因版本和物理后端而异。恢复延迟写法,确认报错消失。
执行前再次检查对象的状态
入队与执行之间,其他系统可能已对同一对象调用 queue_free()、完成释放或将其移动到别的父节点。WeakRef.get_ref() 对已释放对象返回 null;is_instance_valid() 防止访问无效对象;is_queued_for_deletion() 排除已预约释放的节点;父级检查避免误删已被接管的对象。
_handled 负责避免同一次接触重复排队。如果在其他逻辑中先对障碍物执行 queue_free(),延迟方法应打印“跳过:目标已失效”,而不是继续操作。不要仅凭请求时缓存的节点路径或固定等待时间推断目标仍存在。
延迟调用与等待下一帧的区别
| 做法 | 实际语义 | 合适用途 |
|---|---|---|
call_deferred() |
在空闲安全阶段调用方法,可能仍在当前帧结束前执行 | 避开物理查询中的结构修改 |
set_deferred() |
将单个属性赋值推迟执行 | 安全禁用碰撞形状 |
await get_tree().process_frame |
等待下一次渲染处理帧前的信号 | 确实需要跨到后续处理帧 |
await get_tree().physics_frame |
等待下一次物理处理前的信号 | 明确与物理步同步 |
如果业务需要下一帧的状态,应等待相应帧信号,并在 await 之后重新校验对象;如果只是要避开受限制的回调,则优先使用延迟调用。通过请求与执行的日志判断顺序,不能用“等 0.1 秒再试”代替正确的同步边界。