quiccsite

Using Claude Code with Godot: A Setup Guide for Game Devs

2026-03-11

Claude Code works surprisingly well with Godot once you set it up properly (if you're working with Unity instead, see our Unity guide). The challenge is that LLMs have limited GDScript training data compared to languages like Python or TypeScript. Here's how to bridge that gap.

The problem

Claude knows GDScript syntax — it's Python-like, so the model can reason about it. But it doesn't deeply know Godot's 850+ API classes, the scene tree lifecycle, or engine-specific quirks. It'll hallucinate Python idioms that look right but fail to compile.

Basic setup

1. Install Claude Code

If you haven't already:

npm install -g @anthropic-ai/claude-code

2. Create a CLAUDE.md for your Godot project

This is the most important step. You need to teach Claude about your project's Godot patterns (see our CLAUDE.md guide for general best practices):

Godot 4 game project using GDScript.

## Conventions
- All scenes in `scenes/`, scripts in `scripts/`
- Use typed GDScript: always annotate variables and function signatures
- Prefer signals over direct method calls between nodes
- Use @export for inspector-visible properties, not @onready for configuration
- @onready is only for caching node references

## Godot-specific rules
- Node references: use @onready var, not get_node() in _ready()
- Signals: define with `signal name(params)`, connect in _ready()
- Scene changes: use get_tree().change_scene_to_file(), not change_scene()
- Input: use Input.is_action_pressed(), not raw key codes
- Every node added programmatically needs .owner set or it won't serialize to .tscn

## Don't
- Don't use Python builtins that don't exist in GDScript (list comprehensions, with statements)
- Don't call _ready() or _process() directly — they're lifecycle callbacks
- Don't use Thread without checking if the target function is safe for threading

3. Add Godot docs as context

Claude doesn't have Godot 4's full API memorized. You can help by adding reference docs to your project:

# Download the GDScript class reference
# Place in docs/ directory
mkdir -p docs
# Add relevant class docs you're using

Then reference them in your CLAUDE.md:

## References
- Godot class docs are in `docs/` — read them before using unfamiliar classes

Setting up the LSP

Claude Code can use LSP (Language Server Protocol) for better code intelligence. Godot's built-in LSP gives Claude access to autocompletion data, type information, and error diagnostics.

Enable Godot's LSP

  1. Open your Godot project in the Godot editor
  2. Go to Editor → Editor Settings → Network → Language Server
  3. Enable the language server (it runs on port 6005 by default)

With the LSP running, Claude Code gets real-time feedback about GDScript errors, which dramatically reduces hallucinated code.

Practical workflows

Building a new scene

"Create a player character scene with a CharacterBody2D root. It should have 8-directional movement with acceleration and friction. Use the input map actions 'move_left', 'move_right', 'move_up', 'move_down'."

Claude will generate the .tscn and .gd files. Review the scene structure — Claude sometimes nests nodes incorrectly.

Debugging game logic

"The enemy AI stops moving after the player dies. Read scripts/enemy_ai.gd and scripts/game_manager.gd to find why."

Claude excels at reading GDScript and tracing logic flow. It can usually spot the issue (often a signal that disconnects or a flag that never resets).

Shader work

Claude is decent at Godot shaders (they use a GLSL-like syntax). Be specific about what you want:

"Write a fragment shader for a dissolve effect that takes a noise texture and a threshold parameter. Apply it to the player sprite when they die."

Common pitfalls

Build-time vs runtime confusion

Claude sometimes writes code that uses @onready or calls get_tree() in contexts where the scene tree doesn't exist yet (like in @tool scripts or scene generation scripts). If you're generating scenes programmatically, tell Claude explicitly:

"This script runs in the editor as a @tool script. There is no scene tree at this point."

Signal syntax changes

Godot 4 changed signal syntax significantly from Godot 3. Claude occasionally mixes them up:

# Godot 3 (wrong)
connect("signal_name", self, "_on_signal")

# Godot 4 (correct)
signal_name.connect(_on_signal)

Add this to your CLAUDE.md if you see it happening.

Resource paths

Claude sometimes guesses resource paths wrong. Be explicit about your project structure and use res:// paths in your instructions.

Tips

Run the game frequently. Claude can't see your game running. After each change, test it yourself and report what you see. "The player moves but doesn't animate" gives Claude the feedback loop it needs.

Use plan mode for game design. Before implementing a system (inventory, dialogue, combat), use plan mode to have Claude design the node structure and data flow first.

Keep scripts small. GDScript files over 200 lines are hard for Claude to reason about. Split into components — separate movement, animation, and combat into different scripts attached to child nodes.