All 5 AI packs for $39 →
← ToolTier Library
Cursor rules · Free

Cursor rules for Godot 4 (GDScript typing, style, signals)

A free Cursor rule (.mdc) for Godot 4 GDScript projects: static typing, the official style guide's naming and code order, signals up and references down, _physics_process vs _process, and Input Map actions.

Install
.cursor/rules/godot.mdc
Last tested
Cursor / Godot 4.7 docs · 2026-11-05

AI assistants write a lot of Godot 3 habits and untyped GDScript: hard-coded key checks, long get_node("../../Thing") paths, physics movement in _process, and scripts with no types at all. This rule steers Cursor's agent to current Godot 4 conventions. It's an Apply to Specific Files rule (globs is **/*.gd, alwaysApply is false), so it attaches whenever a .gd file is in play.

It follows Godot's own documentation, checked on November 5, 2026, when the latest stable release on GitHub was 4.7.2: the GDScript style guide (snake_case files, functions and signals, PascalCase classes, past-tense signal names, the recommended code order), the static typing guide (typed arrays everywhere, typed dictionaries from Godot 4.4, and the warning that the as keyword silently returns null on a mismatch), the scene organization guide (children signal up, owners pass references down, signals respond rather than start behavior) and the idle and physics processing guide (physics bodies move in _physics_process).

Replace the [bracketed] values with your engine version and test command, and delete the Input Map or autoload lines if you handle those differently. Building a game to ship? Our free Steam page prompts cover the store side, and the Indie Game Launch Kit has the full 12-month plan. Add an AGENTS.md at the repo root if you also use other coding agents.

godot.mdc
---
description: Godot 4 GDScript conventions: static typing, official style guide naming and code order, signals up and references down, _process vs _physics_process, Input Map actions. Use when editing .gd scripts or Godot scenes.
globs: **/*.gd
alwaysApply: false
---

# Godot 4 + GDScript

Engine: Godot [4.x]. If something here disagrees with the installed engine version or the official docs (docs.godotengine.org), the docs win. Never invent a node, method or signal name; check the class reference or the existing code first.

## Commands
- Run the project: `[godot --path . ]`. Run a scene: `[godot --path . res://scenes/main.tscn]`.
- Tests: `[GUT | gdUnit4 | none]`: `[command]`. Never say a change works unless you ran it or the user did. Report the command and the result.

## Types
- Use static typing everywhere: typed variables, parameters and return types (`func take_damage(amount: int) -> void:`). Use `:=` when the type is obvious from the value.
- Type collections: `Array[Enemy]`, and `Dictionary[String, int]` on Godot 4.4 or later. Nested typed collections such as `Array[Array[int]]` are not supported, so don't write them.
- Give shared scripts a `class_name` so they can be used as types. One script, one responsibility.
- Casting: `as` silently returns `null` on a mismatch. Use it only when `null` is the answer you want. To assert a type, use `is`, `is not` or `assert(x is Foo)`.

## Style (based on the official GDScript style guide)
- File names `snake_case.gd` (class `YAMLParser` lives in `yaml_parser.gd`). Classes, nodes and enum names `PascalCase`. Functions, variables and signals `snake_case`. Constants and enum members `CONSTANT_CASE`.
- Prefix private variables, private functions and virtual methods you override with a single underscore: `_health`, `_recalculate_path()`.
- Name signals in the past tense: `door_opened`, `score_changed`.
- Indent with tabs, keep lines under 100 characters, use a trailing comma in multi-line arrays, dictionaries and enums, and write each enum member on its own line.
- Use `and`, `or`, `not`, not `&&`, `||`, `!`. Put `##` doc comments on every exported variable, signal and public method.
- Order a script like this: `@tool`/`@icon`, `class_name`, `extends`, `##` doc comment, signals, enums, constants, `@export` variables, other variables, `@onready` variables, built-in virtual methods (`_init`, `_enter_tree`, `_ready`, `_process`, `_physics_process`), public methods, private methods, inner classes.

## Scenes and communication
- Signals go up, references go down. A child announces what happened with a signal; its parent or owner connects to it and decides what to do. Signals respond to behavior, they don't start it.
- Don't reach up or sideways with long `get_node("../../Other")` paths. The owner of two nodes passes the reference, `NodePath`, `Callable` or signal connection between them, so a scene still works when reused elsewhere.
- Cache child nodes once with `@onready var _sprite: Sprite2D = $Sprite2D` (or an `@export` reference) instead of calling `get_node()` or `$` every frame.
- Connect signals with the Callable syntax: `button.pressed.connect(_on_button_pressed)`, and emit with `door_opened.emit()`. Name handlers `_on_<node>_<signal>`.
- Use an autoload only for state or services that really are global (settings, a signal bus, save data). Don't put gameplay logic that belongs to one scene in an autoload.
- Expose tunable values with `@export` (with `@export_range` where a range makes sense) instead of magic numbers in code.

## Processing and input
- Anything that moves a physics body goes in `_physics_process(delta)`. Use `_process(delta)` for visuals and other per-frame updates. Multiply speeds by `delta` in `_process`.
- Read input through Input Map actions (`Input.is_action_pressed("move_left")`, `Input.get_vector(...)`), never hard-coded keys, so players can rebind. Add new actions in Project Settings, and tell the user you did.
- Free nodes with `queue_free()`, not `free()`, unless you have a specific reason.

## Never
- Edit `project.godot`, `.import` files or `.godot/` by hand unless asked. Don't hand-edit `.tscn` or `.tres` files for large changes; describe the scene change for the user to make in the editor, or keep edits small and exact.
- Add an addon or a dependency without asking.
- Leave `print()` debugging in finished code. Use `push_warning()` or `push_error()` for real problems.
Works with: Cursor
CursorGodotGDScriptGame dev

← More free rules, templates and prompts

+ Your logo here