Claude Code and Godot: build a browser game

By GamesByAI · Published · Updated · 33 sources

On this page

Godot is a pretty good fit for coding agents, because a project is just files and terminal commands they can work with, with an MCP server as an option. Start with GDScript, build a tiny game in short loops and make the browser export an early milestone, since a game that runs in the editor still has to work in a browser.

We’ll build a whole game, just a tiny one. It’s a single-screen platformer where you move, jump, collect three coins, reach an exit and restart. For installing and signing in to the agent, use the Claude Code guide or the Codex guide.

The general process is in the AI game development guide, choosing an engine is in the engine comparison, and the MCP guide’s engine section compares the Godot connections. Here, you’ll pick just one connection and actually take a project all the way to its web build.

1. Create an empty Godot project for the browser

Use Godot 4.7.2, which was the stable download on godotengine.org when we checked. Pick the standard build and GDScript for this one. That’s because the current web export docs say “Projects written in C# using Godot 4 currently cannot be exported to the web.” The feature reference also points C# web users to Godot 3.

Create a new project in an empty folder, as in Godot’s setup tutorial, and choose Compatibility as the renderer. Godot’s renderer overview lists it as the only one of the three that supports Web, so choosing it keeps the editor and the web build on the same renderer. Name the folder coin-hop and open your agent’s terminal in it.

The commands below assume the editor executable is on your PATH as godot. If it isn’t, use your binary’s path instead, and on macOS the executable is inside Godot.app/Contents/MacOS/. The command-line tutorial documents those paths and --version, so check that it works before you go on.

godot --version

2. Connect Godot MCP, or keep the terminal loop

We’ll use Coding-Solo/godot-mcp here. It’s MIT-licensed, and its README requires Godot, Node.js 18 or newer, npm and an MCP-capable client. The README doesn’t give a general minimum Godot release, though. Only its UID tools specifically require Godot 4.4 or newer, so don’t read that as a promise about every tool.

Pin 0.1.1 in the commands below, and that part really matters. Versions before it passed an unsanitized project path to a shell, and the GitHub advisory says 0.1.1 fixes this by using execFile() instead of exec(). Check later releases before you change the pin.

Replace /absolute/path/to/godot with your actual executable, since GODOT_PATH overrides the server’s automatic detection (README). Then pick the command for your client.

In Claude Code, the server name has to go before --env. It’s a little fiddly, because --env takes several KEY=value pairs and rejects a name that follows it directly (Claude Code MCP docs). In both clients, the launch command comes after -- (Codex MCP docs).

# Claude Code, from the game folder
claude mcp add --scope project godot --env GODOT_PATH="/absolute/path/to/godot" -- npx -y @coding-solo/godot-mcp@0.1.1

# Codex alternative
codex mcp add godot --env GODOT_PATH="/absolute/path/to/godot" -- npx -y @coding-solo/godot-mcp@0.1.1

In Claude Code, --scope project writes the server to .mcp.json in the game folder, and the next interactive session asks you to approve it. claude mcp get godot shows whether it connects (Claude Code MCP docs). Restart your client, then send something like this.

Use get_godot_version and get_project_info on this project’s absolute path. Report the executable version and project summary. Then read project.godot and scene files through normal file access to identify the main scene and scene paths. Do not change files yet. If the connection fails, show the error before trying another path.

The server’s tool list has a bunch of them, including create_scene, add_node, save_scene, launch_editor, run_project, get_debug_output and stop_project. The usual cycle is pretty simple. You call run_project, then get_debug_output, then stop_project before you launch a new run, and launch_editor opens the editor when you want to look at the scene.

MCP helps, but you can totally skip it. The agent can edit .gd scripts and .tscn text scenes, then run Godot and read terminal errors, because Godot documents human-readable scene and resource formats in its feature list and automation in the CLI reference. That’s enough for the import, parse, run and export commands below, so think of MCP as a nice extra, not the build system.

3. Copy project rules for the agent

Save these rules as AGENTS.md next to project.godot. Codex reads it as project guidance (Codex docs), and Claude Code 2.1.277 and later read it too when the project has no CLAUDE.md. If you keep a CLAUDE.md, put @AGENTS.md at the top of it, so both agents follow one file and you never have to keep two copies in sync (Claude Code docs).

These are conventions for this project, not rules Godot imposes. Its typing guide supports typed variables, parameters and return values, and its signals tutorial shows event connections. The directory layout is just our choice, not an engine requirement (project organization).

# Coin Hop project rules

- Engine: Godot 4.7.2 standard; Compatibility renderer; GDScript 2.0.
- Type variables, parameters and return values. Use Godot 4 APIs.
  No Godot 3 syntax, C#, native extensions or Thread/WorkerThreadPool work.
- Scenes: scenes/main.tscn, scenes/player.tscn, scenes/coin.tscn.
  Scripts: scripts/. Source assets: assets/. Rule tests: test/unit/.
- Use snake_case files/functions and PascalCase node names.
  Player root: CharacterBody2D. Coin root: Area2D. UI: CanvasLayer.
  Keep documented node paths stable; report any scene-tree change.
- Use signals for pickup, death, completion and UI updates.
  Poll movement input in _physics_process; do not poll gameplay events.
  Each coin awards once. A run completes once. Restart resets all state.
- Configure move_left, move_right, jump and restart in Input Map.
  Keyboard and touch use those same actions. No hover-only actions.
- Never hand-edit .godot/ or *.import files.
  Change source assets/import settings and let Godot reimport them.
  Keep generated *.import metadata in version control; ignore .godot/.
- Use res:// paths for project resources. Keep exports in build/web/;
  place an empty build/.gdignore so builds are not imported/exported.
- After changes, run from the project root:
  godot --headless --path . --import
  godot --headless --path . --check-only --script res://scripts/player.gd
  godot --headless --path . --quit-after 180
  Repeat the parse command for each changed script, with its real path.
- Once GUT is installed, run the rule tests after the import:
  godot --headless --path . --debug --script addons/gut/gut_cmdln.gd -gdir=res://test/unit -gexit
- Then run visibly: godot --path .
  Check start, movement, jump, pickup, death, win and restart.
  Inspect a screenshot and read errors; a headless pass is not visual QA.
- Web preset: Thread Support off, Extensions Support off, PWA off.
  Export and play in the browser early, including a plain iframe.
- Finish each task with changed files, actual check results and limits.

Godot creates the *.import metadata and imported resources itself, and the import docs say to keep the metadata in version control and leave .godot/ out. So “don’t hand-edit” doesn’t mean “delete”, and the .import files belong in your commits even though you never edit them by hand. A .gdignore excludes a folder from imports and export (import docs, organization), and res:// starts at the project root (paths).

4. Build one playable slice per prompt

Start with movement and a floor, then add pickups and the ending, and stick to simple shapes until the loop works. The prompts below describe the game we want, but that’s no promise an agent will finish it in one turn.

The first prompt covers movement.

Create scenes/main.tscn and scenes/player.tscn under the project rules. Main has a floor, a Player instance and a fixed camera. Player is a CharacterBody2D with a visible shape and collision. Configure arrows and A/D for movement, Space for jump. Set main.tscn as the main scene. Done when I can run, jump, land and fall to a reset point.

Run import, parse and headless checks, then open the game visibly. Report errors and the scene tree.

Use this scene contract for the next slice. The exact shapes and positions can change, of course.

Main (Node2D)
  World (Node2D)
    Ground (StaticBody2D with a CollisionShape2D)
    Player (instance of player.tscn)
    Coins (Node2D holding coin.tscn instances)
    Exit (Area2D with a CollisionShape2D)
  Camera2D
  HUD (CanvasLayer)
    Counter (Label)
    Result (Control, hidden until completion)
    TouchControls (Node2D)

The second prompt makes one complete run.

Add three coin instances. Each emits collected once and disables its collision before it can award again. Main owns the run state and connects signals once. Update the counter from a signal, unlock Exit after all coins, and show a result panel when the player enters the unlocked exit. Restart recreates the run, coins and counter.

Done when entering Exit early does nothing, a coin cannot award twice, and repeated restarts never multiply signal connections. Run the checks, then play those cases.

Run, read the error, fix the cause

After each prompt, run the checks in order. The flags all come from Godot’s CLI reference.

godot --headless --path . --import
godot --headless --path . --check-only --script res://scripts/player.gd
godot --headless --path . --quit-after 180
godot --path .

--import waits for imports and exits. --check-only parses the script you give it, but it doesn’t play the scene or check every file. And --quit-after 180 ends after 180 iterations, not 180 seconds.

Read the output as well as the exit status, because a quiet startup doesn’t really tell you anything about an exit trigger nobody touched.

Give the agent the actual error, file and line, like this.

The parser reports “Cannot infer the type” in player.gd. Read that line and the value it receives. Add the correct explicit type, rerun the same parse command, then the startup check. Preserve the movement behavior and show the result.

For visuals, take a screenshot from the visible run and check the player, floor and HUD at game size. With MCP, pair run_project with get_debug_output. Its run and debug tools are documented, but the README doesn’t list a screenshot tool (README), so a person or a separate browser tool has to capture the exported game. Playtesting with AI covers that browser loop.

5. Add a test for the rule that ends a run

For tests, use GUT 9.7.1. The README’s version table maps it to Godot 4.7.x, and it’s MIT-licensed.

Download the 9.7.1 release, copy addons/gut into the game’s addons/ directory and enable the plugin. Oddly, GitHub marks 9.6.1 for Godot 4.6 as Latest, so pick GUT by engine version rather than by that label.

Ask the agent to pull the run rules out into scripts/run_state.gd, extending RefCounted. A new run has coins: int = 0 and finished: bool = false. Its collect_coin() -> void stops at three, and try_finish() -> bool succeeds once, only after three coins.

Keep the duplicate-pickup protection in the coin scene too. Then save this rule test as test/unit/test_run_state.gd.

extends GutTest

const RunState = preload("res://scripts/run_state.gd")

func test_exit_requires_coins_and_finishes_once() -> void:
    var state: RunState = RunState.new()
    assert_false(state.try_finish())
    state.collect_coin()
    state.collect_coin()
    assert_false(state.try_finish())
    state.collect_coin()
    assert_true(state.try_finish())
    assert_true(state.finished)
    assert_false(state.try_finish())
    state.collect_coin()
    assert_eq(state.coins, 3)

func test_new_run_is_empty() -> void:
    var state: RunState = RunState.new()
    assert_eq(state.coins, 0)
    assert_false(state.finished)

Run it after the import. The --headless, --path, --debug and --script flags belong to Godot, while the -g options belong to GUT (Godot CLI, GUT command line).

godot --headless --path . --debug --script addons/gut/gut_cmdln.gd -gtest=res://test/unit/test_run_state.gd -gexit

GUT returns exit code 0 when all tests pass and 1 when any test fails, and pending tests don’t change the result (GUT command line). Run --import first, though.

If GUT’s classes haven’t been imported yet, gut_cmdln.gd prints an error and exits with code 0 before running any tests (9.7.1 source), so a skipped import can look like a pass. Read the output as well as the exit code.

That tests the rule itself. Scene connections and collision behavior need their own check, so walk into the same coin twice, enter the exit early and restart in the visible game too.

6. Export a Web preset before adding polish

Install the 4.7.2 export templates through Editor > Manage Export Templates, then add a Web preset in Project > Export and name it Web. Templates and preset setup are both documented in Exporting projects. Keep the preset in export_presets.cfg so later exports use the same settings.

For this GDScript game, you’ll want to set these four explicitly. The Web platform reference documents what each option changes.

Option Set it to Reason for this path
Thread Support Off No thread support or SharedArrayBuffer isolation requirement
Extensions Support Off This project uses no GDExtension
Progressive Web App > Enable Off Start with ordinary hosted files and an iframe
Canvas Resize Policy Adaptive Fit the canvas to its web page

In export_presets.cfg, the first one shows up as variant/thread_support=false, which basically means an agent can check it there.

Create build/web/ and the empty build/.gdignore before exporting, then run this from the game root.

godot --headless --path . --export-debug "Web" build/web/index.html
# After browser checks pass:
godot --headless --path . --export-release "Web" build/web/index.html

The preset name has to match exactly, and the output directory has to exist already (CLI). Export as index.html from the start and keep the generated companion filenames together (web docs).

To test it, serve that folder through a local HTTP server. With the Node and npm prerequisites from earlier, Vercel’s serve does that in one command, and npm’s --yes skips the install prompt (npx docs).

npx --yes serve build/web

Open the local URL the server prints, play the debug export and check the browser console, then do the same with the release export.

What enabling threads changes

Turning Thread Support on sounds nice, since it allows multithreading and lower-latency Stream audio (web docs). The option reference says it requires cross-origin isolation, and it warns that disabling threads can expose performance and audio issues. So measure your game before you switch it on, and decide where it’ll be hosted at the same time as you make the performance call.

Godot introduced single-threaded Web export in 4.3, and its web-export report explains the distribution problem behind the change. The current web docs even call single-threaded export the preferred default.

A threaded build uses SharedArrayBuffer, so Godot requires a secure context and these response headers (serving docs).

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The server has to send them as real HTTP response headers, and an HTML meta tag doesn’t count. MDN explains that cross-origin isolation also depends on permissions. The cross-origin-isolated permissions policy defaults to self, so a frame from another origin needs the embedding page to grant it.

The embedding page has to be isolated as well, which is why itch.io’s option changes its own game pages too (more on that in the next section).

Godot documents a PWA service-worker workaround for hosts where you can’t configure headers (web docs). Treat that as a separate delivery route to test, though, because it doesn’t show that a threaded build will work inside any third-party iframe.

7. Upload to itch.io or embed on your own site

For itch.io, zip the contents of build/web/ with index.html at the archive root. Pick HTML Game as the kind of game, upload the zip and set the viewport size under Embed options. itch.io requires relative asset paths and filenames with the right case (HTML5 upload docs), and for the single-threaded build, the SharedArrayBuffer support setting stays off.

For a threaded build, itch.io’s own developer update documents Embed Options > Frame Options > SharedArrayBuffer support. It adds isolation headers to the game’s files, its itch.io page and Game Embed pages, and it moves the game to another CDN domain. That’s kind of a big deal on a game people are already playing, because saves kept in local storage from earlier plays get left behind.

itch.io supports play on the project page and through its Game Embed feature, not raw CDN URLs. The setting prepares itch.io’s own environment, but it can’t configure a parent page on a different site.

If you host the build on your own HTTPS origin, a small wrapper like this one does the job (swap in your own URL). It assumes the host allows framing and serves all the generated files, and the iframe reference documents the fullscreen permission. With Thread Support and Extensions Support off, the game doesn’t need cross-origin isolation, only HTTPS (web docs, export option).

<iframe
  title="Coin Hop"
  src="https://play.example.com/coin-hop/index.html"
  width="960"
  height="540"
  style="width:100%;aspect-ratio:16/9;height:auto;border:0"
  allow="autoplay; fullscreen"
  allowfullscreen>
</iframe>

Test the actual wrapper on the actual host. It needs visible keyboard focus on click, a Start button, touch controls and a way to restart, and you’ll want to check resizing, audio after Start and fullscreen after a button press.

Single-threaded export gets rid of the isolation requirement, but it can’t fix a missing file or a host that blocks iframes. And if you add saves later, Godot’s docs note that user:// data in an iframe only persists when the player allows third-party cookies (web docs).

Keep download size visible

Measure what your release build actually sends over the network before you add art. Record the .wasm, .pck and asset requests with the cache disabled, then test a repeat visit. When you talk about loading time, go by the transfer size and startup time on the device and connection you tested, not by the zip’s size.

The export manual recommends server compression for .wasm and .pck, and no wonder, since it says gzip shrinks the .wasm to about a quarter. It also asks for .wasm to be served as application/wasm (serving docs).

itch.io’s CDN gzips uploaded .wasm and .pck files on its own (HTML5 upload docs), but on your own host you’ll need to switch compression on. And keep source and press-kit assets out of the export with .gdignore (import docs).

8. Check mobile input, audio and fullscreen

Don’t call the game mobile-ready until it has touch actions. Godot’s TouchScreenButton supports simultaneous touches and has an action property, so you can map left, right and jump to the same Input Map actions the keyboard uses. Test holding a direction while jumping, letting go outside a button and rotating the device, and see the mobile-game guide for that test session.

Godot documents a few browser constraints, so build your checks around its web export limitations.

  • Audio. Require a click, tap or key press at Start, because some browsers restrict autoplay. The default web Sample playback leaves out audio effects and procedural generation, while Stream brings back the engine’s audio features with some latency tradeoffs.
  • Fullscreen and pointer lock. Godot calls pointer lock mouse capture. Request both inside a pressed input-event callback like _input or _unhandled_input, because polling the Input singleton isn’t enough.
  • Mobile. The web export can run on phones, but native Android and iOS exports perform better. Test on a real phone, since Compatibility is a renderer choice, not a speed guarantee.
  • Tab changes. The browser pauses processing in an inactive tab, so check that the game resumes and what state held inputs are in when the player comes back.

Keep the first build’s sound to simple samples, and make fullscreen optional, so a player can finish and restart while the game stays inside its frame.

A tower-defense game records its Godot build

In the Godot games we list, you can see the engine and, where the creator named them, the AI tools. None of them says which MCP server, export settings or test framework it used, though.

  • StarJam does something a little unusual and mixes tower defense with clicker income. Its entry, based on the creator’s Vibe Jam 2026 submission, says it was built in Godot with Claude Code.

  • ironclash is an online multiplayer battle game that runs in desktop and phone browsers, and according to its Vibe Jam 2026 submission, it’s another one built in Godot with Claude Code.

  • The entry for Pro Skater: The Warehouse cites the repository README and records Claude Opus 5.5. It says the game runs in Godot with GDScript, as a web export and a Windows build. The creator says Python scripts in Blender generate every 3D asset, and even the sound is synthesized in code.

  • Almost Surgery is a single-player browser game about performing operations, and its submission-sourced entry records Godot and Codex.

  • Pocket Salvage has you sorting scrap with a crane in a night-time junkyard, and it turns out two AIs worked on it. Its entry records Godot and cites the project README for Claude (the chat app) and Codex.

  • The entry for Ikuta ’73 cites the itch.io game page and the rules of the fourth AI Browser Game Jam. The creator credits Claude Code with the code, sound effects, modeling and level QA, and Grok Build with the title-screen and lens-flare code.

You can find more on the Godot hub, or look through the Claude Code games, Codex games and platformers. Once the loop works and you want character art, AI sprite animation picks up from there.

Complete the browser build

You’re basically done when a fresh browser can start, move, jump, collect, win and restart in the release export, both directly and in the iframe you’re planning to use. Do it again with touch controls on a phone, and check the console and any missing network requests. Then write down the engine, export settings, test results and remaining limits next to the build.

After that, submit the game with its playable URL and an accurate account of what the AI made. We list playable games under our editorial policy, but just so it’s clear, listing it here doesn’t host the Godot export for you.

Games to look at

Questions

Can Claude Code make Godot games?

Yes. It edits GDScript and Godot's text scene files, and runs the Godot binary from the terminal to import, check scripts, run and export. StarJam and ironclash are Godot games whose creators credit Claude Code.

Do I need Godot MCP to use Claude Code or Codex?

No. An agent can edit GDScript and text scene files, run Godot from the terminal and read its output, and MCP just adds named tools like run_project and get_debug_output. Keep the CLI checks even when you connect it.

Can Godot 4 C# games export to a browser?

Not right now. Godot's current web export docs say projects written in C# using Godot 4 cannot be exported to the web, and they point C# web users to Godot 3 instead, which is why this guide uses GDScript.

Should I enable Thread Support for an itch.io game?

Leave it off for a small game like this one in an ordinary iframe. Turning it on requires SharedArrayBuffer and cross-origin isolation, and while itch.io has an opt-in SharedArrayBuffer setting, an external embedding page also has to meet the browser's isolation and permissions requirements.

Does a clean headless run prove my Godot game works?

No. It catches startup and runtime errors on the path it executes, but doesn't check the rendered scene or play the controls. Run rule tests, inspect the visible game and play the exported browser build, including restart and touch input.