61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
---
|
|
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
|