GDScript 速成

## 一个"会说话"的节点：每个生命周期回调被调用时，都往 LifeLog 里写一行。
class_name LifeNode
extends Node

var label := ""
var feeds_timeline := false   # 只有 Root 把每一帧的调用时间记到时间轴上
var process_calls := 0
var physics_calls := 0
var last_callback := ""
var last_usec := 0

var hp = 100                 # 动态类型：以后可以赋任何类型的值
var speed: float = 120.0     # 显式静态类型
var player_name := "Alice"   # := 根据右边的值推断类型（这里是 String），之后不能再赋别的类型
var lives := 3               # 推断为 int
var ratio := 3 / 2           # 两个 int 相除还是 int，结果是 1
var ratio_f := 3 / 2.0       # 只要有一个是 float，结果就是 1.5
const MAX_LIVES := 5         # 常量，不能修改
enum State { IDLE, RUN, JUMP }   # 枚举，本质是一组 int 常量：IDLE=0, RUN=1, JUMP=2
var state := State.IDLE

## 参数和返回值都可以写类型；带默认值的参数要放在后面。
func damage(amount: int, critical := false) -> int:
	var result := amount * 2 if critical else amount   # 三元表达式：值 if 条件 else 值
	hp -= result
	return result


## 没有返回值就写 -> void
func say_hello(who: String) -> void:
	print("你好，%s！" % who)   # % 格式化：%s 字符串，%d 整数，%.2f 两位小数

func control_flow_demo() -> void:
	if hp > 50:
		print("状态良好")
	elif hp > 0:
		print("快不行了")
	else:
		print("倒下了")

	for i in 3:                       # 0, 1, 2（等价于 range(3)）
		print("第 ", i, " 次")
	for i in range(10, 0, -3):        # 10, 7, 4, 1
		print(i)

	var n := 0
	while n < 3:
		n += 1
	print("n = ", n)

func describe(value: Variant) -> String:
	match value:
		0:
			return "零"
		1, 2, 3:
			return "很小"
		"start":
			return "字符串 start"
		[var x, var y]:                       # 数组模式：正好两个元素，并把它们绑定到 x、y
			return "二元数组 %s, %s" % [x, y]
		{"type": "coin", ..}:                  # 字典模式：有 type 键且值是 coin，.. 表示允许有别的键
			return "金币字典"
		var other when other is int and other < 0:   # 守卫条件（4.4 起支持 when）
			return "负数"
		_:
			return "其他"

func arrays_demo() -> void:
	var items := ["剑", "盾", 3]               # 普通数组：什么类型都能放
	var scores: Array[int] = [90, 72, 85]     # 类型化数组：只能放 int
	scores.append(60)
	scores.sort()                             # [60, 72, 85, 90]
	print(scores, " 最高分 ", scores.max(), " 共 ", scores.size(), " 个")
	print(items[0], " / 最后一个：", items[-1])  # 负数下标从末尾数
	var passed := scores.filter(func(s: int) -> bool: return s >= 80)   # [85, 90]
	var doubled := scores.map(func(s: int) -> int: return s * 2)
	print(passed, " ", doubled)
	print("有 72 吗？", 72 in scores)

func dicts_demo() -> void:
	var player := {"name": "Alice", "hp": 100, "pos": Vector2(3, 4)}
	player["hp"] -= 30
	player.level = 2                          # 键是字符串时，也可以用点号读写
	print(player.name, " hp=", player["hp"], " 等级 ", player.get("level", 1))
	print("有 mp 键吗？", player.has("mp"), "  mp 默认 ", player.get("mp", 0))
	for key in player:                        # 遍历的是键（按插入顺序）
		print(key, " -> ", player[key])
	var stock: Dictionary[String, int] = {"苹果": 3, "香蕉": 5}   # 类型化字典（4.4 起）
	stock["苹果"] += 1
	print(stock)

@export var max_speed := 300.0                 # 出现在检查器里，可以在编辑器里改
@export_range(0, 100, 5) var armor := 20       # 带范围的滑块
@export var tint := Color.WHITE
@export_enum("战士", "法师", "弓手") var job := "战士"
@export_group("掉落")                           # 检查器里的分组标题
@export var drop_table: Array[String] = ["金币"]

@onready var label: Label = $Label             # 等节点进树、_ready() 之前才取值
@onready var start_pos := position             # 也可以是任意表达式

## 当前显示哪个小场景。网页上切换时，Tuning 会直接给它赋值，setter 负责换场景。
@export_enum("太阳系", "信号实验室", "生命周期") var scene := "太阳系":
	set(value):
		scene = value
		if is_node_ready():
			_load_scene()

## 属性的 setter / getter：赋值时自动执行一段代码。
var health := 100:
	set(value):
		health = clampi(value, 0, max_health)   # 在 setter 里给自己赋值，不会再次触发 setter
		if health == 0:
			print("倒下了")
	get:
		return health

var max_health := 100
var is_alive: bool:                             # 只有 getter 的"计算属性"
	get:
		return health > 0

@export var physics_ticks := 60:            ## 每秒物理帧数
	set(value):
		physics_ticks = value
		Engine.physics_ticks_per_second = value
@export var time_scale := 1.0:              ## 时间缩放：传给回调的 delta 会乘上它
	set(value):
		time_scale = value
		Engine.time_scale = value
@export var paused := false:                ## 暂停场景树
	set(value):
		paused = value
		if is_inside_tree():
			get_tree().paused = value
@export var physics_interpolation := false: ## 物理插值：让低物理帧率下的移动也显得平滑
	set(value):
		physics_interpolation = value
		if is_inside_tree():
			get_tree().physics_interpolation = value

## 内部类：写在别的类里面的类。适合只在这个文件里用的小数据结构。
class Item:
	var name: String
	var price: int

	func _init(p_name: String, p_price := 1) -> void:   # 构造函数，new() 的参数传到这里
		name = p_name
		price = p_price

	func _to_string() -> String:                          # print() 时显示的文字
		return "%s(%d 金)" % [name, price]


func make_items() -> Array[Item]:
	return [Item.new("药水", 5), Item.new("钥匙")]

## static：属于"类"本身，不属于某个实例。不用创建对象就能调用。
static var created_count := 0      # 所有实例共享的一个变量

static func lerp_color(a: Color, b: Color, t: float) -> Color:
	return a.lerp(b, t)


func _init() -> void:
	created_count += 1

## 生命周期日志：一个只有静态成员的类，任何地方都能直接 LifeLog.write(...)。
## 用静态变量是因为 _init() 被调用时节点还不在场景树里，没法用 get_node 去找别的节点。
class_name LifeLog
extends RefCounted

const WINDOW_USEC := 1_500_000            # 时间轴显示最近 1.5 秒

static var entries: Array[Dictionary] = []
static var max_frame_logs := 3            # 每个节点只记录前几次 _process/_physics_process
static var process_times: Array[int] = []    # 最近 1.5 秒内每次 _process 的时间戳（微秒）
static var physics_times: Array[int] = []
static var last_process_delta := 0.0
static var last_physics_delta := 0.0


static func write(who: String, callback: String, extra := "") -> void:
	entries.append({"who": who, "cb": callback, "extra": extra,
		"frame": Engine.get_process_frames(), "usec": Time.get_ticks_usec()})
	if entries.size() > 300:
		entries.pop_front()

func lambda_demo() -> void:
	var square := func(x: int) -> int: return x * x    # 把函数存进变量，类型是 Callable
	print(square.call(7))                              # 49

	var counter := 0
	var add := func() -> void: counter += 1            # lambda 捕获的是外部变量当时的"值"
	add.call()
	print("counter 还是 ", counter)                    # 0：基本类型按值捕获

	var hits: Array[int] = []
	var record := func(n: int) -> void: hits.append(n)  # 数组是引用类型，改的是同一个数组
	record.call(5)
	print("hits = ", hits)                             # [5]

	var words := ["banana", "fig", "apple"]
	words.sort_custom(func(a: String, b: String) -> bool: return a.length() < b.length())
	print(words)                                       # ["fig", "apple", "banana"]

## 带 await 的函数就是"协程"：执行到 await 时先返回，等信号来了再从这里接着往下走。
func countdown() -> void:
	for i in range(3, 0, -1):
		print("倒计时 ", i)
		await get_tree().create_timer(0.5).timeout    # 等 0.5 秒（SceneTreeTimer 的 timeout 信号）
	print("出发！")


func ask() -> String:
	var text: String = await answered               # 等这个信号，并拿到它的参数
	return "收到回答：" + text


func await_demo() -> void:
	print("A：调用 countdown 之前")
	countdown()                                     # 没写 await：不等它，马上往下走
	print("B：countdown 已经开始，但还没结束")
	await countdown()                               # 写了 await：等它整个执行完
	print("C：第二次倒计时结束")

A：调用 countdown 之前
倒计时 3
B：countdown 已经开始，但还没结束
倒计时 3
倒计时 2
倒计时 2
倒计时 1
倒计时 1
出发！
出发！
C：第二次倒计时结束

func _init(p_label := "") -> void:
	label = p_label
	_log("_init", "还不在场景树里")


func _enter_tree() -> void:
	_log("_enter_tree")


func _ready() -> void:
	_log("_ready", "子节点都已就绪")


func _process(delta: float) -> void:
	process_calls += 1
	if feeds_timeline:
		LifeLog.tick(false, delta)
	if process_calls <= LifeLog.max_frame_logs:
		_log("_process", "delta = %.4f" % delta)


func _physics_process(delta: float) -> void:
	physics_calls += 1
	if feeds_timeline:
		LifeLog.tick(true, delta)
	if physics_calls <= LifeLog.max_frame_logs:
		_log("_physics_process", "delta = %.4f" % delta)


func _exit_tree() -> void:
	_log("_exit_tree")


func _notification(what: int) -> void:
	if what == NOTIFICATION_PREDELETE:
		_log("PREDELETE", "对象真正被释放")

func respawn() -> void:
	if is_instance_valid(_root):
		_root.free()                          # 立即删除：马上触发 _exit_tree
	LifeLog.write("", "", "———— 重新生成 ————")
	_root = LifeNode.new("Root")              # _init() 在这一行被调用，此时还不在场景树里
	_root.name = "Root"
	_root.feeds_timeline = true
	for i in child_count:
		var child := LifeNode.new("Child%d" % (i + 1))
		child.name = child.label
		_root.add_child(child)                # Root 还不在树里，所以这里不会触发 _enter_tree
		if i == 0:
			var grand := LifeNode.new("GrandChild")
			grand.name = grand.label
			child.add_child(grand)
	_next_id = child_count + 1
	specimens.add_child(_root)                # 整棵树一起进树：先 _enter_tree，再 _ready

func add_child_node() -> void:
	if not is_instance_valid(_root):
		return
	LifeLog.write("", "", "———— 添加子节点 ————")
	var child := LifeNode.new("Child%d" % _next_id)
	child.name = child.label
	_next_id += 1
	_root.add_child(child)          # Root 已经在树里，新节点马上 _enter_tree、_ready


func remove_child_node() -> void:
	if not is_instance_valid(_root) or _root.get_child_count() == 0:
		return
	var last := _root.get_child(-1)
	LifeLog.write("", "", "———— %s.queue_free() ————" % last.name)
	last.queue_free()               # 不会立刻删除，等这一帧结束才 _exit_tree