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

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

2. Signal Architecture

MANDATORY: typed_signal_definitions.gd, signal_architecture_validator.gd.

3. Node Access & Lifecycle Safety

MANDATORY: safe_type_casting.gd.

4. Callable & Signal (First-Class)

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

5. Async, Statics & Safe Collections

MANDATORY: await_sequence_manager.gd, static_var_singleton_alt.gd, dictionary_safe_iteration.gd, performance_analyzer.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 → 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.