Godot GDScript 编程

要解决什么问题

在 Godot 4.x 里写或改 .gd 脚本时，常见痛点是：静态类型没写全导致解析期才发现错误、3.x 迁到 4.x 后信号与 yield 语法直接报错，以及把节点引用写在 _init() 里、在 _process 里做物理移动这类「能跑但不稳」的用法。本技能面向 Godot 4.3+（GDScript 2.0），帮助按引擎设计方式写 GDScript，而不是堆经验口诀。

技能如何帮你写对脚本

核心工作流可以概括为几条可执行的约定：

• 尽量写静态类型：如 var hp: int = 10、func add(a: int, b: int) -> int:，或用 := 做类型推断，便于解析期报错并减轻 VM 负担。
• 生命周期各用其位：_ready() 做一次性初始化；_process(delta) 做每帧逻辑；移动与物理放在 _physics_process(delta)（例如 move_and_slide()）。
• 用 @onready 拿子节点引用，不要用 _init()——子节点尚未进场景树。
• 用 @export 暴露可在 Inspector 里调的参数；事件优先 信号 + await，避免无意义的轮询。
• 先跑 Debugger，从第一个报错改起，后续错误常常是连锁反应。

模式层面会覆盖：带类型与生命周期的脚本骨架、4.x 的 Callable 信号连接与 emit、await 替代 3.x 的 yield，以及 lambda、类型化数组与安全访问等写法。

适用边界与常见坑

• 场景树、实例化、Autoload → 用 godot-nodes-scenes；信号架构与解耦 → godot-signals-groups；C# 而非 GDScript → godot-csharp。
• 3.x → 4.x：export/onready/tool 等改为 @export、@onready、@tool；connect("x", self, "_on_x") 改为 x.connect(_on_x)；yield(obj, "sig") 改为 await obj.sig。
• 整数除法截断（5 / 2 == 2），需要浮点请用 5.0 / 2 或显式转换。
• class_name 全项目唯一，否则无法在其他脚本或 Inspector 里当作类型使用。