idle/.agents/skills/developing-godot-gdscript/SKILL.md

name, description

name	description
developing-godot-gdscript	Builds and refactors Godot 4 projects with idiomatic GDScript, scene composition, signals, and autoload patterns. Use when implementing gameplay, UI, tools, or architecture changes in Godot/GDScript repositories.

Developing Godot With GDScript

Implements production-friendly Godot 4 changes using typed GDScript, scene composition, and low-coupling architecture.

Use This Skill When

• Adding or refactoring gameplay systems, UI flows, or content pipelines in Godot.
• Debugging node lifecycle, signals, resources, or autoload behavior.
• Improving maintainability, style consistency, or data flow in GDScript code.

Core Rules

1. Prefer composition over deep inheritance: split reusable behavior into scenes/resources/scripts with focused responsibilities.
2. Choose scenes for reusable node trees and editor-authored structure; choose scripts/resources for logic and data that do not need node hierarchy.
3. Use autoloads only for truly global state/services (save systems, global config, cross-scene coordinators), not as default dependency injection.
4. Favor signals over direct cross-tree mutation to reduce coupling between gameplay, UI, and services.
5. Use typed GDScript where possible: annotate variables, params, and return types for safer refactors.

GDScript Implementation Checklist

1. Keep naming idiomatic: snake_case for vars/functions/signals, PascalCase for class_name, UPPER_SNAKE_CASE for constants.
2. Use @export for editor-facing configuration and @onready only for scene-dependent node lookups.
3. Respect lifecycle intent: _init for construction data, _enter_tree for tree attachment concerns, _ready for node wiring, _process/_physics_process for frame loops.
4. Distinguish frame loops clearly: use _physics_process for deterministic physics movement and _process for visual or non-physics updates.
5. Use match for clear branching on enums/states and keep functions short with early returns.

Data, Loading, And Error Handling

1. Guard all file access (FileAccess.open) and JSON parsing before indexing into parsed values.
2. Validate dynamic data types (is Dictionary, is Array) before field access to avoid runtime surprises.
3. Use preload for stable, frequently used compile-time resources; use load for optional or dynamic runtime assets.
4. Prefer Resource/RefCounted for plain data models when node features are unnecessary.
5. Use assert/push_error for invalid states that should fail loudly during development.

Delivery Workflow

1. Read project.godot first to identify autoloads, rendering/physics settings, and project conventions.
2. Inspect relevant .tscn + .gd pairs together before editing to preserve scene-script contracts.
3. Implement minimal, targeted changes that keep public APIs/signals stable unless change is requested.
4. Run headless validation and script checks for touched scripts; run project smoke test when feasible.
5. Summarize changed files, behavior impact, and any follow-up risks.

Validation Commands

Use project-provided commands when available. Typical Godot checks:

"$GODOT_BIN" --headless --path . --quit
"$GODOT_BIN" --headless --check-only --script res://path/to/changed_script.gd

References

• https://docs.godotengine.org/en/stable/tutorials/best_practices/index.html
• https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html