godot-gdscript

Godot GDScript (4.x)

Write correct, statically typed GDScript and use the node lifecycle and signal system the way the engine intends. Targets Godot 4.7 (GDScript 2.0).

When to use

• Use when writing or fixing .gd files: declaring variables, functions, classes, using @export/@onready, connecting signals, or awaiting coroutines/signals.
• Use when porting Godot 3.x scripts to 4.x and the script no longer parses.

When not to use: scene/node structure and instancing questions → godot-nodes-scenes; signal architecture/decoupling patterns → godot-signals-groups; using C# instead of GDScript → godot-csharp.

Core workflow

1. Type everything you can. GDScript 2.0 supports static types (var hp: int = 10, func add(a: int, b: int) -> int:). Types catch errors at parse time and speed up the VM. Use := for inferred types.
2. Use the lifecycle callbacks for their purpose: _ready() once when the node and its children enter the tree; _process(delta) every rendered frame; _physics_process(delta) on the fixed physics tick (use it for movement/physics).
3. Grab node references with @onready, not in _init() — children do not exist until the node enters the tree.
4. Expose tunables with @export so designers edit them in the Inspector.
5. React to events with signals + await, not polling, where it reads cleanly.
6. Run and read errors. The Debugger panel prints typed errors with line numbers; fix the first error first (later ones are often cascades).

Patterns

1. A typed script with lifecycle, @export, and @onready

extends Node2D
class_name Spinner            # registers a global type usable in other scripts
 
@export var speed: float =

2. Signals: declare, emit, connect (4.x Callable syntax)

3. await — pause until a timer or signal fires (replaces 3.x yield)

4. Lambdas, typed arrays, and safe access

Pitfalls

• 3.x → 4.x signal API changed. emit_signal("x") still works but prefer x.emit(...); connect("x", self, "_on_x") is gone — use x.connect(_on_x) with a Callable. yield(obj, "sig") is now await obj.sig.
• export var is now @export var (annotation). Likewise onready→@onready, tool→@tool, remote/master RPC keywords → the @rpc(...) annotation.
• @onready and $NodePath in _init() fail — the node isn't in the tree yet. Initialize node references in _ready() or with @onready.
• Integer division truncates. 5 / 2 == 2. Use 5.0 / 2 or cast to float.
• _process vs _physics_process. Put move_and_slide() and physics in _physics_process(delta); using _process makes motion frame-rate dependent.
• class_name must be unique project-wide and is required to use the type name in other scripts or as an Inspector type.

References

• For the full annotation list, advanced typing, and style conventions, read references/annotations-and-typing.md.

Related skills

• godot-nodes-scenes — the scene tree, instancing, and autoloads.
• godot-signals-groups — event-driven architecture with signals and groups.
• godot-resources — data-driven design with custom Resource types.
• godot-csharp — the same engine concepts using C#/.NET.