neon-sprawl-archived/.cursor/rules/gdscript-style.mdc

--- description: GDScript naming, formatting, and Godot-idiomatic patterns (Godot docs style guide). globs: "**/*.gd" alwaysApply: true --- # GDScript style (Neon Sprawl) Follow the [Godot GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_styleguide.html). Prefer clarity and consistency with existing scripts in the repo. ## Naming - **Functions, variables, signals:** `snake_case`. - **Classes** (`class_name`, custom resources): `PascalCase`. - **Constants** (`const`): `ALL_CAPS` when they are true fixed values; otherwise match Godot/node conventions used nearby. - **“Private” / internal:** leading underscore `_like_this` for members meant as implementation detail (not enforced by the language). ## Types and API - Add **static types** on parameters, locals, and return values where reasonable (`-> void`, `var x: int`, etc.). - Prefer **`@export`** (Godot 4) over legacy `export` syntax. - Use **`@onready`** for node references set after the scene tree is ready when that pattern fits. ## Formatting - **One statement per line**; break long lines for readability (Godot line length is flexible—aim for ~100 characters unless a longer string is clearer). - **Indentation:** use **tabs** for new Godot work (editor default). Do not mix tabs and spaces in the same file; match the file if it already uses spaces. - **Blank lines:** separate functions with two blank lines; sparing single blank lines inside functions for logical groups. - **Trailing commas** in multi-line collections/function args when it improves diffs. ## Structure - **`class_name`** only when the type must be referenced globally; otherwise anonymous `extends` is fine. - Order loosely: `extends` → `class_name` → `signals` → `enums` → `const` → `export/@export` → `onready` → other vars → `_ready` / lifecycle → public methods → private helpers. - Virtual overrides (`_ready`, `_process`, `_physics_process`, etc.): keep small; extract helpers with leading `_`. ## Comments - Use `#` comments; document non-obvious **why**, not what the next line literally does. - Doc comments: Godot 4 supports `##` above declarations for the in-editor help—use for public-ish APIs when helpful. ## Anti-patterns - Avoid `get_node()` string paths repeated everywhere; use `@onready`, exports, or groups when scale demands it. - Prefer typed collections and enums over “magic” string/int state when it stays readable.