Godot 场景架构

场景拆分、节点引用、节点通信、状态机、暂停与场景切换的约定。

默认结构：一个概念一个 .tscn，脚本挂在场景根，对外只露 @export 属性、信号和少量方法。

范围

先查内置

做法

实例化

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)

• 引用用 @onready 缓存为带类型成员，不在 _process 里取
• @export 节点引用在 instantiate() 返回时已解析
• @export 节点引用在 _enter_tree 和 _ready 可用，_init 里是 null
• 代码 instantiate() 的场景，场景外的引用由调用方赋值

通信

原则 call down, signal up。

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

状态机

• 所有转移走一个入口函数，进出逻辑放在里面

暂停

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()

• create_timer 的 process_always 默认 true，暂停时照常计时
• PROCESS_MODE_DISABLED 不拦截已连接的信号，见 references/lifecycle.md
• Node.set_process(false) 只停 _process，不停 _physics_process 和输入

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/lifecycle.md：回调顺序、构造期设值、owner、手写 .tscn 的 node_paths、call_deferred、释放与失效引用、禁用时的信号
• references/scene-switching.md：change_scene_to_* 行为、自己做切换、加载界面
• references/enum-state.md：enum 加 match 完整示例
• references/state-machine.md：状态子节点模板、AnimationTree 状态机
• https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html