Godot

Godot 4.x (GDScript + C#)

Build 2D and 3D the way the engine is designed: scenes as reusable units, composition over deep node trees, signals for decoupling, static typing for speed and safety. GDScript (typed) is primary; C# parity snippets sit beside it.

Version contract — read first

This is Godot 4.x. Never emit Godot 3 APIs. Godot 4 renamed core nodes, moved annotations behind @, replaced yield with await, and switched signal/file/tween APIs. A Godot 3 snippet will not even parse in 4.x. Before writing or accepting any line, check it against this ban-list:

Lifecycle overrides must chain the parent with super() (Godot 3 called it implicitly; Godot 4 does not). If you override _ready, _process, _init, etc. in a script that extends another script defining them, call super() / super._ready() or the base logic silently never runs.

Silent-breakers (compile fine, behave wrong — the dangerous class):

• Array.slice(begin, end) — end is now exclusive (was inclusive in Godot 3). [1,2,3,4].slice(1,3) → [2,3].
• Camera2D.zoom is inverted vs Godot 3: a larger zoom now means zoomed in (magnified). Vector2(2,2) = 2× magnification, not half.
• TileMap is deprecated → use one TileMapLayer node per layer (since 4.3).
• Angles are radians; _process(delta) delta is a float (GDScript) / double (C#) in seconds.

Full table with every rename → references/godot3-to-4-traps.md.

Project & scene organization

• The scene (.tscn) is the reusable unit — a self-contained tree you instance many times (a Player, a Bullet, a HUD). Prefer composition: small scenes/nodes assembled, not one 60-node monolith. If a subtree has its own behavior, make it its own scene.
• One responsibility per script. Attach behavior to the scene's root; child nodes are parts.
• class_name Foo registers a global type usable in the inspector and as Foo.new(). Use it for reusable scripts and custom Resources; skip it for one-off scene scripts.
• Files: snake_case.gd / snake_case.tscn for scenes and scripts; PascalCase for node names in the tree and for class_name. Group by feature (player/, enemy/, ui/), not by type.

Nodes vs scenes vs scripts vs custom Resources

Custom Resources are Godot's typed, savable, inspector-editable data objects — reach for them instead of loose Dictionaries or JSON for game data. See references/nodes-scenes-resources.md.

class_name EnemyStats extends Resource
@export var max_health: int = 30
@export var speed: float = 120.0
@export var loot_table: Array[ItemDrop] = []

Autoloads / singletons + EventBus

Register a script or scene as an autoload (Project → Project Settings → Globals/Autoload) to get one always-present instance reachable by name from anywhere. Use it for cross-cutting state (save game, audio, run config) — not as a dumping ground.

The EventBus pattern decouples unrelated systems: an autoload that owns only signals. Emitters and listeners never reference each other, just the bus.

# event_bus.gd  (autoload named "Events")
extends Node
signal enemy_died(position: Vector2, xp: int)
signal score_changed(new_score: int)

# emitter                              # listener (anywhere)
Events.enemy_died.emit(global_position, 10)
Events.enemy_died.connect(_on_enemy_died)

Keep gameplay logic in nodes; let the bus carry the notification, not the behavior.

Node access & lifecycle

• _init() runs at construction (no tree, no @onready yet). _ready() runs once the node and all children are in the tree — do node wiring here.
• @onready var x = $Path defers the assignment to _ready, so the child exists. Never grab children in _init.
• Prefer unique names: mark a node Unique Name in Owner (%) and access %HealthBar instead of the fragile, refactor-breaking get_node("../../UI/HealthBar"). $Foo is fine for a direct child — get_node/$ on a missing path returns null and errors.
• Cache node lookups in @onready vars; don't call get_node every frame.
• Freeing: call queue_free() (safe, end of frame), not free() mid-signal. Guard reused refs with is_instance_valid(node).
• Never busy-wait; await get_tree().create_timer(1.0).timeout or await a signal.

extends CharacterBody2D
@onready var sprite: Sprite2D = $Sprite2D
@onready var health_bar: ProgressBar = %HealthBar   # unique name, position-independent

func _ready() -> void:
    super()                       # chain the parent's _ready if the base defines one
    health_bar.value = 100

Signals

Signals are Godot's decoupling primitive. In Godot 4 you connect a Callable, not strings.

• Declare with typed params; name in the past tense for facts that happened (health_depleted, item_collected), present-tense imperative only for requests.
• Connect: node.signal_name.connect(_on_thing) — a direct method reference, checked at parse time. Add CONNECT_ONE_SHOT for auto-disconnect after one fire.
• Disconnect discipline: a connection to a node that gets freed is cleaned up automatically, but connections you make to long-lived objects (autoloads, the bus) from a short-lived node must be disconnected in _exit_tree(), or use CONNECT_ONE_SHOT, to avoid calls into freed instances.

signal health_depleted
signal health_changed(current: int, max: int)

func take_damage(amount: int) -> void:
    _health -= amount
    health_changed.emit(_health, _max_health)
    if _health <= 0:
        health_depleted.emit()