# Developing Godot Games with AI

> Source: https://aiwiki.ai/wiki/developing_godot_games_with_ai
> Updated: 2026-10-30
> Fact-checked: 2026-10-30
> Categories: AI in Gaming, Developer Tools, Generative AI, Software Development
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) - attribute to "AI Wiki (aiwiki.ai)"
> Cite as: AI Wiki. "Developing Godot Games with AI." aiwiki.ai, 30 Oct 2026. https://aiwiki.ai/wiki/developing_godot_games_with_ai
> From AI Wiki (https://aiwiki.ai), the free encyclopedia of artificial intelligence. Reuse freely with attribution.

**Developing Godot games with AI** means using an assistant to help design, edit and check a Godot project while retaining the engine's scenes, scripts and resources as the working game. A useful starting point is Godot's official *Dodge the Creeps!* tutorial, which builds a complete small 2D game and assumes some programming experience.[1] An assistant can help work through that project, but its changes still need to run in Godot.

<figure class="w-56">
<div class="bg-slate-50 rounded-lg p-3"><a href="https://godotengine.org/"><img src="/images/game-guide-godot-logo-3971f2540498.svg" alt="Logo of the game engine used for the scene and scripting workflow" width="1024" height="414" /></a></div>
<figcaption>Official engine logo. Andrea Calabro, 2017. <a href="https://godotengine.org/press/">Original</a>, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>. Unmodified.</figcaption>
</figure>

This practical guide focuses on Godot 4 and GDScript, with notes on C#. As of 30 October 2026 the current stable release is Godot 4.7.2 (18 August 2026); Godot 4.8 is in beta, with 4.8-beta2 published on 29 October 2026.[25] Choose the documentation branch matching your installed editor before using examples. Godot's release policy distinguishes major, minor and patch updates: patch releases are described as backwards compatible, while for minor releases it says "Minor compatibility breakage in very specific areas may happen".[2] The steps and acceptance checks below are recommended workflows, not a promise about an assistant's success rate.

This page is part of [Developing Games with AI](https://aiwiki.ai/wiki/developing_games_with_ai). For a JavaScript framework rather than an engine export, see [Developing Browser Games with AI](https://aiwiki.ai/wiki/developing_browser_games_with_ai). Asset generation and release checks have their own guides, linked where they apply.

## Start with an inspectable project

Complete enough of the official 2D tutorial to understand its player, enemies, main scene and HUD. Run that baseline before asking an agent to alter it. Avoid combining the tutorial, an engine upgrade and an unfamiliar plugin in the same first task.[1]

Record the exact engine version, renderer, scripting language, main scene, intended platforms and run command in the project instructions. Give the assistant the matching API documentation and ask it to report incompatible assumptions before editing. Treat a Godot 3 example as a migration task when working in Godot 4, not as interchangeable code.[2][31]

| Baseline record | Example of what to write down |
| --- | --- |
| Engine | The exact version reported by `godot --version`, for example `4.7.2.stable.official` followed by a short commit hash |
| Build | Standard build (GDScript) or the .NET build (C#) |
| Entry point | The main scene configured in the project |
| Input | Existing action names and their keyboard or controller bindings |
| Allowed changes | Named scenes, scripts and resources for this task |
| Protected changes | Engine upgrades, new addons, renderer changes and signing settings require review |
| Evidence | Which checks ran, their output and which play checks remain manual |

The command-line documentation recommends putting the editor binary on the `PATH` as `godot`. On macOS the binary sits inside the application bundle (`Godot.app/Contents/MacOS/Godot`), and the documentation gives `brew install godot` (Homebrew) and `scoop bucket add extras` followed by `scoop install godot` (Scoop, Windows) as ways to install it on the path; the C# editor installs as `godot-mono`.[16]

### Set up version control before the first agent edit

Save a version-control checkpoint before an agent touches the project. Godot can generate Git metadata from the project manager or from **Project > Version Control > Generate Version Control Metadata**, which creates `.gitignore` and `.gitattributes` files.[3] The documented Godot 4.1-and-later exclusions differ from those for Godot 3.x and 4.0, so do not reuse an older ignore list blindly.[3]

| File or folder | Commit it? | Source |
| --- | --- | --- |
| `.godot/` | No. It stores project cache data and is regenerated; the generated metadata ignores it | [3][20] |
| `*.translation` | No. Binary translations generated from CSV files | [3] |
| `<asset>.import` next to each imported asset | Yes. The import documentation says these contain "important metadata" | [20] |
| `*.uid` next to scripts and shaders (Godot 4.4 and later) | Yes. Godot's announcement says `*.uid` "should not be added to `.gitignore`" | [27] |
| `export_presets.cfg` | Yes. Godot says it "can be safely committed" | [21] |
| `.godot/export_credentials.cfg` | No. It holds confidential export options such as passwords and encryption keys | [21] |

Large binary assets can go through Git LFS; Godot's version-control page includes an example `.gitattributes` for it.[3] Inspect the diff before committing an agent's changes, and include `.uid` and `.import` files that belong to new or moved assets.

## Give the assistant the scene structure

A Godot game is organized as scenes made from node trees. Saved scenes can be instantiated in other scenes, and the project has a main scene that loads first; the editor stores its path in `project.godot`.[4] A script alone may therefore omit the relationships needed to understand a bug.

For a player task, supply the relevant tree, attached scripts and Inspector values. Include the exact names, not a description such as "the collision object somewhere under the player." Identify whether the request changes a reusable scene or only one instance of it.

An illustrative organization for a small collection game is:

```text
main.tscn
  Main
    Player (instance of player.tscn)
    Pickups
    HUD

player.tscn
  Player (CharacterBody2D)
    Visual (Sprite2D)
    CollisionShape2D
```

These are proposed project names, not nodes automatically created by Godot. Ask the assistant to inspect the actual project before adopting them. Godot's scene-organization guidance explains how hard references can break when a branch becomes a reusable scene, and recommends designing scenes "to have no dependencies" where possible, with a parent supplying what a child needs.[5]

Node paths are a common failure point when an agent renames or moves nodes. `get_node()` returns `null` and generates an error when its path does not point to a valid node.[33] A node marked with `unique_name_in_owner` can instead be reached with the `%Name` syntax from any node sharing the same owner, which survives some reorganizations within a scene.[33] Ask the agent to search scripts and scenes for the old path after any rename.

For interactions, specify who owns the state. A pickup can report collection; the gameplay controller can update the score; the HUD can display it. Godot signals allow objects to react to events without requiring direct references between every participant.[6] In an agent request, state which signal already exists, who connects it and whether the editor or a script creates that connection. A signal can be connected only once to the same callable: a second `connect()` returns `ERR_INVALID_PARAMETER` and generates an error unless the reference-counted flag is used, and `is_connected()` checks first.[32] An "already connected" error therefore usually means both the editor and a script are making the same connection.

### Write Godot-specific project instructions

The hub guide gives a general instructions template for `CLAUDE.md` or `AGENTS.md`. For a Godot project, add the engine facts and the exact commands the agent is allowed to run. The following block is illustrative; replace the version, paths and preset name with your own. Every Godot flag in it appears in Godot's command-line reference; the GUT options (`-gdir`, `-gexit`) are covered below.[16][36]

```text
## Engine
- Godot 4.7.2 standard build, GDScript only. Do not use Godot 3 APIs
  (KinematicBody2D, yield, the export keyword). Use static types.
- Main scene: res://main.tscn. Input actions: move_left, move_right,
  move_up, move_down, restart. Do not rename them.

## Commands (run from the folder containing project.godot)
- Import after adding or moving files: godot --headless --path . --import
- Parse one script:  godot --headless --path . --check-only --script <file.gd>
- Unit tests (GUT):  godot --headless -s --path . addons/gut/gut_cmdln.gd -gdir=res://test/unit -gexit
- Export (Linux):    godot --headless --path . --export-release "Linux" build/game.x86_64

## Rules
- Prefer editing .gd files. Edit .tscn/.tres text only for the task's named
  scenes; never invent uid:// values. Keep each .uid file with its script.
- Read the full output of every command. A zero exit status does not prove
  there were no script errors.
- Do not install addons, change project.godot renderer settings or edit
  export_presets.cfg without asking.
```

## Implement one mechanic with explicit checks

Start with movement or one pickup, then add a failure condition and restart. Each step should have a visible outcome and a narrow set of files. The following is an illustrative prompt for an existing project:

```text
Inspect project.godot, main.tscn and player.tscn before editing.
Use the installed Godot 4 version and the existing input actions.

Task: add a collectible that increases the run score once.
The gameplay controller owns the score; the HUD only displays it.
Reuse the existing player scene and preserve its node names.

Checks:
- Touching one collectible increases the score exactly once.
- Remaining in its collision area does not award repeated points.
- Two separate collectibles award two points.
- Restart clears the score and restores the intended collectible state.
- Existing movement and failure behavior still work.

Show the diff and the evidence for each check.
Do not add an addon or change the engine version.
```

The expected numbers here define this example's rules. They are not Godot defaults. If the real game uses a different scoring system, replace them before implementation.

For a bug, give evidence rather than a symptom. An illustrative repair prompt:

```text
Bug: after restart, the score label shows the old score until the first pickup.
Reproduction: start main.tscn, collect 2 pickups, die, press restart.
Output: no errors in the Debugger; the label shows 2, then 1 after a pickup.
Scope: scripts/game_controller.gd and scenes/hud.tscn only.
First explain the cause using the code. Then make the smallest fix, add a
GUT test that fails before the fix and passes after it, and run the tests.
```

### A small Godot 4 movement example

For a top-down example, create a `CharacterBody2D` with a suitable collision shape, set its Motion Mode to Floating, and attach this script. Define `move_left`, `move_right`, `move_up` and `move_down` in **Project > Project Settings > Input Map**, with the intended keys or controller events. `Input.get_vector()` combines four actions into a direction whose length is limited to 1; `CharacterBody2D` provides the `velocity` property and `move_and_slide()`.[7][8]

```gdscript
extends CharacterBody2D

@export var speed: float = 180.0

func _physics_process(_delta: float) -> void:
    velocity = Input.get_vector(
        "move_left", "move_right", "move_up", "move_down"
    ) * speed
    move_and_slide()
```

The speed is an example tuning value. This script supplies movement, not a camera, level, sprite, scoring system or complete game. Check it before relying on it: parse it with `--check-only` and run a test such as the GUT example below, which asserts a diagonal speed of 180 and that the body stops after the input is released. Such checks do not establish wall collision, controller support, appearance or behavior on an exported platform.

If the actions are missing from the Input Map, Godot 4.7.2 reports an error such as `The InputMap action "move_right" doesn't exist. Did you mean "ui_right"?` on every physics frame rather than refusing to start, so read the output even when the game window opens.[53]

Test input in the actual game as well. Godot's InputMap separates actions from particular keys. Its input-event guidance also explains that gameplay event handlers can use `_unhandled_input()` so GUI controls have an opportunity to consume events first.[9] Polling global input state is a different mechanism: `Input` methods "reflect the global input state" and are not affected by a GUI accepting an event.[7] Define what movement should do while a menu or pause screen is open, rather than assuming a menu will suppress it.

## Keep agent-written GDScript on Godot 4

Models have seen large amounts of Godot 3 code, and Godot 3 and 4 differ substantially. Godot's migration guide lists renamed classes (for example `KinematicBody2D` became `CharacterBody2D` and `KinematicBody` became `CharacterBody3D`), a changed signal-connection syntax, changed setter and getter syntax, and the `tool` keyword becoming the `@tool` annotation.[31] Tell the agent the engine version and reject Godot 3 idioms in review.

| Godot 3 idiom an agent may produce | Godot 4 form | What Godot 4.7.2 reports |
| --- | --- | --- |
| `extends KinematicBody2D` | `extends CharacterBody2D`[31] | `Could not find base class "KinematicBody2D".` |
| `yield(timer, "timeout")` | `await timer.timeout` | `"yield" was removed in Godot 4. Use "await" instead.` |
| `connect("body_entered", self, "_on_body_entered")` | `body_entered.connect(_on_body_entered)`; Godot recommends the Signal-based syntax so signal-name errors are not found only at runtime[31] | `Invalid argument for "connect()" function: argument 2 should be "Callable"` |
| `tool` at the top of a script | `@tool`[31] | `The "tool" keyword was removed in Godot 4. Use the "@tool" annotation instead.` |
| `export var speed = 10` | `@export var speed: float = 10.0` | `The "export" keyword was removed in Godot 4. Use an export annotation ("@export", "@export_range", etc.) instead.` |

The messages in the third column are the GDScript parser's and analyzer's error strings in the Godot 4.7.2 source.[53] For a whole Godot 3 project, Godot provides `--validate-conversion-3to4` to list planned renames and `--convert-3to4` to apply them; the migration guide warns to back the project up first because the tool makes no backup, and says scripts will likely still contain errors afterwards.[31][16]

### Use static typing and warnings as a check

Static typing lets GDScript "detect more errors without even running the code".[29] Ask the agent to type variables, parameters and return values, and make the project enforce it. The warning system is configured in the GDScript section of **Project Settings**, which is visible with **Advanced Settings** enabled (or by searching for "GDScript"). Each warning can be set to Ignore, Warn or Error, and the documentation notes that with warnings turned into errors "your game won't compile unless you fix all warnings".[28][30]

Useful settings for agent-written code are `debug/gdscript/warnings/untyped_declaration` (a variable or parameter without a static type, or a function without a return type), `unsafe_method_access` and `unsafe_property_access`; all three default to Ignore.[30] With `untyped_declaration` set to Error, an untyped variable is reported as a parse error such as `Variable "score" has no static type. (Warning treated as error.)`.[53] In `project.godot` the setting is stored as:

```ini
[debug]

gdscript/warnings/untyped_declaration=2
```

The value 2 corresponds to Error in that setting's Ignore, Warn, Error list. Prefer changing it in the Project Settings dialog; the generated `project.godot` itself notes that it is "best edited using the editor UI and not directly".[53] The static-typing guide also notes that `@onready var node: Type = $Node` reports a changed node type as soon as the scene loads, whereas `$Node as Type` silently becomes `null`.[29]

## Preserve scenes and resources when editing

Godot resources hold data used by nodes. They can be external files or built into a scene, and images, meshes and other resources are shared between scene instances.[10] If changing one enemy's material changes every enemy, inspect resource sharing before asking the assistant to rewrite the rendering code.

Have the agent explain changes to `.tscn` and `.tres` files as well as `.gd` scripts. Use Godot's resource APIs or editor tools for binary `.scn` and `.res` resources rather than treating them as text; `ResourceSaver` supports both text and binary formats and returns an error code.[11]

There is a separate trap when an editor script or bridge constructs a scene: being a child in memory does not by itself establish which nodes will be serialized. `PackedScene.pack()` saves the root and the nodes it owns. An incorrectly assigned `owner` can leave a generated child out of the saved scene.[12] After a tool-created change, save, close and reopen the scene, then run it again.

Keep paths and filename casing consistent. Godot's project-organization guidance recommends snake_case file names and lowercase characters because the exported PCK virtual filesystem is case-sensitive.[13] A path that happens to work on a case-insensitive development machine is insufficient evidence for a portable build.

### Editing .tscn files as text

Scene files are text, so an agent can edit them, but the format has rules that are easy to break. Godot documents five sections in order: the file descriptor, external resources, internal resources, nodes and connections.[26]

| Element | What the documentation specifies | Agent pitfall |
| --- | --- | --- |
| Descriptor | `[gd_scene format=3 uid="uid://..."]`; Godot 4 files use `format=3`. `load_steps` appears in scenes saved before Godot 4.6 and is now deprecated | Producing `format=2` (Godot 3) files |
| `[ext_resource]` | A path, type, `uid` and a file-local `id`, referenced as `ExtResource("id")` | Inventing a `uid://` value or reusing an `id` |
| `[sub_resource]` | Referenced as `SubResource("id")`; when internal resources link to each other, order matters in the file | Wrong ordering after inserting a resource |
| `[node]` | `name`, `type` and `parent`; the root has no `parent`; a direct child of the root uses `parent="."`; parent paths exclude the root's name. `unique_id` appears only in scenes saved with Godot 4.6 or later | Two roots, or parent paths that include the root name |
| Comments and defaults | `;` comments and properties equal to their default are discarded when the editor saves | Expecting notes or explicit defaults to survive |

All entries in this table come from the TSCN format documentation.[26] Since Godot 4.4, scripts and shaders also get a `.uid` file beside them (for example `player.gd.uid`), so a file moved outside the editor keeps its identity; Godot asks that the `.uid` file be moved or removed together with its script, and recommends re-saving dependent scenes after external moves to clear warnings.[27] When a scene's `uid` does not match any resource, Godot falls back to the text path: Godot 4.7.2 prints a warning of the form `ext_resource, invalid UID: uid://... - using text path instead: res://player.gd`.[53] Treat that warning as a defect to fix by re-saving in the editor, not as success, because the fallback can resolve to the wrong file if paths have been swapped.[27]

A safe pattern is to let the agent edit text for small, reviewable changes (a property value, a new child node), then open and save the scene in the editor so Godot normalizes it, and review the second diff.

## Add an engine bridge only when needed

A file-editing assistant can work without an [MCP](https://aiwiki.ai/wiki/model_context_protocol) server: the developer or the agent can run Godot's command line and read the logs. A bridge is useful when the agent needs documented engine operations, but its actual tool list determines what it can inspect or change. The hub guide's setup section compares bridges across engines.

### Coding-Solo Godot MCP

Coding-Solo's community Godot MCP (MIT license) describes itself as letting agents "launch the Godot editor, run projects, capture debug output, and control project execution". Its stated requirements are Godot, Node.js 18 or newer with npm, and an MCP-compatible client.[14] This is a third-party integration, not a Godot Engine feature. As of 30 October 2026 the repository listed no GitHub releases, and the latest version published to npm as `@coding-solo/godot-mcp` was 0.1.1 (3 February 2026).[14][47]

For [Claude Code](https://aiwiki.ai/wiki/claude_code), the README's setup is:[14]

```bash
claude mcp add godot -- npx @coding-solo/godot-mcp
```

If Godot is not detected automatically, pass its path (and optionally server-side debug logging):

```bash
claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx @coding-solo/godot-mcp
```

Restart Claude Code afterwards. Other clients use an `mcpServers` entry with `"command": "npx"` and `"args": ["@coding-solo/godot-mcp"]`, optionally with `GODOT_PATH` and `DEBUG` in `env`.[14] The tools named in its documented auto-approve list are:

| Tool | Purpose (from the README) |
| --- | --- |
| `launch_editor`, `run_project`, `stop_project` | Open the editor; run a project in debug mode; stop it |
| `get_debug_output` | Retrieve console output and errors |
| `get_godot_version`, `list_projects`, `get_project_info` | Version, project discovery and structure |
| `create_scene`, `add_node`, `load_sprite`, `save_scene` | Create scenes, add nodes with properties, load textures into `Sprite2D`, save (including variants) |
| `export_mesh_library` | Export a 3D scene as a `MeshLibrary` for `GridMap` |
| `get_uid`, `update_project_uids` | UID lookup and re-saving resources (Godot 4.4+) |

Simple operations call Godot's command line; scene operations run a bundled GDScript file, `godot_operations.gd`.[14] Before using it, ask for the detected engine version and project path, then a read-only project inspection followed by a controlled run, and verify the reported result against the real project. The list contains no screenshot or input tool, so do not infer visual checks, keyboard control or playtesting from it. Its troubleshooting notes say the project path must point to a directory containing `project.godot`.[14]

### Other Godot integrations

The Godot Asset Library lists many community MCP and assistant addons; a search for "MCP" on 30 October 2026 returned more than a dozen, all at the "community" support level.[50] Popularity is not a security review. The following are documented examples, not endorsements:

| Project | What its documentation says | Requirements and caveats |
| --- | --- | --- |
| Godot-MCP (Ivan Murzak, Apache-2.0) | C# editor addon exposing editor operations as AI tools, including viewport, camera and isolated-node screenshots returned as PNG; the Godot counterpart of the same author's Unity-MCP[48] | Godot 4.3+ .NET (mono) edition and .NET 8 SDK; connects through the hosted ai-game.dev backend by default, or a self-hosted server[48] |
| AI Assistant Hub (FlamxGames, MIT) | In-editor assistants for coding and scene editing, "designed for local LLMs first"; Ollama, llama.cpp, Google Gemini, OpenRouter, xAI and others[49] | Does not run models itself; needs a provider such as [Ollama](https://aiwiki.ai/wiki/ollama)[49] |
| Godogen (htdt, MIT) | Skills for Claude Code and Codex that generate a Godot (C# or GDScript), Bevy, Babylon.js or three.js game; says the agent "judges results from the running game (a live URL or a recorded clip), not from a clean compile"[51] | Godot 4 on `PATH` (the .NET build for C#), Python 3, system packages including ffmpeg; optional paid API keys for assets[51] |

Review downloaded addons and editor scripts before enabling them. In particular, Godot's `@tool` annotation executes a script in the editor. Its documentation warns that modifications made in the editor "are permanent, with no undo/redo possible" and that freeing nodes at the wrong time can crash the editor.[15] Use a disposable copy for a new automation tool and inspect what it saves.

## Check the project in layers

Use the installed executable's `--help` output and the matching command-line reference. In the examples below, `godot` means that executable on the shell's path; replace it with the correct quoted path on your machine. Run from the project directory containing `project.godot`. `--headless` enables the headless display driver and a dummy audio driver, and is "useful for servers and with `--script`".[16]

| Check | Example command | What it establishes |
| --- | --- | --- |
| Identify the binary | `godot --version` | Which editor executable is being used |
| Import resources | `godot --headless --path . --import` | The editor completes its import pass and quits; inspect errors |
| Parse one script | `godot --headless --path . --check-only --script player.gd` | Parsing of that script ("only parse for errors and quit"), not gameplay correctness |
| Run a custom check | `godot --headless --path . --quit-after 600 --script checks/check_movement.gd` | Only the assertions implemented by that script |
| Run unit tests | GUT or gdUnit4 commands below | The behaviors the tests cover |
| Run a scene with collision shapes | `godot --path . --debug-collisions main.tscn` | Visual confirmation of hitboxes |

`--import` starts the editor, waits for resources to import and then quits; `--quit-after` quits after a given number of iterations, which bounds a script that never calls `quit()`.[16] The custom-check row requires a script that actually exists, inherits from `SceneTree` or `MainLoop`, and controls its own completion; it is not a built-in Godot test suite.[16] `SceneTree.quit()` accepts an exit code, and by convention 0 means success.[34] An illustrative check script, saved as `checks/check_movement.gd`:

```gdscript
extends SceneTree

func _initialize() -> void:
    for action in ["move_left", "move_right", "move_up", "move_down"]:
        if not InputMap.has_action(action):
            InputMap.add_action(action)
    var player := CharacterBody2D.new()
    player.motion_mode = CharacterBody2D.MOTION_MODE_FLOATING
    player.set_script(load("res://player.gd"))
    root.add_child(player)
    Input.action_press("move_right")
    Input.action_press("move_down")
    for i in 5:
        await physics_frame
    var speed := player.velocity.length()
    if absf(speed - 180.0) > 0.01:
        printerr("FAIL: expected 180, got ", speed)
        quit(1)
        return
    print("PASS")
    quit(0)
```

### Do not trust the exit status alone

The command-line reference does not promise a non-zero exit status for script errors.[16] Do not rely on the exit status alone: how a failed check is reported can vary by platform and by whether `--headless` is used, so check the output for errors as well. Command-line export failures, such as a missing preset or export template, end with a failure status.[53] Tell the agent to read the full output and treat any `SCRIPT ERROR`, `Parse Error` or `ERROR:` line as a failure, and give every automated run a timeout.

The `-d` (`--debug`) option starts a local command-line debugger.[16] When a script error occurs, that debugger stops at a `debug>` prompt and waits for input, which can stall an unattended agent.[53] gdUnit4's own runner works around this by passing `--remote-debug tcp://127.0.0.1:0`, with a source comment explaining that it prevents "an endless 'debug>' loop on script parse errors".[43] Omit `-d` in agent runs unless someone is watching.

### Automated tests with GUT or gdUnit4

Godot's own `--test` option runs the engine's unit tests and requires an engine compiled with `tests=yes`, so it is not a test runner for a game project.[16] Two community frameworks provide in-editor panels and command-line runners for project tests:

| | GUT (Godot Unit Test) | gdUnit4 |
| --- | --- | --- |
| Version for Godot 4.7 | 9.7.1 (released 10 July 2026), listed for 4.7.x[35][46] | 6.2.2 (released 7 October 2026); the README lists the 6.2.x line for Godot 4.5 to 4.7.1[39][45] |
| Install | Download the 9.7.1 release zip and put its `addons/gut` folder in the project (the Asset Library's GUT entry was 9.6.1, listed for Godot 4.6), then enable in **Project Settings > Plugins** and relaunch Godot[35][37] | Asset Library ("GdUnit4") or manual install, then enable in **Project Settings > Plugins**; restart recommended[56] |
| Test file | `extends GutTest`; files start with `test_`[37] | `extends GdUnitTestSuite`[39] |
| Command line | `godot -d -s --path "$PWD" addons/gut/gut_cmdln.gd` plus options such as `-gdir`, `-gtest`, `-gexit`[36] | `./addons/gdUnit4/runtest.sh -a <dir>` with `GODOT_BIN` set (`runtest.cmd` on Windows)[40] |
| Exit codes | 0 if all tests pass, 1 if any fail[36] | 0 success, 100 failures, 101 warnings[40] |
| Reports | JUnit XML with `-gjunit_xml_file`[36] | HTML (`index.htm`) and JUnit (`results.xml`) under `reports/`[40] |
| Input simulation | `GutInputSender` (`InputSender`), which sends `InputEvent`s to an object or to `Input`[55] | Scene Runner: `simulate_action_pressed`, key, mouse and touch input, `simulate_frames`[41][42] |
| C# | GDScript tests | GDScript and C# tests[39] |

Two practical points from the frameworks' own source:

1. **Import first.** Before the first `--import`, GUT stopped with `Some GUT class_names have not been imported. Please restart the Editor or run godot --headless --import`, the message in GUT's own source; GUT 9.7.1's command-line script then calls `quit(0)`, so the run exits with status 0.[38][54] Run `godot --headless --path . --import` after cloning or after adding the addon.
2. **gdUnit4 refuses headless mode by default.** Its runner exits with code 103 and the message "Headless mode is not supported!", because "Godot 'InputEvents' are not transported by the Godot engine in headless mode".[44] It accepts `--ignoreHeadlessMode`, which is reasonable only for tests that do not depend on input events; tests using the Scene Runner's input simulation need a display (for example a virtual display on a CI server).

An illustrative GUT test, saved as `res://test/unit/test_player.gd`:

```gdscript
extends GutTest

func test_diagonal_speed_is_normalized():
    for action in ["move_left", "move_right", "move_up", "move_down"]:
        if not InputMap.has_action(action):
            InputMap.add_action(action)
    var player := CharacterBody2D.new()
    player.motion_mode = CharacterBody2D.MOTION_MODE_FLOATING
    player.set_script(load("res://player.gd"))
    add_child_autofree(player)
    Input.action_press("move_right")
    Input.action_press("move_down")
    await wait_physics_frames(3)
    assert_almost_eq(player.velocity.length(), 180.0, 0.01)
    Input.action_release("move_right")
    Input.action_release("move_down")
    await wait_physics_frames(3)
    assert_eq(player.velocity, Vector2.ZERO)
```

```bash
godot --headless --path . --import
godot --headless -s --path . addons/gut/gut_cmdln.gd \
  -gdir=res://test/unit -gexit -gjunit_xml_file=res://reports/gut.xml
```

GUT's documentation recommends separating fast unit tests from slower integration tests in different directories, and its `wait_physics_frames` helper is best used with at least two frames.[37] gdUnit4 also publishes a GitHub Action for CI.[39] For agent work, a useful rule is: the agent writes or updates a test that fails before a fix, then shows the passing run, and a human still plays the change. The testing and releasing guide covers playtesting and release checks beyond unit tests.

### Debug in the editor

Then open the game and exercise the mechanic. Godot provides runtime debugging, profilers and visible collision shapes.[17] Use collision visualization to distinguish an incorrect hitbox from an incorrect script. For a runtime exception, collect the first relevant error, stack information, scene and input sequence; the Debugger panel's Stack Trace tab gives the stack and object state when execution breaks, and its Errors tab collects error and warning messages printed while the game runs.[18] Ask for a repair against that evidence, followed by the same reproduction and regression checks.

A visual comparison can help, but choose evidence appropriate to the question. Godot's Movie Maker produces offline-rendered, non-real-time video or image sequences and can support repeatable visual inspection; the documentation says it "is not designed for capturing real-time footage during gameplay".[19] From the command line, `--write-movie <file>` records, `--fixed-fps` sets the frame rate and `--quit-after N` stops after N frames; a `.png` output path produces numbered frames such as `example00000000.png` plus a `.wav` file.[19][16] Movie Maker records rendered frames, so do not assume a `--headless` run produces them; check that image frames were actually written, not only the `.wav` file. Retain the input sequence and relevant game state alongside a recording.

## Import generated assets deliberately

Use [Creating Game Assets with AI](https://aiwiki.ai/wiki/creating_game_assets_with_ai) for the generation and provenance workflow. In Godot, place approved source assets in the project and let the import system process them. Importing adds an `<asset>.import` file next to the source, and imported data goes into `.godot/imported/`.[20] The import documentation distinguishes loading imported assets through the resource system from reading ordinary files directly; using `FileAccess` for an imported asset "will work in the editor, but it will break in the exported project".[20]

Test a replacement in one scene before changing every instance. Keep its dimensions, origin, collision behavior and readability consistent with the mechanic. After an agent adds files from outside the editor, run `godot --headless --path . --import` or reopen the project, and check the import result. Store source artwork and generation records outside the automatically generated import cache.

## Export early and test the exported game

Create an export preset for the target platform in **Project > Export** and install export templates from **Editor > Manage Export Templates**. Godot's export dialog identifies missing requirements, and some platforms also need external SDKs.[21] Establish a small successful export before investing in the full content pipeline.

From the command line, the editor binary exports with a preset name from `export_presets.cfg`:[16][21]

```bash
godot --headless --path . --export-release "Linux" build/game.x86_64
godot --headless --path . --export-debug "Windows Desktop" build/game.exe
```

The command must use an editor binary, not an export template; preset names with spaces need quotes; a relative output path is relative to the project folder, not the shell's working directory; and the target directory must exist. `--export-debug` uses the debug template.[16] On machines without GPU access, such as CI servers, `--headless` is required.[16] If no matching templates are installed, the export fails with exit status 1 and the message `No export template found at the expected path`, naming a folder for the exact editor version (for example `export_templates/4.7.2.stable/`): templates must match the editor version. Without an `export_presets.cfg`, it stops with "This project doesn't have an `export_presets.cfg` file at its root."[53]

Check platform restrictions while choosing the language and renderer. The Godot 4 Web documentation requires WebAssembly and WebGL 2.0, uses the Compatibility renderer, and states that C# projects cannot currently export to the Web.[22] Recheck that versioned documentation before planning a browser release. A desktop editor run does not establish browser compatibility.

### C# projects

C# needs the .NET-enabled Godot editor and a separately installed .NET SDK, because Godot does not bundle MSBuild or the C# compiler. The current documentation states that Godot 4.5 requires .NET 8 or later and that exporting to Android requires .NET 9 or later; Android and iOS support is described as experimental.[52] Project assemblies must be rebuilt (the editor's Build button) before new exported variables or signals appear in the editor, and `--build-solutions` builds them from the command line.[52][16] For an agent, C# adds a compile step: Godogen's README notes that `dotnet build` type-checks the whole project before anything runs, while GDScript runs on any Godot build with no .NET toolchain.[51]

Ask another person to launch the exported build without the editor or the agent. Test starting, playing, failure, restart, quitting and any saved settings. Record the build, device and result. Use [Testing and Releasing AI-Assisted Games](https://aiwiki.ai/wiki/testing_and_releasing_ai_assisted_games) for the broader release checks and storefront disclosures.

## Common problems and fixes

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Movement never starts; `The InputMap action "move_right" doesn't exist` | Action missing or misspelled in the Input Map, or the wrong scene runs | Define the exact action names in **Project Settings > Input Map**; check the main scene[4][7] |
| `Cannot call method ... on a null value` after a rename (Godot 4.7.2 wording; the API reference quotes "Attempt to call <method> on a null instance") | A `get_node()` or `$` path no longer matches the tree | Update the path, or use `%Name` with `unique_name_in_owner`[33][53] |
| `Could not find base class "KinematicBody2D"` or `"yield" was removed in Godot 4` | Godot 3 code in a Godot 4 project | Use `CharacterBody2D` and `await`; run `--validate-conversion-3to4` for whole projects[31] |
| Signal "already connected" error, or a pickup scores twice | The same connection made in the editor and in code, or collection not disabled after the first hit | Keep one connection; check with `is_connected()`; disable the pickup when collected[32] |
| Player passes through a wall | Collision shapes, layers or masks | Run with `--debug-collisions` or enable Visible Collision Shapes[16][17] |
| A tool-created node vanishes after reopening | The node's `owner` was not set before packing | Set `owner` to the scene root, save, reopen[12] |
| `ext_resource, invalid UID ... using text path instead` | A hand-edited or invented `uid://` value, or a `.uid` file not moved with its script | Re-save the scene in the editor; commit and move `.uid` files with scripts[26][27] |
| GUT: `Some GUT class_names have not been imported` | No import pass since the addon was added or the repository was cloned | `godot --headless --path . --import`[38] |
| gdUnit4 exits with 103 | Headless mode is refused by default | Run with a display, or `--ignoreHeadlessMode` for tests without input events[44] |
| Agent's headless run hangs at `debug>` | `-d` local debugger stopped on a script error | Drop `-d` in unattended runs; add `--quit-after` or a timeout[16][43] |
| A check "passed" but the log shows `SCRIPT ERROR` | Exit status 0 despite script errors | Fail the run on any `SCRIPT ERROR`, `Parse Error` or `ERROR:` line |
| `No export template found at the expected path` | Templates missing or for another version | **Editor > Manage Export Templates** for the exact editor version[21] |
| Export passwords or keys missing on a new machine | `.godot/export_credentials.cfg` is not in version control | Copy it manually to the new machine; keep it out of Git[21] |
| Asset works in the editor but is missing from a build | `FileAccess` used on an imported asset, or the file excluded from export | Load through the resource system; check import and export filters[20][21] |
| Path works on Windows or macOS but not in the export | File-name case differs from the path in code | Use consistent snake_case, lowercase names[13] |
| New C# export or signal not visible in the editor | Assemblies not rebuilt | Build in the editor or run `--build-solutions`[52] |
| Web export unavailable, or the web build looks different from desktop | C# project (cannot export to the Web), or visuals built for Forward+ or Mobile (web builds use the Compatibility renderer: `rendering/renderer/rendering_method.web` defaults to `gl_compatibility`) | GDScript for Web; test the visuals with the Compatibility renderer[22][30] |

## What research supports

Godot-based benchmarks offer evidence for checking behavior inside the engine, rather than accepting generated files as a finished result. The June 2026 *GameCraft-Bench* preprint evaluates 140 Godot tasks across 15 game families through replayed demonstrations and rubric-guided multimodal judging. Its authors report that the strongest agent scored 41.46% and most agents below 40%, and that agents "struggle to deliver complete games with sufficient content, functional visual feedback, and coherent presentation".[23]

The September 2026 *SWE-Game* preprint, revised in October, covers 247 tasks grounded in 41 Godot games across 13 gameplay categories. It combines engine-state checks, input replay and demonstrations with separate visual assessment. The authors report best overall scores below 60 out of 100 on the three construction tasks, and identify requirement omissions and gameplay-logic errors as the predominant problems in reviewed submissions. On human-labeled behaviors from 100 agent-built games, their executable checks reached 92.59% balanced accuracy, compared with 78.41% for a video-based vision-language judge.[24] These are results for specified tasks and evaluated systems, not a success forecast for a particular game. The practical recommendation here is to review code, run engine-level tests, observe gameplay and test the exported artifact separately.

## See also

- [Developing Games with AI](https://aiwiki.ai/wiki/developing_games_with_ai) (hub guide)
- [Developing Browser Games with AI](https://aiwiki.ai/wiki/developing_browser_games_with_ai)
- [Developing Unity Games with AI](https://aiwiki.ai/wiki/developing_unity_games_with_ai)
- [Developing Unreal Engine Games with AI](https://aiwiki.ai/wiki/developing_unreal_engine_games_with_ai)
- [Creating Game Assets with AI](https://aiwiki.ai/wiki/creating_game_assets_with_ai)
- [Testing and Releasing AI-Assisted Games](https://aiwiki.ai/wiki/testing_and_releasing_ai_assisted_games)
- [AI game development](https://aiwiki.ai/wiki/ai_game_development)

## References

1. Godot Engine. [Your first 2D game](https://docs.godotengine.org/en/stable/getting_started/first_2d_game/index.html). Official documentation, accessed 30 October 2026.
2. Godot Engine. [Godot release policy](https://docs.godotengine.org/en/stable/about/release_policy.html). Official documentation, accessed 30 October 2026.
3. Godot Engine. [Version control systems](https://docs.godotengine.org/en/stable/tutorials/best_practices/version_control_systems.html). Official documentation, accessed 30 October 2026.
4. Godot Engine. [Nodes and Scenes](https://docs.godotengine.org/en/stable/getting_started/step_by_step/nodes_and_scenes.html). Official documentation, accessed 30 October 2026.
5. Godot Engine. [Scene organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/scene_organization.html). Official documentation, accessed 30 October 2026.
6. Godot Engine. [Using signals](https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html). Official documentation, accessed 30 October 2026.
7. Godot Engine. [Input](https://docs.godotengine.org/en/stable/classes/class_input.html), especially `get_vector()` and global input state. Official API reference, accessed 30 October 2026.
8. Godot Engine. [CharacterBody2D](https://docs.godotengine.org/en/stable/classes/class_characterbody2d.html). Official API reference, accessed 30 October 2026.
9. Godot Engine. [Using InputEvent](https://docs.godotengine.org/en/stable/tutorials/inputs/inputevent.html). Official documentation, accessed 30 October 2026.
10. Godot Engine. [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html). Official documentation, accessed 30 October 2026.
11. Godot Engine. [ResourceSaver](https://docs.godotengine.org/en/stable/classes/class_resourcesaver.html). Official API reference, accessed 30 October 2026.
12. Godot Engine. [PackedScene](https://docs.godotengine.org/en/stable/classes/class_packedscene.html), especially ownership when packing a scene. Official API reference, accessed 30 October 2026.
13. Godot Engine. [Project organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html). Official documentation, accessed 30 October 2026.
14. Coding-Solo. [Godot MCP](https://github.com/Coding-Solo/godot-mcp). Repository README and documented tool list, MIT license, accessed 30 October 2026.
15. Godot Engine. [Running code in the editor](https://docs.godotengine.org/en/stable/tutorials/plugins/running_code_in_the_editor.html). Official documentation, accessed 30 October 2026.
16. Godot Engine. [Command line tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html). Official command reference, accessed 30 October 2026.
17. Godot Engine. [Overview of debugging tools](https://docs.godotengine.org/en/stable/tutorials/scripting/debug/overview_of_debugging_tools.html). Official documentation, accessed 30 October 2026.
18. Godot Engine. [Debugger panel](https://docs.godotengine.org/en/stable/tutorials/scripting/debug/debugger_panel.html). Official documentation, accessed 30 October 2026.
19. Godot Engine. [Creating movies](https://docs.godotengine.org/en/stable/tutorials/animation/creating_movies.html). Official documentation, accessed 30 October 2026.
20. Godot Engine. [Import process](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/import_process.html). Official documentation, accessed 30 October 2026.
21. Godot Engine. [Exporting projects](https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html). Official documentation, accessed 30 October 2026.
22. Godot Engine. [Exporting for the Web](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html). Official documentation, accessed 30 October 2026.
23. Tongxu Luo et al. [GameCraft-Bench: Can Agents Build Playable Games End-to-End in a Real Game Engine?](https://arxiv.org/abs/2606.17861). arXiv:2606.17861, preprint, 16 June 2026.
24. Xiaoyu Chen et al. [SWE-Game: Can Coding Agents Build the Games We Want?](https://arxiv.org/abs/2609.33678v3). arXiv:2609.33678v3, preprint, 7 October 2026; first submitted 27 September 2026.
25. Godot Engine. [Godot download archive](https://godotengine.org/download/archive/). Lists 4.7.2-stable (18 August 2026) and 4.8-beta2 (29 October 2026), accessed 30 October 2026.
26. Godot Engine. [TSCN file format](https://docs.godotengine.org/en/stable/engine_details/file_formats/tscn.html). Official documentation, accessed 30 October 2026.
27. Hugo Locurcio. [UID changes coming to Godot 4.4](https://godotengine.org/article/uid-changes-coming-to-godot-4-4/). Godot Engine blog, 15 January 2025.
28. Godot Engine. [GDScript warning system](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/warning_system.html). Official documentation, accessed 30 October 2026.
29. Godot Engine. [Static typing in GDScript](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/static_typing.html). Official documentation, accessed 30 October 2026.
30. Godot Engine. [ProjectSettings](https://docs.godotengine.org/en/stable/classes/class_projectsettings.html), `debug/gdscript/warnings/*` settings. Official API reference, accessed 30 October 2026.
31. Godot Engine. [Upgrading from Godot 3 to Godot 4](https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.html). Official documentation, accessed 30 October 2026.
32. Godot Engine. [Object](https://docs.godotengine.org/en/stable/classes/class_object.html), `connect()`. Official API reference, accessed 30 October 2026.
33. Godot Engine. [Node](https://docs.godotengine.org/en/stable/classes/class_node.html), `get_node()` and `unique_name_in_owner`. Official API reference, accessed 30 October 2026.
34. Godot Engine. [SceneTree](https://docs.godotengine.org/en/stable/classes/class_scenetree.html), `quit()`. Official API reference, accessed 30 October 2026.
35. bitwes. [GUT](https://github.com/bitwes/Gut). GitHub README and version table, MIT license, accessed 30 October 2026.
36. GUT documentation. [Command Line](https://gut.readthedocs.io/en/latest/Command-Line.html). Accessed 30 October 2026.
37. GUT documentation. [Quick Start](https://gut.readthedocs.io/en/latest/Quick-Start.html) and [Install](https://gut.readthedocs.io/en/latest/Install.html). Accessed 30 October 2026.
38. bitwes. [version_conversion.gd](https://github.com/bitwes/Gut/blob/v9.7.1/addons/gut/version_conversion.gd). GUT 9.7.1 source, `error_if_not_all_classes_imported()`, accessed 30 October 2026.
39. Godot gdUnit Labs. [gdUnit4](https://github.com/godot-gdunit-labs/gdUnit4). GitHub README and compatibility table, accessed 30 October 2026.
40. gdUnit4 documentation. [Command Line Tool](https://godot-gdunit-labs.github.io/gdUnit4/latest/advanced_testing/cmd/). Accessed 30 October 2026.
41. gdUnit4 documentation. [Scene Runner](https://godot-gdunit-labs.github.io/gdUnit4/latest/advanced_testing/sceneRunner/). Accessed 30 October 2026.
42. gdUnit4 documentation. [Simulate Actions](https://godot-gdunit-labs.github.io/gdUnit4/latest/advanced_testing/scene_runner/actions/). Accessed 30 October 2026.
43. Godot gdUnit Labs. [runtest.sh](https://github.com/godot-gdunit-labs/gdUnit4/blob/v6.2.2/addons/gdUnit4/runtest.sh). gdUnit4 6.2.2 source, accessed 30 October 2026.
44. Godot gdUnit Labs. [GdUnitTestCIRunner.gd](https://github.com/godot-gdunit-labs/gdUnit4/blob/v6.2.2/addons/gdUnit4/src/core/runners/GdUnitTestCIRunner.gd). gdUnit4 6.2.2 source, headless-mode check, accessed 30 October 2026.
45. Godot gdUnit Labs. [gdUnit4 v6.2.2 release](https://github.com/godot-gdunit-labs/gdUnit4/releases/tag/v6.2.2). GitHub, 7 October 2026.
46. bitwes. [GUT 9.7.1 release](https://github.com/bitwes/Gut/releases/tag/v9.7.1). GitHub, 10 July 2026.
47. npm. [@coding-solo/godot-mcp](https://www.npmjs.com/package/@coding-solo/godot-mcp). Package registry entry, latest version 0.1.1, accessed 30 October 2026.
48. Ivan Murzak. [Godot-MCP](https://github.com/IvanMurzak/Godot-MCP). GitHub README, Apache-2.0 license (Asset Library entry version 0.33.0), accessed 30 October 2026.
49. FlamxGames. [Godot AI Assistant Hub](https://github.com/FlamxGames/godot-ai-assistant-hub). GitHub README (version 2.1.0), MIT license, accessed 30 October 2026.
50. Godot Engine. [Asset Library search: "mcp"](https://godotengine.org/asset-library/asset?filter=mcp). Accessed 30 October 2026.
51. htdt. [Godogen](https://github.com/htdt/godogen). GitHub README, MIT license, accessed 30 October 2026.
52. Godot Engine. [C# basics](https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_basics.html). Official documentation, accessed 30 October 2026.
53. Godot Engine. [Godot source code, 4.7.2-stable](https://github.com/godotengine/godot/tree/4.7.2-stable). Error and warning strings in `modules/gdscript/` (`gdscript_parser.cpp`, `gdscript_analyzer.cpp`, `gdscript_warning.cpp`, `gdscript_vm.cpp`), `core/input/input_map.cpp`, `scene/resources/resource_format_text.cpp`, `core/debugger/local_debugger.cpp`, `core/config/project_settings.cpp`, `editor/editor_node.cpp` and `editor/export/editor_export_platform.cpp`. Accessed 30 October 2026.
54. bitwes. [gut_cmdln.gd](https://github.com/bitwes/Gut/blob/v9.7.1/addons/gut/gut_cmdln.gd). GUT 9.7.1 source, accessed 30 October 2026.
55. GUT documentation. [Mocking Input](https://gut.readthedocs.io/en/latest/Mocking-Input.html). Accessed 30 October 2026.
56. gdUnit4 documentation. [Installation](https://godot-gdunit-labs.github.io/gdUnit4/latest/first_steps/install/). Accessed 30 October 2026.