Godot Gdscript Agent Skill

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.3+ (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

• 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.

• 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).

• Grab node references with @onready, not in _init() — children do not exist

until the node enters the tree.

• Expose tunables with @export so designers edit them in the Inspector.
• React to events with signals + await, not polling, where it reads cleanly.
• 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 = 90.0          # editable in the Inspector (degrees/sec)
@export_range(0, 10, 0.5) var wobble := 2.0
@onready var sprite: Sprite2D = $Sprite2D # resolved when the node enters the tree

func _ready() -> void:
    # Runs once, after children are ready. Safe to touch $Sprite2D here.
    sprite.modulate = Color.AQUA

func _process(delta: float) -> void:
    # delta is seconds since last frame; multiply rates by it for FPS independence.
    rotation_degrees += speed * delta

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

extends Node

signal health_changed(current: int, maximum: int)   # typed signal params

var health := 100

func take_damage(amount: int) -> void:
    health = max(health - amount, 0)
    health_changed.emit(health, 100)     # 4.x: emit as a method on the signal

func _ready() -> void:
    # 4.x: connect with a Callable, not a string method name.
    health_changed.connect(_on_health_changed)

func _on_health_changed(current: int, maximum: int) -> void:
    print("HP: %d/%d" % [current, maximum])

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

func flash_then_continue() -> void:
    modulate = Color.RED
    await get_tree().create_timer(0.2).timeout   # resume after 0.2s
    modulate = Color.WHITE
    # await any signal: var result = await some_node.some_signal

4. Lambdas, typed arrays, and safe access

var enemies: Array[Node] = []                    # typed array

func cull_dead() -> void:
    enemies = enemies.filter(func(e): return e.is_inside_tree())

func get_first_name(d: Dictionary) -> String:
    return d.get("name", "unknown")              # default avoids missing-key errors

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.