How to use Cursor or Claude Code for a Godot 4 game jam

Updated 2026-10-17

AI coding agents are fast at GDScript and bad at knowing which GDScript. Most failures in a Godot 4 jam come from three things: Godot 3 APIs, nobody running the project after a change, and a web export that breaks on itch.io. Here's how to handle each.

1. Tell the agent the version and ban Godot 3 APIs

Put the engine version and a "don't write this" table in your rules file. These are the ones agents get wrong most:

Godot 3 (parse error or wrong in 4)	Godot 4
`KinematicBody2D`	`CharacterBody2D`
`move_and_slide(velocity, Vector2.UP)`	set `velocity`, call `move_and_slide()`
`yield(..., "timeout")`	`await get_tree().create_timer(1.0).timeout`
`export var` / `onready var`	`@export var` / `@onready var`
`connect("sig", self, "_m")`	`sig.connect(_m)`
`instance()`	`instantiate()`

In Cursor, scope these rules to **/*.gd, **/*.tscn, project.godot with a .cursor/rules/*.mdc file (the old .cursorrules file is deprecated). In Claude Code put them in CLAUDE.md. Codex reads AGENTS.md.

2. Give the agent a way to check its work

Godot runs headless from the command line, so an agent with a terminal can verify changes. We tested these on Godot 4.7.2:

# once per fresh checkout
godot --headless --path . --import
# parse-check one script
godot --headless --path . --check-only --script res://scripts/player.gd
# run the main scene ~120 frames, see runtime errors and print()
godot --headless --path . --quit-after 120

Feed it a Godot 3 script and the check prints SCRIPT ERROR: Parse Error: "yield" was removed in Godot 4. Use "await" instead. Don't trust the exit code; have the agent search the output for SCRIPT ERROR.

The Godot MCP server (claude mcp add godot -- npx @coding-solo/godot-mcp) goes further: the agent can launch the project and read debug output itself.

3. Export for the web early

Pick the Compatibility renderer when you create the project. The web platform only runs that one.
Leave Thread Support off in the Web preset. Single-threaded export (since Godot 4.3) needs no special server headers, and the Godot docs call it the more compatible option for itch.io.
Install export templates that match your editor version exactly.
Godot 4 C# projects can't export to the web per the official docs. Use GDScript for web jams.

mkdir -p build/web
godot --headless --path . --export-release "Web" build/web/index.html
butler push build/web yourname/yourgame:html5

After the first butler push, set the project kind to HTML and tick "played in the browser" in itch.io's Edit game page. Do the first upload around hour 8, not hour 47.

4. Make the agent manage scope

Keep a JAM.md with the deadline, the core verb, the win/lose condition and a cut list, and tell the agent to read it every session. Rules that pay off: a playable build by hour 6, one system per change, no new dependencies after hour 12, no new mechanics after hour 30.

Get the rules

The Godot rules in this guide are free on GitHub. The full kit adds Phaser and Roblox packs, six roles and the 48h playbook.