Godot 场景架构
场景拆分、节点引用、节点通信、状态机、暂停与场景切换的约定。
默认结构:一个概念一个 .tscn,脚本挂在场景根,对外只露 @export 属性、信号和少量方法。
范围
| 不含 |
去哪 |
内容摆进 .tscn 还是代码生成、脚本生成场景文件 |
godot-scene-authoring |
| 具体节点用法 |
godot-2d godot-3d godot-ui godot-animation |
Resource 当数据、存档 |
godot-resources-data |
@tool 与编辑器插件 |
godot-editor-tooling |
| C# 信号、导出、生命周期写法 |
godot-csharp |
| 失焦自动暂停、设置界面 |
godot-ui |
| 屏幕外停用、大量实体 |
godot-performance |
| 收尾音效、同时多声 |
godot-audio |
先查内置
| 需求 |
用这个 |
别自己写 |
| 可复用对象 敌人 子弹 面板 |
独立 .tscn + PackedScene.instantiate() |
代码 new 整棵节点树 |
| 同场景内的节点引用 |
%UniqueName 或 @onready 缓存 |
长路径 get_node("A/B/C"),每帧 get_node |
| 场景外的目标引用 |
@export var target: Node2D |
写死 /root/Main/Level/Player |
| 一类对象批量通知 |
add_to_group + get_tree().call_group |
手写注册表数组,全局事件总线 |
| 子对象通知父对象 |
信号 |
子节点 get_parent().foo() |
| 全局共享数据 |
自定义 Resource,或 autoload 只放全局状态 |
Manager 套 Manager |
| 状态切换 |
enum + match、状态子节点、AnimationTree |
一串 is_jumping is_attacking bool |
| 暂停菜单 |
SceneTree.paused + Node.process_mode |
每个脚本判断 is_paused |
| 多个场景共用逻辑 |
class_name 组件节点 |
复制粘贴,深继承链 |
| 场景切换 |
change_scene_to_file、change_scene_to_packed |
手动 free 旧场景再 add_child |
| 非节点的纯逻辑对象 |
RefCounted 或 Resource |
继承 Node 只为存数据 |
做法
实例化
class_name Bullet
extends Area2D
var direction: Vector2 = Vector2.RIGHT
var speed: float = 400.0
func _physics_process(delta: float) -> void:
position += direction * speed * delta
class_name Spawner
extends Node2D
@export var bullet_scene: PackedScene
func fire(dir: Vector2) -> void:
var bullet := bullet_scene.instantiate() as Bullet
bullet.direction = dir
get_parent().add_child(bullet)
bullet.global_position = global_position
- 初始参数在
add_child 前设,_ready 里可读
global_position 在 add_child 后设
add_child 前设 global_position:2D 按本地坐标算,3D 报错
- 场景引用用
@export var scene: PackedScene,文件移动后引用不断
- 同脚本内固定不变的小场景可用
preload
- 代码生成节点并存进
PackedScene 时,每个节点设 owner,见 references/lifecycle.md
节点引用
extends Node2D
@export var target: Node2D
@export_node_path("Marker2D") var spawn_path: NodePath
@onready var score: Label = %ScoreLabel
@onready var sprite: Sprite2D = $Sprite2D
@onready var spawn: Marker2D = get_node(spawn_path)
func _process(_delta: float) -> void:
if target != null:
look_at(target.global_position)
| 写法 |
用于 |
$Name |
直接子节点 |
%Name |
同场景更深的节点,先在场景面板右键 Access as Unique Name |
@export var x: Node2D |
场景外的目标,Inspector 里连 |
get_node_or_null |
节点可能不存在 |
- 引用用
@onready 缓存为带类型成员,不在 _process 里取
@export 节点引用在 instantiate() 返回时已解析
@export 节点引用在 _enter_tree 和 _ready 可用,_init 里是 null
- 代码
instantiate() 的场景,场景外的引用由调用方赋值
通信
原则 call down, signal up。
| 方向 |
做法 |
| 父到子 |
直接调方法或设属性 |
| 子到父 |
子 emit 信号,父 connect |
| 兄弟之间 |
经共同父节点转发,或各自 @export 对方 |
| 子需要父提供的行为 |
父把方法赋给子的 Callable 属性 |
class_name Health
extends Node
signal changed(current: int, maximum: int)
signal died
@export var maximum: int = 100
@onready var current: int = maximum
func damage(amount: int) -> void:
current = maxi(current - amount, 0)
changed.emit(current, maximum)
if current == 0:
died.emit()
extends CharacterBody2D
@onready var health: Health = $Health
func _ready() -> void:
health.died.connect(queue_free)
- 信号名用过去式:
died item_collected
- 信号只报告已发生的事,要对方做事就调方法
- 成员初始化器读
@export 得到脚本默认值
- 依赖 Inspector 所设值的初值用
@onready
- 编辑器 Node 面板连的信号存在
.tscn,改方法名无提示。优先脚本里 connect
分组
extends Node2D
func raise_alarm() -> void:
get_tree().call_group("guards", "alert", global_position)
- 分组用作一类对象的广播通道,不当全局注册表
- 加入分组:节点面板 Groups 页签,或
add_to_group("guards")
call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) 帧末执行,遍历中会增删节点时用
- 场景唯一对象用
get_first_node_in_group("player"),_ready 里取一次并缓存
Autoload
用于跨场景存活的全局状态:存档槽、设置、场景切换器、跨关卡任务进度。change_scene_to_* 不释放 autoload。
[autoload]
Settings="*res://src/autoload/settings.gd"
- 能放进场景的就放进场景
- 不做全局音效池,场景自带
AudioStreamPlayer
* 对应面板 Enable 列,开启后 GDScript 才有全局名
- C# 不读
*,自己写静态 Instance 属性
- autoload 的
_ready 早于主场景加载,取不到场景节点
- 共享函数用
class_name + static func,不需要 autoload
- 共享数据用自定义
Resource,不需要 autoload
- 不建 GameManager、EventBus、UIManager
- 不建信号总线,收发方无法追踪
组合与继承
class_name HurtBox
extends Area2D
@export var health: Health
func _ready() -> void:
area_entered.connect(_on_area_entered)
func _on_area_entered(area: Area2D) -> void:
if area is HitBox:
health.damage(area.damage)
class_name HitBox
extends Area2D
@export var damage: int = 1
| 手段 |
用于 |
限制 |
| 组件子节点 |
多种对象共有的行为,如 Health HurtBox,不建 Damageable 基类 |
宿主用 @export 传入,不用 get_parent() |
| 脚本继承 |
同类事物的细分 |
一层,要第三层先拆组件 |
| 继承场景 |
同一模板的变体,如换贴图和数值的敌人 |
父场景改结构影响所有变体 |
Editable Children |
改子场景内部节点 |
改动存在宿主场景,父场景改结构后易失效 |
状态机
暂停
SceneTree.paused 为 true 时,可暂停的节点停止 _process、_physics_process 和输入,物理模拟一并暂停。
extends Control
func _ready() -> void:
process_mode = Node.PROCESS_MODE_ALWAYS
hide()
func _unhandled_input(event: InputEvent) -> void:
if event.is_action_pressed("pause"):
get_tree().paused = not get_tree().paused
visible = get_tree().paused
get_viewport().set_input_as_handled()
process_mode |
未暂停 |
暂停时 |
用于 |
PROCESS_MODE_INHERIT 默认 |
同父级 |
同父级 |
普通节点,根节点按 PAUSABLE |
PROCESS_MODE_PAUSABLE |
运行 |
停止 |
游戏内容 |
PROCESS_MODE_WHEN_PAUSED |
停止 |
运行 |
暂停菜单内容 |
PROCESS_MODE_ALWAYS |
运行 |
运行 |
切换暂停的节点、背景音乐、转场 |
PROCESS_MODE_DISABLED |
停止 |
停止 |
关掉整棵子树 |
create_timer 的 process_always 默认 true,暂停时照常计时
PROCESS_MODE_DISABLED 不拦截已连接的信号,见 references/lifecycle.md
Node.set_process(false) 只停 _process,不停 _physics_process 和输入
陷阱
| 现象 |
做法 |
子节点 _ready 里父节点未就绪 |
_ready 子先于父。依赖子节点的初始化放在父的 _ready |
queue_free() 后 is_instance_valid 仍为 true |
帧末才释放。判断销毁中用 is_queued_for_deletion() |
物理回调里改碰撞体报 Can't change this state while flushing queries 或 Function blocked during in/out signal |
set_deferred 或 call_deferred,见 references/lifecycle.md |
手写 .tscn 的 @export 节点属性运行时为 null |
节点头写 node_paths=PackedStringArray(...),见 references/lifecycle.md |
%Name 取不到 |
跨实例化子场景无效。代码 add_child 的节点要设 owner |
await get_tree().process_frame 报错 |
树外 get_tree() 为 null,先 add_child |
change_scene_to_* 后 current_scene 为 null |
帧末才切换,见 references/scene-switching.md |
| 节点释放后 lambda 回调报错 |
用方法引用连接,对象释放时自动断开 |
每帧 get_node find_child get_nodes_in_group,或 ../Sibling 路径 |
@onready 缓存,或改 @export 和信号 |
一个 Level.gd 管相机、HUD、生成、计时 |
按职责拆子场景,Level 只组装 |
参考