GDScript 写法

GDScript 语言层的写法与陷阱：类型、注解、信号、协程、对象有效性、警告。断言与日志见 references/syntax.md。目标 4.7，最低 4.4，更新的特性标版本号。

范围

先查内置

做法

静态类型

extends Node

var speed: float = 200.0
var hp := 10
var names: Array[String] = []
var scores: Dictionary[StringName, int] = {}
var target: Node2D

func take_damage(amount: int) -> bool:
	hp -= amount
	return hp <= 0

func _ready() -> void:
	var raw: Dictionary = {"k": 1}
	var value: int = raw["k"]
	var sprite := get_node_or_null("Sprite") as Sprite2D
	print(value, sprite)

• Array[T] 运行时强制元素类型，filter() 保留元素类型
• Dictionary[K, V] 4.4+，不支持再嵌套类型
• 循环变量写类型：for n: Node in nodes:
• 大量数值用 PackedFloat32Array，Array[float] 仍是 Variant 数组
• 对象类型可为 null，数值与字符串类型不可

class_name 与 preload

• class_name Foo 注册全局类，任何脚本可直接当类型和构造
• 类名不能与 autoload 同名，报 Class "Foo" hides an autoload singleton
• 类名不能与引擎类同名
• 无 class_name 的脚本用常量引用，preload 参数须是常量字符串
• 路径运行时才定用 load()

const Rifle := preload("res://weapons/rifle.gd")

var main_weapon: Rifle = Rifle.new()

• 两个脚本互相 preload 在 4.7 可加载，仍建议用 class_name 打断环
• @export 类型只能是内置类型、Resource、Node、枚举
• 3.x 的 export var onready var yield connect("sig", obj, "method") 在 4.x 都没了

注解

extends Node2D

@export var speed: float = 200.0
@export_range(0.0, 1.0, 0.01) var ratio := 0.5
@export_enum("Idle", "Run") var mode: int = 0
@export_file("*.tscn") var next_scene: String
@export var bullet_scene: PackedScene
@export var spawn_point: Marker2D
@export_flags_2d_physics var hit_mask: int

@export_group("Loot")
@export var drops: Array[Resource] = []

@onready var label: Label = %Label
@onready var timer: Timer = $Timer

func _ready() -> void:
	timer.start()
	label.text = str(speed)

全表见 references/annotations.md。

• @export 的类型来自标注或默认值，都没有是解析错误，要 Variant 写 : Variant
• @export var n: Node 只在 Node 派生脚本里可用
• setter 里用节点前判断 is_node_ready()
• @onready 与 @export 同用是错误 onready_with_export
• 成员默认值里用 $ 不带 @onready 是错误 get_node_default_without_onready
• 代码 add_child() 的节点直接赋成员，不需要 @onready
• 场景里已存的属性值覆盖脚本的新默认值
• 导出 Resource 随场景一起加载，大资源用 @export_file 存路径，用时 load()
• 4.5+ @export_file 存 UID，要原始路径用 @export_file_path
• @export_tool_button("名字") 4.4+，须配 @tool

信号

extends Node

signal died
signal damaged(amount: int, source: Node)

@export var button: Button

func _ready() -> void:
	button.pressed.connect(_on_pressed)
	damaged.connect(_log_damage.bind("player"))
	died.connect(queue_free, CONNECT_ONE_SHOT)

func _on_pressed() -> void:
	damaged.emit(3, self)

func _log_damage(amount: int, _source: Node, tag: String) -> void:
	print(tag, amount)

• bind() 的参数追加在发射参数之后，unbind(n) 丢掉末尾 n 个发射参数
• 同一 Callable 连两次返回 ERR_INVALID_PARAMETER 并打印错误，先 is_connected()
• CONNECT_ONE_SHOT 触发一次后断开，CONNECT_DEFERRED 推迟到帧末
• 接收者释放时连接自动断开，lambda 捕获 self 成员时也一样
• 只由外部发射的信号加 @warning_ignore("unused_signal")
• emit() 不检查参数类型，接收方法参数类型不符时调用报错

extends Node

func _ready() -> void:
	var stats: Dictionary = {"count": 0}
	var bump := func() -> void:
		stats["count"] += 1
	bump.call()
	bump.call()
	print(stats["count"])

• lambda 创建时按值捕获局部变量一次
• lambda 里 count += 1 只改副本，触发 confusable_capture_reassignment
• 要回写就捕获 Array、Dictionary 或对象，改其内容

await 与协程

extends Node

signal answered(choice: int)

func open_door(door: Node3D) -> void:
	await get_tree().create_timer(1.0).timeout
	if not is_inside_tree() or not is_instance_valid(door):
		return
	door.hide()

func ask() -> int:
	var choice: int = await answered
	return choice

• await 之后先检查 is_inside_tree() 和目标 is_instance_valid()
• 要清理的状态放 _exit_tree() 或 tree_exiting 里复位
• create_timer 默认暂停时也走，要受暂停影响第二参数传 false
• 等一帧 await get_tree().process_frame，等物理帧 physics_frame
• 没有内置超时，用 Timer 的 timeout 和业务信号谁先到谁处理

对象有效性

• 物理回调、信号回调、遍历子节点时释放用 queue_free()
• _init() 里节点不在树内，get_node() 失败

Callable 与延迟调用

extends Node

func _ready() -> void:
	var child := Node.new()
	add_child.call_deferred(child)
	set_deferred(&"process_mode", Node.PROCESS_MODE_DISABLED)
	var sorted: Array[int] = [3, 1, 2]
	sorted.sort_custom(func(a: int, b: int) -> bool: return a > b)

• call_deferred 在当前帧空闲阶段末尾执行，返回值永远是 null
• 物理回调里改碰撞形状、Area2D.monitoring、CollisionShape2D.disabled 用 set_deferred
• 线程里碰场景树只能 call_deferred
• 方法引用写 _on_pressed，不写 Callable(self, "_on_pressed")
• callable.is_valid() 判断绑定对象是否还在

警告设置

项目设置 debug/gdscript/warnings/*，0 忽略、1 警告、2 错误，高级设置里可见。全表见 references/warnings.md。全类型化项目建议：

[debug]

gdscript/warnings/untyped_declaration=2
gdscript/warnings/missing_await=2
gdscript/warnings/narrowing_conversion=2
gdscript/warnings/int_as_enum_without_cast=2
gdscript/warnings/unassigned_variable=2

• 单句忽略 @warning_ignore("unused_signal")
• 区域忽略 @warning_ignore_start 与 @warning_ignore_restore
• directory_rules 默认忽略 res://addons

陷阱

match、静态成员、setter、super 的完整写法见 references/syntax.md。

参考

• references/annotations.md：导出与其他注解全表
• references/syntax.md：match、静态成员、StringName、setter、super、可变参数与抽象类、断言与日志
• references/warnings.md：全部警告与默认值
• https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html
• https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/static_typing.html
• https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_exports.html
• https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/warning_system.html