godot-gdscript-patterns
Use when writing Godot 4 GDScript - static typing everywhere, scene composition with component nodes, call down/signal up, @onready caching, Resources as data duplicated per instance, autoloads only for services, state machines, pooling, physics in _physics_process, and threaded loading.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- godot-gdscript-patterns
- source
- wshobson/agents godot-gdscript-patterns (MIT), adapted; Godot 4 documentation cited
- category
- architecture
- tech_stack
- Godot
- description
- Use when writing Godot 4 GDScript - static typing everywhere, scene composition with component nodes, call down/signal up, @onready caching, Resources as data duplicated per instance, autoloads only for services, state machines, pooling, physics in _physics_process, and threaded loading.
03 SKILL.md 正文
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
Each component exports its dependencies (@export var health: HealthComponent) so the scene wires them in the inspector, and each is testable alone.
Call down, signal up
# ❌ reaching up and across the tree: breaks when the scene is reused or rearranged
func _on_hit() -> void:
get_parent().get_parent().get_node("UI/HUD").update_health(health)
# ✅ the child emits; whoever owns both connects them
# in level.gd:
func _ready() -> void:
player.health_changed.connect(hud.show_health)
- Parents call methods on children they own; children announce events with signals.
- Connect in code with Callables (
button.pressed.connect(_on_start_pressed)) or in the editor — follow the repository. @onready(or%UniqueNamefor unique-in-owner nodes) caches node references once; neverget_node()or$Pathinside_process.
Resources: data, duplicated per instance
class_name PlayerDefinition extends Resource
@export var max_health: int = 100
@export var move_speed: float = 180.0
@export var dash_curve: Curve
- Resources hold data, not behaviour (no gameplay logic, no node references).
- A loaded
.tresis shared by everyone who loads it. Runtime state goes on the node, ordefinition.duplicate()per instance, orresource_local_to_scenefor sub-resources edited per scene. - Never load user-provided
.tres/.resfiles: they can carry scripts (game-save-and-persistence).
Autoloads sparingly
Autoloads are global singletons. Acceptable for services: scene loading, save, audio, settings, an event bus for genuinely global events. Not for the current level's state, the player's health or anything a test needs to reset. A level's data belongs to the level scene.
State machines
Small: an enum and a match. Larger: a StateMachine node with one child node per state (enter(), exit(), physics_update(delta), handle_input(event)), transitions requested by name, and the legal transitions tested (game-state-machines-and-ai).
enum State { IDLE, CHASE, ATTACK }
var _state := State.IDLE
func _physics_process(delta: float) -> void:
match _state:
State.IDLE:
if _target_in_range(definition.aggro_range): _change(State.CHASE)
State.CHASE:
_chase(delta)
if _target_in_range(definition.attack_range): _change(State.ATTACK)
State.ATTACK:
pass
Physics, processing and pooling
CharacterBody2D/3D: setvelocity, callmove_and_slide()in_physics_process(delta).RigidBody: forces/impulses, or_integrate_forces(state)for direct control — never setpositionon it every frame.- Turn off what is idle:
set_process(false)/set_physics_process(false),process_mode = PROCESS_MODE_DISABLED,VisibleOnScreenEnabler2D/3Dfor off-screen enemies. - Pool frequent spawns (bullets, hit effects): pre-instantiate, hide and disable processing on return, reset state on reuse — never
queue_free()+instantiate()every shot. - Groups (
add_to_group("enemies"),get_tree().get_nodes_in_group(...)) for broadcast queries, not for per-frame lookups in hot loops.
Loading and awaiting
- Big scenes:
ResourceLoader.load_threaded_request(path)at a loading screen, pollload_threaded_get_status, thenload_threaded_get(game-asset-pipeline). awaiton a signal of a node that may be freed hangs or errors; checkis_instance_valid(node)after awaits that span frames.
Project hygiene
- Commit
.importfiles and, from 4.4, the.uidfiles beside scripts and shaders; ignore.godot/. - Keep the editor version pinned in
config/features; opening the project in a newer minor rewrites files.
Common Mistakes
- Untyped variables and functions in new code.
get_node("../../UI/HUD")orget_parent()chains for communication.- Mutating a shared
.tresat runtime. - An autoload per feature, holding level state.
- Moving a
RigidBodyby setting its position.
Red Flags
$Pathorget_nodeinside_process/_physics_process.- A Resource script with methods that change game state.
queue_free()andinstantiate()for projectiles fired many times a second.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns