godot-export

# Export presets & CLI reference (Godot 4.7)

Depth companion to `godot-export`.

## export_presets.cfg

Generated/edited by *Project > Export*; commit it so CI and teammates share presets. It is
an INI-style file with a `[preset.N]` block per preset and a matching `[preset.N.options]`
block. Example shape (do not hand-author from scratch — let the editor create it):

```ini
[preset.0]
name="Windows Desktop"
platform="Windows Desktop"
runnable=true
export_path="build/windows/game.exe"
custom_features=""
exclude_filter=""
include_filter=""

[preset.0.options]
binary_format/embed_pck=false
application/icon="res://icon.ico"
application/product_name="My Game"
codesign/enable=false
```

Sensitive values (keystore passwords, encryption keys) live in `export_presets.cfg` too —
keep them out of public repos or inject them in CI rather than committing.

## Useful command-line flags

```
godot --headless                      run without a window/GPU
      --path <dir>                    project directory (where project.godot is)
      --export-release "<preset>" <out>   export a release build
      --export-debug "<preset>" <out>     export a debug build
      --export-pack "<preset>" <out>      export only the .pck/.zip data
      --quit-after <frames|seconds>   auto-quit (smoke tests)
      --main-pack <file.pck>          run a specific data pack
      --verbose                       detailed logging
      -- <args>                       pass args to your game (OS.get_cmdline_user_args())
```

Use the exact preset `name` (case/space-sensitive). Run from the project dir or pass
`--path`. Exit code is non-zero on export failure — check it in CI.

## Custom feature tags

Add tags under a preset's *Features* (or `custom_features`) and branch at runtime with
`OS.has_feature("tag")`. Common built-ins: `web`, `windows`, `macos`, `linux`, `android`,
`ios`, `mobile`, `pc`, `debug`, `release`, `editor`, `template`, `dedicated_server`,
`64`/`32`. Use a `demo` tag to ship a content-limited build from the same project.

## Web (HTML5) specifics

- Output is `index.html` + `.js`/`.wasm`/`.pck`. Serve over HTTP(S).
- Threaded builds need **cross-origin isolation**:
  - `Cross-Origin-Opener-Policy: same-origin`
  - `Cross-Origin-Embedder-Policy: require-corp`
  Without these, `SharedArrayBuffer` is unavailable and the engine errors or falls back.
- itch.io: enable "This file will be played in the browser" and the SharedArrayBuffer
  support option. GitHub Pages can't set the headers — use a host that can, or a service
  worker shim.
- Reduce size: enable compression, trim unused features, and consider the
  "Extensions Support" toggle only if needed.

## Android

- Set Android SDK + OpenJDK paths in Editor Settings > Export > Android.
- Install the Android build template (Project > Install Android Build Template) for custom
  Gradle builds / plugins.
- Provide a **debug keystore** (auto for debug) and a **release keystore** for store
  builds. Add the `INTERNET` permission for networked games.
- Choose architectures (arm64-v8a is standard for modern devices).

## macOS / iOS

- macOS distribution: enable codesign, provide an Apple Developer ID, and notarize the
  `.app`/`.dmg`; otherwise Gatekeeper blocks it.
- iOS: exports an Xcode project; build/sign/submit through Xcode.

## PCK patching & DLC

Export extra content as a separate `.pck` and load it at runtime:

```gdscript
var ok := ProjectSettings.load_resource_pack("user://dlc1.pck")  # mounts into res://
```

A patch pack can override or add files. Use `--export-pack` to produce packs in CI.

## Encryption

Set a 64-hex-char script encryption key (Project > Export, or `GODOT_SCRIPT_ENCRYPTION_KEY`
env for CLI) and enable "Encrypt Exported PCK". Note: client-side encryption deters casual
inspection but cannot fully protect assets on a user's machine — don't store true secrets
in the build.

---
name: godot-export
description: >
  Export and build a Godot 4.7 project for distribution: install export templates,
  define export presets (Windows/macOS/Linux/Web/Android), run headless command-line
  exports for CI, and handle web (HTML5) COOP/COEP and dedicated-server/headless
  builds. Use when exporting a Godot game, configuring export_presets.cfg, building
  for web/desktop/mobile, or automating builds from the command line.
---

# Godot Export & Builds (4.x)

Turn a project into runnable platform builds via export presets and the command line, and
handle the web/dedicated-server gotchas. Targets **Godot 4.7**.

## When to use

- Use when producing a shippable build: installing export templates, creating/editing
  export presets, exporting from the editor or headless CLI (CI), or troubleshooting web
  (HTML5) and dedicated-server exports.

**When *not* to use:** storefront publishing flows → `steam-publish`/`itch-publish`; the
networking code of a server → `godot-multiplayer` (this skill covers building it headless).

## Core workflow

1. **Install export templates** matching your engine version: Editor menu >
   *Manage Export Templates* (download), or install the `.tpz` offline. Versions must
   match the editor exactly.
2. **Add export presets** in *Project > Export*: pick a platform (Windows Desktop, macOS,
   Linux, Web, Android, iOS), set the export path, icons, features, and resource
   include/exclude filters. Presets are saved to `export_presets.cfg`.
3. **Export from the editor** with *Export Project* (release) or *Export PCK/ZIP*.
4. **Or export headless from the CLI** for automation/CI using
   `--export-release "<preset name>" <output path>`.
5. **Per platform:** Web needs cross-origin isolation (COOP/COEP) for threads; Android
   needs the SDK/keystore; macOS/iOS need signing for distribution.
6. **Smoke-test the build** on the target before shipping — exported builds use `res://`
   read-only; write to `user://`.

## Patterns

### 1. Headless CLI export (CI-friendly)

```bash
# Preset name must match exactly what's in Project > Export (quote it).
# Run from the project directory (where project.godot lives).
godot --headless --export-release "Windows Desktop" build/windows/game.exe
godot --headless --export-release "Linux/X11"       build/linux/game.x86_64
godot --headless --export-release "Web"             build/web/index.html

# Debug build (includes debug symbols / remote debug):
godot --headless --export-debug "Windows Desktop" build/windows/game_debug.exe

# Export only the data pack (no executable):
godot --headless --export-pack "Linux/X11" build/game.pck
```

### 2. Run a project headless (dedicated server / tests)

```bash
# No window/GPU — for a server build or automated runs.
godot --headless --path . res://server_main.tscn
# Quit after N main-loop iterations (frames, NOT seconds) — handy for a headless smoke test:
godot --headless --path . --quit-after 600
```

### 3. Detect the build context at runtime

```gdscript
func _ready() -> void:
    if OS.has_feature("dedicated_server") or DisplayServer.get_name() == "headless":
        _start_server_only()          # skip rendering/UI on a headless server
    if OS.has_feature("web"):
        _apply_web_tweaks()
    # Custom feature tags (added per preset) are also queryable:
    # if OS.has_feature("demo"): limit_content()
```

### 4. Choose write paths that survive export

```gdscript
# res:// is READ-ONLY in exported games. Always write to user://.
func save_path() -> String:
    return "user://savegame.tres"     # resolves to the OS app-data dir

func _ready() -> void:
    print(OS.get_user_data_dir())     # where user:// actually lives
```

## Pitfalls

- **"No export template found".** Templates must match the exact editor version (incl.
  beta/rc). Re-download via *Manage Export Templates* after upgrading Godot.
- **Preset name mismatch in CLI.** `--export-release "Windows"` fails if the preset is
  named `"Windows Desktop"`. Names are case- and space-sensitive; quote them.
- **Web build shows a blank page / threads error.** HTML5 builds that use threads require
  the server to send `Cross-Origin-Opener-Policy: same-origin` and
  `Cross-Origin-Embedder-Policy: require-corp` (cross-origin isolation for
  `SharedArrayBuffer`). Must be served over HTTP(S), not opened as a `file://`. itch.io has
  a "SharedArrayBuffer support" toggle for this.
- **Writing to `res://` at runtime fails** in exports (read-only, packed). Use `user://`.
- **Missing resources in the build.** Non-resource files (e.g. external `.json`, `.txt`)
  are not auto-included — add them via the preset's *Resources > Filters to export
  non-resource files* (e.g. `*.json`).
- **Android export needs setup**: Android SDK/JDK paths in Editor Settings, a debug or
  release **keystore**, and the `INTERNET` permission for networked games.
- **macOS/iOS distribution requires signing/notarization**; unsigned macOS apps are
  blocked by Gatekeeper.
- **Debug vs release.** `--export-debug` enables remote debugging and debug checks; ship
  `--export-release`.

## References

- For the `export_presets.cfg` structure, all useful CLI flags, custom feature tags,
  PCK/expansion patching, encryption, and per-platform setup (Android keystore, macOS
  signing, web headers), read `references/presets-and-cli.md`.

## Related skills

- `godot-multiplayer` — the dedicated-server code you export headless.
- `steam-publish` / `itch-publish` — getting the build to players.
- `prototype-fast` / `game-jam` — quick web/desktop builds for sharing.