/godot-export

name: godot-export
description: >
  Exports Godot 4.7 projects: templates, export_presets.cfg for desktop, Web and Android,
  command-line exports and web COOP/COEP headers. Use on "No export template found", a blank web
  build, a SharedArrayBuffer error or files missing after export. Not for tests in CI
  (`godot-gdscript-headless-testing`), store uploads (`steam-publish`, `itch-publish`) or netcode
  (`godot-multiplayer`).

Godot Export & Builds (4.x)

Turn a project into builds from export presets on the command line, then prove the build runs. Targets **Godot 4.7**; export templates must match the editor version exactly, so read `config/features` in `project.godot` and the CI's Godot version first.

Workflow

1. **Read `export_presets.cfg`.** Each `[preset.N]` has a `name` (what the CLI wants), a `platform` and an `export_path`. If the file is missing, create presets in *Project > Export* or ask the user to; avoid hand-writing a full preset from nothing. 2. **Install matching templates** (*Editor > Manage Export Templates*, or unpack the `.tpz` so its files land in the folder the error message names, for example `~/.local/share/godot/export_templates/4.7.2.stable/` on Linux). `--export-pack` needs none. 3. **Export from the CLI**, from the project folder, into a folder that already exists: `godot --headless --export-release "<preset name>" build/<platform>/<file>`. 4. **Per platform:** Web needs COOP/COEP headers only when the preset's *Thread Support* is on (off by default); Android needs SDK paths and a keystore; macOS needs signing and notarization to pass Gatekeeper. 5. **Verify before you finish:**

• The export command exits 0 and the output file exists. A non-zero exit always means

failure (missing template, unknown preset, unwritable path); the reason is in the log.

• Smoke-run the exported data without templates: `godot --headless --path <project> --export-pack "<preset>" build/game.pck`,

then `godot --headless --main-pack build/game.pck --quit-after 300 > run.log 2>&1` and `grep -nE "SCRIPT ERROR|^ERROR:" run.log`. This catches files the preset's filters left out and `res://` writes, because it loads only what was packed.

• For a Linux or server build, run the binary itself the same way:

`./build/linux/game.x86_64 --headless --quit-after 300`.

• Platforms you cannot run here (consoles, iOS, a signed macOS app, phones): ask the user

to launch the build on the device and report whether it starts, saves and loads.

Patterns

1. Command-line exports

mkdir -p build/windows build/linux build/web          # Godot will not create the folder
godot --headless --export-release "Windows Desktop" build/windows/game.exe
godot --headless --export-release "Linux"           build/linux/game.x86_64
godot --headless --export-release "Web"             build/web/index.html
godot --headless --export-debug   "Windows Desktop" build/windows/game_debug.exe
godot --headless --export-pack    "Linux"           build/game.pck   # .zip for a ZIP pack
godot --headless --export-patch   "Linux"           build/patch1.pck --patches build/game.pck

2. Detect the build at runtime

func _ready() -> void:
    if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
        start_server_only()           # skip rendering and UI
    if OS.has_feature("web"):
        apply_web_settings()
    if OS.has_feature("demo"):        # a custom tag set in one preset's Features
        limit_content()

3. Write paths that survive export

const SAVE_PATH := "user://savegame.tres"   # res:// is read-only inside a .pck

func _ready() -> void:
    print(OS.get_user_data_dir())           # where user:// lives on this platform

Gotchas

• **`No export template found at the expected path`** → templates are missing or for another

version (including beta/rc). Install the exact version; 4.7 can download one platform's templates instead of the full set.

• **`Invalid export preset name: ...`** → names are case- and space-sensitive; the output

then lists the presets it found. Quote the name.

• **`Can't open file for writing`** → the output folder does not exist. `mkdir -p` first.
• **A file is missing only in the build** → non-resource files (`.json`, `.txt`, `.csv`) are

not exported unless listed in the preset's *Filters to export non-resource files* (`include_filter="*.json"`). Resources excluded by `exclude_filter` vanish too.

• **Saving works in the editor, fails in the build** → the game writes under `res://`. Use

`user://`.

• **Web build: blank page or `SharedArrayBuffer` error** → *Thread Support* is on and the host

does not send `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`. Turn threads off, enable the host's option (itch.io has one), or use the PWA option that adds the headers. `file://` never works.

• **Web build looks different** → web always uses the Compatibility renderer.
• **C# project will not export to web** → not supported in Godot 4; see `godot-csharp`.
• **Secrets end up in Git** → keystore passwords and encryption keys live in

`.godot/export_credentials.cfg`, not `export_presets.cfg`. Keep `.godot/` ignored and supply secrets in CI through environment variables or a restored file.

• **Shipping a debug build** → `--export-debug` keeps the remote debugger and debug checks;

ship `--export-release`.

References

• Read `references/presets-and-cli.md` for the `export_presets.cfg` layout, every useful CLI

flag, feature tags, web, Android and Apple setup, PCK patches and DLC, and why PCK encryption needs custom templates.

Related skills

• `godot-gdscript-headless-testing`: tests before the export step in CI.
• `godot-multiplayer`: the dedicated-server code you export.
• `godot-csharp`: .NET export limits.
• `steam-publish` / `itch-publish`: getting the build to players.

Versio