Pins this version in aipm.package.json and aipm-lock.json.
aipm add @affaan-m/godot-patterns@1.0.0
Without project tracking
Writes the skill files only. Add --no-init to skip aipm.package.json and the lockfile.
aipm add @affaan-m/godot-patterns@1.0.0 --no-init
How to use
Install the skill above, then run this in your AI tool:
/godot-patterns <your description>
About
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.
Source
What gets added to your project
Preview every file this package writes on install before you run the command above.
Summary
Idiomatic Godot 4 GDScript patterns - static typing, scene and node design, signals, resources, autoloads, input, and lifecycle safety. Use when writing or reviewing GDScript, designing scenes, or deciding where game state should live.
Skill instructions
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 .gd files
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 RefCounted or Resource classes 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
gdscript
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 (-> void included).
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 StringName literals (&"player") for ids and keys that are compared often.
Cast with as and check the result for null before 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
gdscript
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
gdscript
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:
%UniqueName for nodes inside the same scene.
An @export var target: Node assigned 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
gdscript
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 .tres for read-only data. Call duplicate() before mutating it per instance, otherwise every user of that file changes together.
Use Resources for save data too, but never load a .tres or .res from an untrusted path: Resources can embed scripts. For user-provided saves use JSON or ConfigFile.
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.
gdscript
# 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
gdscript
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 delta for anything you add per frame (position += velocity * delta) but not for move_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).timeout for short delays. Use a Timer node when you need to stop or restart it.
Turn off processing on idle nodes with set_process(false).
Lifecycle Safety
gdscript
# 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 of free() so the node is removed at a safe point in the frame.
@onready variables 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. Use get_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-testing for headless tests of the patterns above
Agent: gdscript-reviewer for review checklists
Skill: python-patterns for the closest typed, snake_case idioms if you are coming from Python
Add this badge to a GitHub README so readers can open the package page and install the same version.
[](https://www.aipm-registry.com/skills/affaan-m/godot-patterns/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)
This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.
AI assistant context
What this skill is for
@affaan-m/godot-patterns@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: Idiomatic Godot 4 GDScript patterns - static typing, scene and node design, signals, resources, autoloads, input, and lifecycle safety. Use when writing or reviewing GDScript, designing scenes, or deciding where game state should live.
Preview a UI component mockup in a local browser canvas where the human directly edits it (move, resize, edit text, delete, restyle), switches mobile/desktop/custom viewports, tests it, chats with you, and clicks Save and Finish. You the...
Run aipm add @affaan-m/godot-patterns@1.0.0 in a project that has AIPM initialized.
Supported tools
@affaan-m/godot-patterns@1.0.0 supports All tools.
Before installing
AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.