godot-gdscript-patterns

Godot GDScript Patterns

Overview

Godot's building blocks are nodes composed into scenes, signals between them, and Resources for data. GDScript is dynamic by default, which hides typos until runtime and costs speed; typed GDScript catches them at parse time and runs faster. The common failure modes are untyped code, get_node chains reaching up the tree, logic in Resources, and autoloads holding everything.

Core principle: Type everything, compose scenes from small nodes, call down and signal up, keep data in Resources and rules in plain classes.

Type everything

# ❌ untyped: typos and wrong types surface only when this line runs
var speed = 200
func take_damage(amount):
    health -= amount

# ✅ typed: checked when the script parses, faster at runtime
class_name Player extends CharacterBody2D

signal health_changed(current: int, maximum: int)
signal died

@export var definition: PlayerDefinition
@onready var _sprite: AnimatedSprite2D = $AnimatedSprite2D
@onready var _hurtbox: Area2D = %Hurtbox

var health: int

func _ready() -> void:
    health = definition.max_health

func take_damage(amount: int) -> void:
    health = maxi(0, health - amount)
    health_changed.emit(health, definition.max_health)
    if health == 0:
        died.emit()

Turn on Project Settings → Debug → GDScript → untyped_declaration (and unsafe_* warnings) as warnings or errors if the repository has not yet. Typed arrays and dictionaries (Array[Enemy], Dictionary[StringName, int] in 4.4+) everywhere a collection has one element type.

Composition with component nodes

Build behaviour from small reusable child scenes rather than deep inheritance:

Enemy (CharacterBody2D)          enemy.gd: wires components, no rules of its own
├── HealthComponent (Node)       health_component.gd: health, damage(), signal died
├── HitboxComponent (Area2D)     deals damage on overlap
├── HurtboxComponent (Area2D)    forwards hits to HealthComponent
└── StateMachine (Node)          child state nodes: Idle, Chase, Attack