Godot 4 GDScript Patterns
Idiomatic patterns for Godot 4.x projects written in GDScript. Verified against the Godot 4.7 documentation; most guidance applies to every 4.x release.
When to Activate
- Writing or reviewing
.gdfiles - Designing a scene tree or deciding which node owns what
- Choosing between a signal, a direct call, an autoload, or a Resource
- Debugging "node not found", freed-object, or signal-connection errors
- Structuring a game so its logic can be tested without running the renderer
Core Principles
- Type everything. Typed GDScript catches bugs at parse time and speeds up the editor.
- Call down, signal up. A parent may call methods on its children. A child announces events with signals and never reaches up to its parent.
- Keep game logic out of Nodes where you can. Plain
RefCountedorResourceclasses can be tested headlessly. Nodes should draw and forward input. - Data lives in Resources, not in scripts full of constants.
- Autoloads are global state. Use as few as you can and treat each one as a public API.
Static Typing
class_name Inventory
extends RefCounted
## A bag of item counts. Pure data and rules: no Node, so tests can run headlessly.
signal item_added(item_id: StringName, new_count: int) ## typed signal parameters
const MAX_STACK: int = 99 ## typed constant
var _counts: Dictionary[StringName, int] = {} ## typed Dictionary (Godot 4.4+)
## Adds `amount` of an item and returns how many were actually added.
func add(item_id: StringName, amount: int) -> int:
var current: int = _counts.get(item_id, 0)
var added: int = mini(amount, MAX_STACK - current) # clamp to the stack limit
if added <= 0:
return 0
_counts[item_id] = current + added
item_added.emit(item_id, _counts[item_id]) # Signal.emit(), not emit_signal()
return added
Rules of thumb:
- Annotate parameters and return types (
-> voidincluded). - Use
:=when the type is obvious from the right-hand side, and an explicit type when it is not. - Use typed arrays (
Array[Enemy]) and, on 4.4+, typed dictionaries. - Use
StringNameliterals (&"player") for ids and keys that are compared often. - Cast with
asand check the result fornullbefore using it.
File Layout and Naming
| Thing | Convention | Example |
|---|---|---|
| Files and folders | snake_case |
player_controller.gd |
Classes (class_name) |
PascalCase |
PlayerController |
| Functions, variables | snake_case |
take_damage() |
| Private members | leading _ |
_speed |
| Constants, enum values | CONSTANT_CASE |
MAX_LIVES |
| Signals | past-tense snake_case |
health_changed |
Order inside a script (from the official style guide): class_name, extends, doc comment, signals, enums, constants, @export vars, public vars, private vars, @onready vars, then methods. Put built-in callbacks (_init, _ready, _process) before your own methods.
Scene and Node Design
Call down, signal up
class_name Player
extends CharacterBody2D
## The player owns a Health child and listens to it. Health knows nothing about Player.
@onready var _health: Health = %Health # %Name = scene-unique node, survives re-parenting
func _ready() -> void:
# Listen UP the tree via the child's signal (child -> parent communication).
_health.died.connect(_on_died)
func _on_died() -> void:
queue_free() # parent decides what death means
class_name Health
extends Node
## A reusable component. It emits events and never touches its parent.
signal died
signal changed(current: int, maximum: int)
@export var maximum: int = 10 # tweakable per scene in the inspector
var current: int = maximum
func damage(amount: int) -> void:
current = maxi(current - amount, 0)
changed.emit(current, maximum)
if current == 0:
died.emit()
Wiring siblings without hard paths
Avoid get_node("../../UI/Label"). It breaks whenever the tree changes. Prefer, in order:
%UniqueNamefor nodes inside the same scene.- An
@export var target: Nodeassigned in the inspector. - A signal that a common ancestor connects.
- Groups (
add_to_group("enemies"),get_tree().get_nodes_in_group("enemies")) for "all of a kind" queries.
Signals
- Connect with a
Callable:button.pressed.connect(_on_pressed). - For one-shot reactions use
CONNECT_ONE_SHOT. - Disconnect or
queue_free()on teardown. A connection to a freed object is cleaned up automatically, but a long-lived emitter holding a Callable to a short-lived object that is still alive keeps it reacting. - Bind extra arguments with
.bind():slot.pressed.connect(_on_slot.bind(slot_index)). - Do not use signals for hot per-frame data. Read the value directly.
Resources for Data
class_name WeaponData
extends Resource
## Designer-editable weapon stats stored as a .tres file. No logic beyond small helpers.
@export var display_name: String = ""
@export var damage: int = 1
@export var cooldown_seconds: float = 0.5
@export var icon: Texture2D
## Damage per second, derived so it is never stored twice and cannot drift.
func dps() -> float:
return damage / cooldown_seconds
- Share one
.tresfor read-only data. Callduplicate()before mutating it per instance, otherwise every user of that file changes together. - Use Resources for save data too, but never load a
.tresor.resfrom an untrusted path: Resources can embed scripts. For user-provided saves use JSON orConfigFile.
Autoloads (Singletons)
Good uses: an event bus, settings, scene-transition manager, save system. Bad uses: anything that holds per-level state and must reset on restart.
# events.gd, registered in Project Settings > Globals > Autoload as "Events"
extends Node
## A tiny global event bus. Keep it to cross-scene events only.
signal player_died
signal score_changed(new_score: int)
Treat each autoload name as a public API. Document it, and do not let gameplay code reach into its private fields.
Process Callbacks and Timing
| Callback | Use for |
|---|---|
_physics_process(delta) |
Movement, physics, anything tied to the physics tick |
_process(delta) |
Visuals, UI, interpolation |
_input(event) / _unhandled_input(event) |
Discrete input events; prefer _unhandled_input for gameplay so UI can consume events first |
func _physics_process(delta: float) -> void:
# Input.get_vector reads four named actions and returns a normalised 2D direction.
var direction: Vector2 = Input.get_vector(&"move_left", &"move_right", &"move_up", &"move_down")
velocity = direction * speed # speed is units per second, so no delta needed here
move_and_slide() # move_and_slide() applies delta internally
- Scale by
deltafor anything you add per frame (position += velocity * delta) but not formove_and_slide(). - Define input as InputMap actions in Project Settings, never as hard-coded keys, so rebinding and gamepads work.
- Use
await get_tree().create_timer(1.0).timeoutfor short delays. Use aTimernode when you need to stop or restart it. - Turn off processing on idle nodes with
set_process(false).
Lifecycle Safety
# BAD: the enemy may be freed before the timer fires.
await get_tree().create_timer(2.0).timeout
enemy.take_damage(5)
# GOOD: check the reference is still valid after every await.
await get_tree().create_timer(2.0).timeout
if is_instance_valid(enemy):
enemy.take_damage(5)
- Use
queue_free()instead offree()so the node is removed at a safe point in the frame. @onreadyvariables are only valid after the node enters the tree. Never read them in_init.- A node removed with
remove_child()is not freed. Free it yourself or it leaks. get_node()on a missing path errors at runtime. Useget_node_or_null()when absence is legitimate.
Anti-Patterns
| Anti-pattern | Why it hurts | Instead |
|---|---|---|
| Untyped everything | Bugs surface at runtime, weak autocomplete | Annotate types |
One 2,000-line main.gd |
Untestable, merge conflicts | Split into components and RefCounted logic classes |
Child calls get_parent().foo() |
Hidden coupling, breaks when reused | Emit a signal |
Deep get_node("../../..") paths |
Breaks on any tree change | %Unique names, exports, groups |
| Magic numbers in scripts | Needs a code change to tune | @export or a Resource |
| Mutating a shared Resource | Changes every instance | duplicate() first |
| Gameplay in autoloads | Leaks state across restarts | Scene-owned nodes, reset on load |
Hard-coded KEY_* checks |
No rebinding or gamepad | InputMap actions |
Related
- Skill:
godot-testingfor headless tests of the patterns above - Agent:
gdscript-reviewerfor review checklists - Skill:
python-patternsfor the closest typed, snake_case idioms if you are coming from Python
