Skip to content

godotmaker.yaml

godotmaker.yaml lives at .claude/godotmaker.yaml inside each generated project. It tells GodotMaker about your machine — the path to your Godot executable — so it can be different per host without changing the project files.

When you work on one project across two computers (or share a project with another developer), each machine has its own copy of this file. The project files themselves stay the same; only this one file differs.

What's in it

The file currently has one field:

godot_path — the full path to the Godot 4 executable on this machine. GodotMaker uses this every time it needs to run Godot: compiling scripts, running unit tests, capturing screenshots.

Platform Typical value
Windows "C:/Godot/Godot_v4.4-stable_win64.exe"
macOS "/Applications/Godot.app/Contents/MacOS/Godot"
Linux "/usr/local/bin/godot4"

If Godot is already on your system PATH, you can set it to just "godot" and omit the full path.

A minimal file looks like this:

# Host-specific tool paths -- not committed to git
godot_path: "C:/Godot/Godot_v4.4-stable_win64.exe"

When to edit it

Edit this file when:

  • You move your Godot installation to a different folder.
  • You upgrade Godot and the executable name changes (e.g. _v4.4 → _v4.5).
  • You open the project on a second machine for the first time and the path on that machine differs from the first.

When NOT to edit it

Do not edit this file to change per-project behaviour like which AI model to use or which image generator to call. Those settings belong in .godotmaker/config.yaml — see Project config.

How it gets created

The first time you run python tools/publish.py <project>, the publish script checks whether .claude/godotmaker.yaml already exists. If it does not, it asks you one question:

No godotmaker.yaml found. Let's create one.
Enter the full path to your Godot executable
  (e.g. C:/path/to/Godot_v4.4-stable_win64.exe)
godot_path: _

What you enter is verified by running <godot_path> --version before the file is written. The verification has three outcomes:

  • Verified — the command exits cleanly (return code 0). Whatever it prints on stdout is shown back as the detected version (or ? if it stayed silent — wrapper scripts and sandbox runners sometimes suppress output, and that is intentionally still treated as success). Publish writes the file and continues.
  • Empty input or invalid path — publish prints the error (executable not found, non-zero exit, timeout) and re-prompts. You get up to 5 attempts before the script gives up without writing the file.
  • Aborted (Ctrl+C / Ctrl+D) — publish prints an "aborted" message and leaves the file uncreated; re-run publish later to set the path.

If Godot is on your system PATH you can still enter just "godot" — it is verified the same way (the validator runs godot --version), and only writes if it actually resolves and runs.

The file is only created during the first publish that produces a verified path. On every subsequent publish the file is left untouched — your path is never overwritten automatically.

What happens if it's wrong

If godot_path points to an executable that does not exist or is the wrong version, most /gm-* commands that invoke Godot will fail with a path error. Run python tools/check_env.py first — it reads this file, tries to run Godot, and tells you exactly what is wrong before you get partway through a build. See check-env for details.