When to Use
- Preparing release builds for Windows, Linux, macOS, Android, iOS, or Web.
- Setting up automated CI/CD pipelines for Godot exports.
- Managing export templates, feature flags, and platform-specific configurations.
- Optimizing build sizes and stripping debug symbols.
- Implementing patching systems (PCK) or SteamPipe uploads.
Prerequisites
- Godot 4.x installed (engine-accurate procedures apply to 4.7+).
- Export templates installed via Editor → Manage Export Templates → Download.
- Platform-specific SDKs:
- Android: Android SDK, OpenJDK 17, Debug keystore.
- iOS: macOS with Xcode, Apple Developer account, Provisioning profile.
- macOS: Developer ID certificate for codesigning.
- Windows host is primary (PowerShell). Keep Windows path notes when present.
Procedure
1. Basic Export Setup
- Open Project → Export.
- Add preset (Windows, Linux, etc.).
- Configure settings (icon, binary format, etc.).
- Export Project.
2. Command-Line Export (Headless)
Use PowerShell for command-line exports:
# Export release build
godot --headless --export-release "Windows Desktop" builds/game.exe
# Export debug build
godot --headless --export-debug "Windows Desktop" builds/game_debug.exe
# PCK only (for patching)
godot --headless --export-pack "Windows Desktop" builds/game.pck
3. Platform-Specific Settings
- Windows: Format
.exe (single file) or .pck + .exe. Icon: .ico file. Include: *.import, *.tres, *.tscn.
- Web: Export Type: Regular or GDExtension. Thread Support: For SharedArrayBuffer. VRAM Compression: Optimized for size.
- Android: Set SDK Path and Keystore in Editor Settings (Export → Android).
- iOS: Export creates
.xcodeproj. Build in Xcode for App Store.
- macOS: Codesign: Developer ID certificate. Notarization: Required for distribution. Architecture: Universal (Intel + ARM).
4. Feature Flags
Check platform at runtime:
if OS.get_name() == "Windows":
# Windows-specific code
pass
if OS.has_feature("web"):
# Web build
pass
if OS.has_feature("mobile"):
# Android or iOS
pass
5. Build Optimization
- Reduce Build Size: Exclude editor-only files in export preset (e.g.,
*.md, *.txt, docs/*). Remove unused imports.
- Strip Debug Symbols: In export preset options, set Debugging → Debug: Off, Binary Format → Architecture: 64-bit only.
- VRAM Compression: Enable ASTC/ETC2 compression in Import settings for Web/Mobile. ALWAYS disable compression for Pixel Art to maintain crisp edges.
- S3TC/BPTC: Mandatory for Desktop (Forward+). BPTC is superior for Normal Maps and HDR.
- ETC2: Standard for older Android/iOS devices.
- ASTC: Modern mobile standard. High quality/size ratio.
6. Expert Export Patterns
Platform-Specific-Patching (Delta Updates)
Mount external PCK archives to update game content without a full reinstall.
func _load_patch(patch_path: String) -> bool:
if FileAccess.file_exists(patch_path):
return ProjectSettings.load_resource_pack(patch_path, true) # true = replace files
return false
Steam-Upload-Pipeline (SteamPipe)
Automate distribution to Steam branches.
# export_steam_upload.ps1
$SteamCMD = "C:\steamcmd\steamcmd.exe"
& $SteamCMD +login $env:STEAM_USER $env:STEAM_PASS +run_app_build "res://builds/app_build.vdf" +quit
Universal-Build-Manager (One-Click Export)
Iterate through all export presets to generate a full suite of release binaries.
func export_all():
var config := ConfigFile.new()
config.load("res://export_presets.cfg")
for section in config.get_sections():
if section.begins_with("preset."):
var preset_name = config.get_value(section, "name")
var path = config.get_value(section, "export_path")
OS.execute(OS.get_executable_path(), ["--headless", "--export-release", preset_name, path])
7. Available Scripts (Load when implementing corresponding patterns)
- export_headless_pipeline.ps1: Load before automating multi-platform headless exports.
- export_version_sync.gd: Load to sync Git tags/hashes with 'application/config/version'.
- export_post_process_hook.gd: Load when using
EditorExportPlugin for post-build tasks (Zipping, Manifests).
- export_feature_flag_manager.gd: Load for runtime behavior swapping via build feature flags.
- export_pck_patch_loader.gd: Load for runtime patching logic (mounting external PCK archives and DLC).
- export_android_signing_env.ps1: Load for secure environment variable setup for Android release keystores.
- export_custom_build_stripper.py: Load for SCons configuration to strip unused Godot modules.
- export_macos_notarize_cmd.ps1: Load for macOS code signing and notarization CLI procedure.
- export_build_size_report.gd: Load to audit resource sizes and optimize build footprints.
- export_ci_github_actions.yml: Load for professional CI/CD workflow for automated multi-platform Godot releases.
- SteamPipe / SteamCMD: Use the inline PowerShell in Steam-Upload-Pipeline (
steamcmd + +run_app_build VDF). This folder has no dedicated SteamCMD wrapper file.
- export_universal_manager.gd: Load to programmatically iterate and export all defined presets in one click.
Pitfalls
Platform & Validation
- NEVER export to production without a 'Smoke Test' — "It runs in editor" is NOT enough. Web, Mobile, and Console have unique memory/shader constraints.
- NEVER skip macOS Notarization — Apple's Gatekeeper will block unsigned apps. Use
notarytool OR distribute exclusively via Steam/App Store.
- NEVER use ad-hoc file paths —
res:// is read-only in builds. Use user:// for saves and logs, or paths will fail on locked file systems.
Performance & Size
- NEVER use 'Debug' templates for release — Debug binaries are bloated and slow. Always use
--export-release to strip profiling overhead.
- NEVER include raw resources in builds — Check your export filters. If you include
.md, .txt, or .psd files, you're wasting player bandwidth and disk space.
- NEVER ignore VRAM compression — Large textures in Web/Mobile builds will crash the GPU driver. Enable ASTC/ETC2 compression in Import settings.
Security
- NEVER commit keystores or raw passwords to Git — Use Environment Variables and CI Secrets (
export_android_signing_env.ps1).
- NEVER allow debug commands in Production — Use
OS.has_feature("release") to purge console/cheats from the final build.
- NEVER bake shaders on export for Dedicated Servers — The Shader Baker (Godot 4.5+) is for visual clients. Enabling it for headless servers is wasted build time.
Godot 4.7+ Specifics
EditorSceneFormatImporter constants moved to ImportFlags enum — update importer scripts.
- Asset Store replaces Asset Library in editor — document addon acquisition via new store UI.
- HDR export: verify viewport HDR settings per platform in export presets.
Verification
- Check Export Output: Verify the executable or PCK file exists in the specified
export_path.Test-Path "builds/game.exe"
- Verify Version Sync: Ensure
application/config/version in project.godot matches the Git tag.
- Test Feature Flags: Run the build and verify that
OS.has_feature("release") correctly purges debug tools.
- Check Build Size: Use
export_build_size_report.gd to ensure no raw resources (.md, .txt, .psd) are included.
- macOS Notarization: Run
export_macos_notarize_cmd.ps1 and verify the app passes Gatekeeper checks.
Related skills
1---
2name: godot-export-builds
3description: "Configures Godot 4.x export templates, presets, PCK patches, SteamCMD VDF uploads, codesign/notarytool, Android keystores, and OS.has_feature flags. Use when shipping Windows, Linux, macOS, Android, iOS, or Web binaries, or stripping debug symbols. Never ship debug templates, skip Gatekeeper notarization, or commit keystores. Distinct from GdUnit4/PlayGodot test export (game-godot)."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/godot-export-builds
7---
8
9## When to Use
10- Preparing release builds for Windows, Linux, macOS, Android, iOS, or Web.
11- Setting up automated CI/CD pipelines for Godot exports.
12- Managing export templates, feature flags, and platform-specific configurations.
13- Optimizing build sizes and stripping debug symbols.
14- Implementing patching systems (PCK) or SteamPipe uploads.
15
16## Prerequisites
17- Godot 4.x installed (engine-accurate procedures apply to 4.7+).
18- Export templates installed via Editor → Manage Export Templates → Download.
19- Platform-specific SDKs:
20 - Android: Android SDK, OpenJDK 17, Debug keystore.
21 - iOS: macOS with Xcode, Apple Developer account, Provisioning profile.
22 - macOS: Developer ID certificate for codesigning.
23- Windows host is primary (PowerShell). Keep Windows path notes when present.
24
25## Procedure
26
27### 1. Basic Export Setup
281. Open Project → Export.
292. Add preset (Windows, Linux, etc.).
303. Configure settings (icon, binary format, etc.).
314. Export Project.
32
33### 2. Command-Line Export (Headless)
34Use PowerShell for command-line exports:
35```powershell
36# Export release build
37godot --headless --export-release "Windows Desktop" builds/game.exe
38
39# Export debug build
40godot --headless --export-debug "Windows Desktop" builds/game_debug.exe
41
42# PCK only (for patching)
43godot --headless --export-pack "Windows Desktop" builds/game.pck
44```
45
46### 3. Platform-Specific Settings
47- **Windows**: Format `.exe` (single file) or `.pck + .exe`. Icon: `.ico` file. Include: `*.import`, `*.tres`, `*.tscn`.
48- **Web**: Export Type: Regular or GDExtension. Thread Support: For SharedArrayBuffer. VRAM Compression: Optimized for size.
49- **Android**: Set SDK Path and Keystore in Editor Settings (Export → Android).
50- **iOS**: Export creates `.xcodeproj`. Build in Xcode for App Store.
51- **macOS**: Codesign: Developer ID certificate. Notarization: Required for distribution. Architecture: Universal (Intel + ARM).
52
53### 4. Feature Flags
54Check platform at runtime:
55```gdscript
56if OS.get_name() == "Windows":
57 # Windows-specific code
58 pass
59
60if OS.has_feature("web"):
61 # Web build
62 pass
63
64if OS.has_feature("mobile"):
65 # Android or iOS
66 pass
67```
68
69### 5. Build Optimization
70- **Reduce Build Size**: Exclude editor-only files in export preset (e.g., `*.md`, `*.txt`, `docs/*`). Remove unused imports.
71- **Strip Debug Symbols**: In export preset options, set Debugging → Debug: Off, Binary Format → Architecture: 64-bit only.
72- **VRAM Compression**: Enable ASTC/ETC2 compression in Import settings for Web/Mobile. ALWAYS disable compression for Pixel Art to maintain crisp edges.
73 - S3TC/BPTC: Mandatory for Desktop (Forward+). BPTC is superior for Normal Maps and HDR.
74 - ETC2: Standard for older Android/iOS devices.
75 - ASTC: Modern mobile standard. High quality/size ratio.
76
77### 6. Expert Export Patterns
78
79#### Platform-Specific-Patching (Delta Updates)
80Mount external PCK archives to update game content without a full reinstall.
81```gdscript
82func _load_patch(patch_path: String) -> bool:
83 if FileAccess.file_exists(patch_path):
84 return ProjectSettings.load_resource_pack(patch_path, true) # true = replace files
85 return false
86```
87
88#### Steam-Upload-Pipeline (SteamPipe)
89Automate distribution to Steam branches.
90```powershell
91# export_steam_upload.ps1
92$SteamCMD = "C:\steamcmd\steamcmd.exe"
93& $SteamCMD +login $env:STEAM_USER $env:STEAM_PASS +run_app_build "res://builds/app_build.vdf" +quit
94```
95
96#### Universal-Build-Manager (One-Click Export)
97Iterate through all export presets to generate a full suite of release binaries.
98```gdscript
99func export_all():
100 var config := ConfigFile.new()
101 config.load("res://export_presets.cfg")
102 for section in config.get_sections():
103 if section.begins_with("preset."):
104 var preset_name = config.get_value(section, "name")
105 var path = config.get_value(section, "export_path")
106 OS.execute(OS.get_executable_path(), ["--headless", "--export-release", preset_name, path])
107```
108
109### 7. Available Scripts (Load when implementing corresponding patterns)
110- **[export_headless_pipeline.ps1](scripts/export_headless_pipeline.ps1)**: Load before automating multi-platform headless exports.
111- **[export_version_sync.gd](scripts/export_version_sync.gd)**: Load to sync Git tags/hashes with 'application/config/version'.
112- **[export_post_process_hook.gd](scripts/export_post_process_hook.gd)**: Load when using `EditorExportPlugin` for post-build tasks (Zipping, Manifests).
113- **[export_feature_flag_manager.gd](scripts/export_feature_flag_manager.gd)**: Load for runtime behavior swapping via build feature flags.
114- **[export_pck_patch_loader.gd](scripts/export_pck_patch_loader.gd)**: Load for runtime patching logic (mounting external PCK archives and DLC).
115- **[export_android_signing_env.ps1](scripts/export_android_signing_env.ps1)**: Load for secure environment variable setup for Android release keystores.
116- **[export_custom_build_stripper.py](scripts/export_custom_build_stripper.py)**: Load for SCons configuration to strip unused Godot modules.
117- **[export_macos_notarize_cmd.ps1](scripts/export_macos_notarize_cmd.ps1)**: Load for macOS code signing and notarization CLI procedure.
118- **[export_build_size_report.gd](scripts/export_build_size_report.gd)**: Load to audit resource sizes and optimize build footprints.
119- **[export_ci_github_actions.yml](scripts/export_ci_github_actions.yml)**: Load for professional CI/CD workflow for automated multi-platform Godot releases.
120- **SteamPipe / SteamCMD**: Use the inline PowerShell in Steam-Upload-Pipeline (`steamcmd` + `+run_app_build` VDF). This folder has no dedicated SteamCMD wrapper file.
121- **[export_universal_manager.gd](scripts/export_universal_manager.gd)**: Load to programmatically iterate and export all defined presets in one click.
122
123## Pitfalls
124
125### Platform & Validation
126- **NEVER export to production without a 'Smoke Test'** — "It runs in editor" is NOT enough. Web, Mobile, and Console have unique memory/shader constraints.
127- **NEVER skip macOS Notarization** — Apple's Gatekeeper will block unsigned apps. Use `notarytool` OR distribute exclusively via Steam/App Store.
128- **NEVER use ad-hoc file paths** — `res://` is read-only in builds. Use `user://` for saves and logs, or paths will fail on locked file systems.
129
130### Performance & Size
131- **NEVER use 'Debug' templates for release** — Debug binaries are bloated and slow. Always use `--export-release` to strip profiling overhead.
132- **NEVER include raw resources in builds** — Check your export filters. If you include `.md`, `.txt`, or `.psd` files, you're wasting player bandwidth and disk space.
133- **NEVER ignore VRAM compression** — Large textures in Web/Mobile builds will crash the GPU driver. Enable ASTC/ETC2 compression in Import settings.
134
135### Security
136- **NEVER commit keystores or raw passwords to Git** — Use Environment Variables and CI Secrets (`export_android_signing_env.ps1`).
137- **NEVER allow debug commands in Production** — Use `OS.has_feature("release")` to purge console/cheats from the final build.
138- **NEVER bake shaders on export for Dedicated Servers** — The Shader Baker (Godot 4.5+) is for visual clients. Enabling it for headless servers is wasted build time.
139
140### Godot 4.7+ Specifics
141- `EditorSceneFormatImporter` constants moved to **ImportFlags** enum — update importer scripts.
142- **Asset Store** replaces Asset Library in editor — document addon acquisition via new store UI.
143- **HDR export**: verify viewport HDR settings per platform in export presets.
144
145## Verification
1461. **Check Export Output**: Verify the executable or PCK file exists in the specified `export_path`.
147 ```powershell
148 Test-Path "builds/game.exe"
149 ```
1502. **Verify Version Sync**: Ensure `application/config/version` in `project.godot` matches the Git tag.
1513. **Test Feature Flags**: Run the build and verify that `OS.has_feature("release")` correctly purges debug tools.
1524. **Check Build Size**: Use `export_build_size_report.gd` to ensure no raw resources (`.md`, `.txt`, `.psd`) are included.
1535. **macOS Notarization**: Run `export_macos_notarize_cmd.ps1` and verify the app passes Gatekeeper checks.
154
155## Related skills
156- Master Skill: [godot-master](../godot-master/SKILL.md)