godot-gdscript-mastery

GDScript Mastery

Expert guidance for writing performant, maintainable GDScript — Godot-landmine decision trees, not a style-guide reprint.

Do NOT Load

• Do not load this skill for general prose style or Godot engine version upgrades (3→4 / 4.x hops) — those live in godot-version-migration (plus official upgrading guides via that hub).
• Do not preload every script below; open only the MANDATORY pointer for the Core Directive you are implementing.
• Do not treat EditorScript utilities (type_checker, performance_analyzer, signal_architecture_validator) as runtime gameplay code.

NEVER Do in GDScript

• NEVER use @onready and @export on the same variable — Initialization order will cause @onready to overwrite the Inspector value.
• NEVER modify a Dictionary's size while iterating it — Use dict.keys().duplicate() or iterate a clone to safely erase elements.
• NEVER use string-based connect("signal", ...) — Always use the Signal object syntax (button.pressed.connect(...)) for compile-time safety.
• NEVER attempt to override non-virtual native engine methods — Overriding queue_free() or get_class() is unsupported and will be ignored by engine callbacks.
• NEVER use dynamic get_node() or $ inside _process() — Fetching paths every frame stalls the CPU. Cache and use @onready.
• NEVER use Parent.method() calls — Violates "Signal Up, Call Down". Use signals to communicate with parents.
• NEVER use is followed by a hard cast — If the type check passes but the object changes, it crashes. Use as and check for null.
• NEVER use print() for production debugging — Use push_error(), push_warning(), or breakpoints.
• NEVER pre-load huge resources in _ready() — Use ResourceLoader.load_threaded_request() for async loading.
• NEVER use global variables in Autoloads when static var is sufficient — Static variables offer better encapsulation.

---

Core Directives (decision trees + MANDATORY scripts)

1. Strong Typing & Performance

Landmine	Decision
Hot path still Variant?	Annotate vars/returns; prefer typed collections
Generic math in _process?	Use typed helpers (absf, ceili, clampf)
Green safe-lines missing?	Fix inference with := or explicit types

MANDATORY: typed_collections_mastery.gd, array_preallocation_perf.gd, type_checker.gd (EditorScript audit).

2. Signal Architecture

Landmine	Decision
Child needs parent reaction?	Emit signal up — never call parent methods
Cross-script payload unsafe?	Typed signal name(arg: Type)
Connect visibility?	Prefer _ready() connects over invisible editor-only wiring

MANDATORY: typed_signal_definitions.gd, signal_architecture_validator.gd.

3. Node Access & Lifecycle Safety

Landmine	Decision
Need child nodes?	@onready / %UniqueName — never in _init()
Scene-instanced node with ctor args?	Use @export injection — _init(args) breaks PackedScene.instantiate()
Path lookup every frame?	Cache once; never $ / get_node in _process

MANDATORY: safe_type_casting.gd.

4. Callable & Signal (First-Class)

Landmine	Decision
Extra context on callback?	Callable.bind(...)
Discard unused signal args?	Callable.unbind(n)
One-off timeout logic?	Inline lambda OK; keep refs if create_callback-style longevity matters

MANDATORY: callable_binding_context.gd, unbind_signal_args.gd, advanced_lambdas.gd, functional_lambda_logic.gd.

5. Async, Statics & Safe Collections

Landmine	Decision
Sequence timers without threads?	await chains — see await manager
Global state without Autoload bloat?	static var (+ nullify large statics when done)
Erase while iterating Dictionary?	Clone keys first

MANDATORY: await_sequence_manager.gd, static_var_singleton_alt.gd, dictionary_safe_iteration.gd, performance_analyzer.gd (EditorScript).

Script Catalog (all files)

Script	When to open
typed_collections_mastery.gd	Typed Array/Dictionary opcodes
functional_lambda_logic.gd	reduce / all / any
advanced_lambdas.gd	Higher-order Callables
safe_type_casting.gd	as + null checks
typed_signal_definitions.gd	Typed signal boundaries
callable_binding_context.gd	bind() context injection
unbind_signal_args.gd	unbind() arity trim
await_sequence_manager.gd	Non-blocking await flows
array_preallocation_perf.gd	resize() pre-alloc
static_var_singleton_alt.gd	Lightweight global state
dictionary_safe_iteration.gd	Safe erase-while-iterate
type_checker.gd	EditorScript typing audit
performance_analyzer.gd	EditorScript hot-path scan
signal_architecture_validator.gd	EditorScript signal-up checks

Quick Landmines

• Prefer dict.get("key", default) over dict["key"] when presence is uncertain.
• Toggle Access as Scene Unique Name and read via %Name for critical UI/nodes.
• Script layout order: extends → class_name → signals/enums/consts → exports/onready → lifecycle → public → _private.

Expert knowledge (on demand)

LLM-ignorance rule: If a general agent would not know it before reading, load the reference — never delete expert deltas.

• gdscript-core-directives.md — restored baseline pedagogy (architecture, WHY, implementation depth)

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• GDScript basics — Language core for typed vars/funcs, signal declarations, await, and first-class Callables this skill standardizes.
• GDScript style guide — Canonical script order (extends → class_name → signals → exports → lifecycle → methods) used in reviews and refactoring.
• Static typing in GDScript — Why typed Arrays/Dictionaries and return types unlock optimized opcodes and editor safe-lines.
• GDScript: An introduction to dynamic languages — Lambdas, higher-order Callables, and advanced patterns behind filter/map/reduce helpers.
• GDScript warning system — Turn unsafe casts, unused signals, and untyped hot paths into CI-visible warnings.
• Logic preferences — When to prefer declarative signals vs imperative calls so scripts stay decoupled.
• Scene organization — Official “signal up, call down” ownership rules this skill enforces.
• Using signals — Connect/emit model and why string-based connect-by-name is avoided.
• Callable — bind() / unbind() APIs for injecting or discarding callback arguments without wrapper nodes.
• Array — Typed arrays, resize(), and functional methods (filter/map/reduce/all/any) used in the scripts.
• Dictionary — Safe .get() defaults and why size must not change while iterating keys.
• CPU optimization — Cache @onready / %UniqueName instead of get_node/$ inside _process loops.

Related Skills

Prerequisites

• godot-project-foundations — Project layout, Autoload registration, and scene ownership conventions that typed GDScript scripts plug into.
• godot-composition — Component boundaries clarify which scripts own signals vs call-down APIs before style enforcement.

Complements

• godot-version-migration — Engine version upgrades (3→4 language breaks, 4.x hops); this skill stays on current GDScript 2.0 idioms.
• godot-signal-architecture — Deepens connect flags, buses, and sequencers after this skill’s typed signal/Callable basics.
• godot-autoload-architecture — Contrasts heavy Autoloads with the static var singleton alternatives shown here.
• godot-resource-data-patterns — Prefer Resources for shared config; keep GDScript modules thin and typed around Resource payloads.
• godot-scene-management — @onready, unique names, and await sequences must stay valid across scene swaps and loaders.
• godot-testing-patterns — Typed signals and Callables make watch_signals / spies reliable in unit tests.
• godot-debugging-profiling — Pair style/perf smells from this skill with profiler and custom monitors when hot paths remain slow.
• godot-state-machine-advanced — FSM enter/exit handlers should follow the same typed-signal and await sequencing conventions.

Downstream / consumers

• godot-performance-optimization — Escalate when typed GDScript alone is not enough; servers, pooling, and broader CPU/GPU tactics live there.
• godot-auditor — Project-wide audits consume the typing, signal-up, and hot-path rules codified in this skill.
• godot-ability-system — Abilities need typed signal payloads and await-safe cooldowns grounded in these language patterns.
• godot-combat-system — Damage/death fan-out depends on typed emits and safe casts taught here.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting scripting concern.