Godot GDScript (4.x)
Write typed GDScript that parses on the project's Godot version and behaves the way the
engine schedules it, then prove every script compiles. Targets Godot 4.7; read
config/features in project.godot and keep an older project on its own version.
Workflow
- Match the project's version and settings. Check
config/featuresand anydebug/gdscript/warnings/*entries inproject.godot: a warning set to Error (2) fails the parse, andinference_on_variantis an error by default. - Type by default. Annotate members, parameters and returns; use
:=only when the right side has a static type (see Gotchas). Typed code catches mistakes at parse time and runs faster. - Put code in the right callback.
_init(): no tree, no children._ready(): after the children, only the first time the node enters the tree (request_ready()re-arms it)._physics_process(): movement and physics._process(): visuals and UI. - Write coroutines defensively. Anything after
awaitmay run frames later, or never. - Verify before you finish (paths are relative to this skill's folder):
- On a fresh checkout, import first:
godot --headless --path <project> --import. - Run
godot --headless --path <project> --script <this skill>/assets/check_scripts_compile.gd. It loads every.gdwith autoloads andclass_nametypes registered; exit 1 lists eachBROKENfile under the engine's parse error and line. Fix the first error in a file first; later ones are often follow-ons. - Run the main scene briefly and read the log, because Godot exits 0 after runtime errors:
godot --headless --path <project> --quit-after 300 > run.log 2>&1, thengrep -nE "SCRIPT ERROR|^ERROR:" run.log. - For behaviour, write a test with
godot-gdscript-headless-testing. Ifgodot-nodes-scenesis installed,python3 ../godot-nodes-scenes/scripts/check_godot_project.py <project>catches brokenpreload()/load()paths.
- On a fresh checkout, import first:
Patterns
1. A typed node script
class_name Spinner
extends Node2D
@export var speed_deg: float = 90.0
@export_range(0.0, 10.0, 0.5) var wobble := 2.0
@onready var sprite: Sprite2D = $Sprite2D # resolved just before _ready()
func _ready() -> void:
sprite.modulate = Color.AQUA
func _process(delta: float) -> void:
rotation_degrees += speed_deg * delta2. Typing values that come back as Variant
var scores: Dictionary[String, int] = {} # typed dictionary, 4.4+
func best(name: String) -> int:
var s: int = scores.get(name, 0) # get() returns Variant: annotate, don't :=
return s
func label_text() -> String:
var label := get_node_or_null("UI/Score") as Label # returns Node: cast to type it
return label.text if label else ""3. A coroutine that survives its node being freed
func flash() -> void:
modulate = Color.RED
await get_tree().create_timer(0.2).timeout
if not is_inside_tree():
return # removed while we waited (a freed node never gets here at all)
modulate = Color.WHITEGotchas
Cannot infer the type of "x" variable because the value doesn't have a set type→:=got a Variant: an untyped function's return, an untypedDictionary/Arraysubscript, or a member of a value typed as a base class (get_node("X").position, sinceget_node()returnsNode). Write the type (var p: Vector2 = ...) or cast withas.The variable type is being inferred from a Variant value→max(),min(),clamp()andabs()return Variant, and this warning is an error by default. Usemaxi,maxf,clampf,absfand friends.- Code after
awaitnever runs, with no error → the object that emits the signal was freed first (aTimernode, an enemy), or the awaiting node itself was freed. The coroutine is dropped silently, so cleanup andquit()after it never happen. AwaitSceneTreeTimers for delays and check validity after waking (Pattern 3). Identifier "X" not declared in the current scopeon a fresh clone or in CI → theclass_namecache in.godot/does not exist yet. Run--importonce.--check-onlyreportsIdentifier not found: SomeAutoload→--check-onlyparses one file without registering autoloads, so any script that names an autoload fails. Use the bundled compile check instead.Not all code paths return a valueafter upgrading to 4.7 → an override now inherits the parent method's return type even when it does not declare one. Return on every path.- A setter stopped running after upgrading to 4.7 → assigning one element of a packed
array property (
points[0] = v) no longer calls that property's setter. Reassign the whole array. @onreadyvariable is null → the node path is wrong, or code ran before_ready()(for example from_init()or a setter during scene load). Use%UniqueNamefor deep nodes.5 / 2 == 2→ integer division truncates; write5 / 2.0orfloat(a) / b.- 3.x scripts do not parse →
export,onready,toolandyield(obj, "sig")became@export,@onready,@toolandawait obj.sig;setgetbecameset/getblocks. Signalconnect()changes are ingodot-signals-groups.
References
- Read
references/annotations-and-typing.mdfor every@export_*variant, the other annotations (@tool,@icon,@rpc,@warning_ignore,@export_tool_button,@export_storage,@abstract), typed collections, and the full lifecycle order. assets/check_scripts_compile.gdis the compile check used in step 5.
Related skills
godot-signals-groups: signals, Callables and groups.godot-nodes-scenes: scene trees, instancing, autoloads and node paths.godot-resources: customResourceclasses withclass_name.godot-gdscript-headless-testing: test runners and CI.godot-csharp: the same engine through C#.
Version notes
Last verified: 2026-11-11 against the Godot 4.7.2 class reference, the 4.7 migration guide and a 4.7.2 headless run.
- Godot 4.7.2 (August 2026) is the current stable release; 4.8 is in beta.
- Typed dictionaries exist since 4.4;
@abstractclasses and methods since 4.5. - 4.7 behaviour changes: override return-type inheritance, and packed-array element writes no longer calling the property setter.
- Sources: Godot releases, Upgrading to Godot 4.7, Static typing in GDScript, GDScript warning settings.