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 (typechecker, performanceanalyzer, signalarchitecturevalidator) 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 queuefree() or getclass() is unsupported and will be ignored by engine callbacks.
• NEVER use dynamic getnode() 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 pusherror(), pushwarning(), or breakpoints.
• NEVER pre-load huge resources in ready() — Use ResourceLoader.loadthreaded_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

MANDATORY: [typedcollectionsmastery.gd](scripts/typedcollectionsmastery.gd), [arraypreallocationperf.gd](scripts/arraypreallocationperf.gd), [typechecker.gd](scripts/typechecker.gd) (EditorScript audit).

2. Signal Architecture

MANDATORY: [typedsignaldefinitions.gd](scripts/typedsignaldefinitions.gd), [signalarchitecturevalidator.gd](scripts/signalarchitecturevalidator.gd).

3. Node Access & Lifecycle Safety

MANDATORY: [safetypecasting.gd](scripts/safetypecasting.gd).

4. Callable & Signal (First-Class)

MANDATORY: [callablebindingcontext.gd](scripts/callablebindingcontext.gd), [unbindsignalargs.gd](scripts/unbindsignalargs.gd), [advancedlambdas.gd](scripts/advancedlambdas.gd), [functionallambdalogic.gd](scripts/functionallambdalogic.gd).

5. Async, Statics & Safe Collections

MANDATORY: [awaitsequencemanager.gd](scripts/awaitsequencemanager.gd), [staticvarsingletonalt.gd](scripts/staticvarsingletonalt.gd), [dictionarysafeiteration.gd](scripts/dictionarysafeiteration.gd), [performanceanalyzer.gd](scripts/performanceanalyzer.gd) (EditorScript).

Script Catalog (all files)

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 → classname → 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](references/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 → classname → 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 getnode/$ 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.