---
name: developing-godot-gdscript
description: 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:

```bash
"$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