godot-gdscript-mastery

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 0c0182b848c3 · 28 Oct 2026Report an issue or request a re-scan

• Publisherthedivergentai GitHub userOwner of the repository this skill is read from
• Source folderthedivergentai/gd-agentic-skills/skills/godot-gdscript-masteryThe exact folder we audited
• LicenceLGPL-3.0As the repository states it
• Commit pinned for this verdict0c0182b848c3A new audit runs when the source changes
• Repository statusNot archivedLast push 11 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Expert GDScript landmine guidance: static typing opcodes, signal-up/call-down, %UniqueName/@onready lifecycle, Callable bind/unbind, await sequences, typed collections, and safe Dictionary iteration. Use for code…

---
name: godot-gdscript-mastery
description: "Expert GDScript landmine guidance: static typing opcodes, signal-up/call-down, %UniqueName/@onready lifecycle, Callable bind/unbind, await sequences, typed collections, and safe Dictionary iteration. Use for code review, refactoring hot paths, or project standards. Trigger keywords: static_typing, signal_architecture, unique_nodes, @onready, class_name, signal_up_call_down, Callable.bind, typed_collections, await_sequence."
---

# 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](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-version-migration/SKILL.md) (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](scripts/typed_collections_mastery.gd), [array_preallocation_perf.gd](scripts/array_preallocation_perf.gd), [type_checker.gd](scripts/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](scripts/typed_signal_definitions.gd), [signal_architecture_validator.gd](scripts/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](scripts/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](scripts/callable_binding_context.gd), [unbind_signal_args.gd](scripts/unbind_signal_args.gd), [advanced_lambdas.gd](scripts/advanced_lambdas.gd), [functional_lambda_logic.gd](scripts/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](scripts/await_sequence_manager.gd), [static_var_singleton_alt.gd](scripts/static_var_singleton_alt.gd), [dictionary_safe_iteration.gd](scripts/dictionary_safe_iteration.gd), [performance_analyzer.gd](scripts/performance_analyzer.gd) (EditorScript).

## Script Catalog (all files)

| Script | When to open |
|---|---|
| [typed_collections_mastery.gd](scripts/typed_collections_mastery.gd) | Typed Array/Dictionary opcodes |
| [functional_lambda_logic.gd](scripts/functional_lambda_logic.gd) | `reduce` / `all` / `any` |
| [advanced_lambdas.gd](scripts/advanced_lambdas.gd) | Higher-order Callables |
| [safe_type_casting.gd](scripts/safe_type_casting.gd) | `as` + null checks |
| [typed_signal_definitions.gd](scripts/typed_signal_definitions.gd) | Typed signal boundaries |
| [callable_binding_context.gd](scripts/callable_binding_context.gd) | `bind()` context injection |
| [unbind_signal_args.gd](scripts/unbind_signal_args.gd) | `unbind()` arity trim |
| [await_sequence_manager.gd](scripts/await_sequence_manager.gd) | Non-blocking await flows |
| [array_preallocation_perf.gd](scripts/array_preall

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/thedivergentai/gd-agentic-skills
git -C gd-agentic-skills checkout 0c0182b848c3

Works in

1. 2026-10-28
   ✓SAFE B 89 / 100

   first audit · source 0c0182b848c3

Questions about godot-gdscript-mastery

• github.com/thedivergentai/gd-agentic-skills/tree/main/skills/god — the audited source at commit 0c0182b848c3 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology