Fixing Claude (and Other AIs) Writing Godot 3 Code in Godot 4
In short: models were trained on years of Godot 3 code. Fix it in three layers. State the version and ban Godot 3 explicitly. Give a wrong → right table. Make the agent run godot --headless --check-only so any Godot 3 code fails loudly.
Why it happens
Godot 3 was the main version for years, and most tutorials, forum answers and GitHub code out there are Godot 3. Without explicit context, a model fills in "Godot" with the most common pattern it has seen. The mistakes are predictable:
| Godot 3 (what the AI writes) | Godot 4 |
|---|---|
yield(timer, "timeout") | await timer.timeout |
KinematicBody2D | CharacterBody2D |
move_and_slide(velocity, Vector2.UP) | set velocity, then move_and_slide() |
export var hp = 3 | @export var hp: int = 3 |
onready var s = $Sprite | @onready var s: Sprite2D = $Sprite2D |
connect("hit", self, "_on_hit") | hit.connect(_on_hit) |
scene.instance() | scene.instantiate() |
change_scene("res://x.tscn") | change_scene_to_file("res://x.tscn") |
File.new() | FileAccess.open(path, FileAccess.READ) |
update() | queue_redraw() |
There is a second family of errors: Python-isms. These include def, None, True, f-strings, try/except and list comprehensions. GDScript looks like Python but isn't.
Fix 1: pin the version up front
Put this at the top of CLAUDE.md: "This is a Godot 4.x project. GDScript 2.0 only; never Python, never Godot 3 APIs." Also tell the agent to read config/features in project.godot, which records the exact version.
Fix 2: give pairs, not principles
"Use modern Godot 4 APIs" is too vague to change behaviour. A table of exact wrong → right pairs works much better. Claude's docs ask for instructions that are "concrete enough to verify". Keep CLAUDE.md under ~200 lines so the table isn't buried.
Fix 3: make the engine the judge
Godot 3 syntax fails to parse in Godot 4. For example, extends KinematicBody2D followed by export var gives Parse Error: Unexpected "Identifier" in class body. Have the agent run this after every edit:
godot --headless --path . --check-only --script res://path/to/file.gdThen have it fix the errors before it says "done". This turns a silent quality problem into an immediate, visible one.
Fix 4: keep sessions short
Adherence drops as the conversation grows. Work one feature per session, keep progress in PLAN.md, and start fresh when the feature is done.
FAQ
Will the official converter fix AI output?
Godot 4's project upgrade tool (--convert-3to4) is for converting whole 3.x projects. It isn't meant to clean up snippets, and it doesn't convert everything (setters and getters, for example). Prevent the problem at the source instead.