godot-export-builds

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-export-builds

Automates multi-platform Godot exports with CI/CD and build optimization.

  • Solves platform-specific export configuration and release preparation.
  • Depends on Godot export templates, Android SDK, and codesigning tools.
  • Uses feature flags and platform presets to select correct export settings.
  • Delivers optimized builds via command-line exports or CI pipeline integration.

SKILL.md

.github/skills/godot-export-buildsView on GitHub ↗
---
name: godot-export-builds
description: "Expert patterns for multi-platform exports including export templates (Windows/Linux/macOS/Android/iOS/Web), command-line exports (headless mode), platform-specific settings (codesign, notarization, Android SDK), feature flags (OS.has_feature), CI/CD pipelines (GitHub Actions), and build optimization (size reduction, debug stripping). Use for release preparation or automated deployment. Trigger keywords: export_preset, export_template, headless_export, platform_specific, feature_flag, CI_CD, build_optimization, codesign, Android_SDK."
---

# Export & Builds

Headless / CI / platform release plumbing — not Editor → Export click-path tutorials.

## NEVER Do (Expert Export Rules)

### Platform & Validation
- **NEVER export to production without a smoke test** — Editor play ≠ Web/Mobile/Console constraints.
- **NEVER skip macOS notarization** for direct distribution — Gatekeeper blocks unsigned apps (Steam/App Store distribution can substitute).
- **NEVER use ad-hoc writable `res://` paths in builds** — Saves/logs go to `user://`.

### Performance & Size
- **NEVER ship Debug templates as release** — Use `--export-release`.
- **NEVER include raw authoring junk** — Filter `.md` / `.psd` / docs out of presets.
- **NEVER ignore VRAM compression on Web/Mobile** — Enable ASTC/ETC2 (keep pixel art uncompressed).

### Security
- **NEVER commit keystores or passwords** — Env vars + [export_android_signing_env.ps1](scripts/export_android_signing_env.ps1).
- **NEVER leave debug cheats in release** — Gate with `OS.has_feature("release")`.
- **NEVER enable Shader Baker on dedicated server exports** — Wasted build time; baker is for visual clients.

---

## Godot 4.7: Import & Export

- `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.

## Platform Decision Tree

| Target | MANDATORY scripts / actions | Do NOT Load |
|--------|----------------------------|-------------|
| Desktop smoke (Win/Linux) | [export_headless_pipeline.ps1](scripts/export_headless_pipeline.ps1) or [headless_build.sh](scripts/headless_build.sh) | Manual Export UI tutorials |
| Web smoke | Headless web preset + size report | Desktop-only compression assumptions |
| Android release | [export_android_signing_env.ps1](scripts/export_android_signing_env.ps1) | Committed keystores |
| macOS direct distribute | [export_macos_notarize_cmd.ps1](scripts/export_macos_notarize_cmd.ps1) | Skipping notarize "because Steam exists" when not on Steam |
| Dedicated server | Headless server preset, baker off | Client shader baker / UI feature packs |
| CI multi-platform | [export_ci_github_actions.yml](scripts/export_ci_github_actions.yml) (**Godot 4.7** images) | Stale 4.2.x container pins |
| Steam depot upload | [export_steam_upload.ps1](scripts/export_steam_upload.ps1) | — if not shipping on Steam |
| PCK / DLC patches | [export_pck_patch_loader.gd](scripts/export_pck_patch_loader.gd) | — if no DLC |
| One-click all presets | [export_universal_manager.gd](scripts/export_universal_manager.gd) | — |
| Version sync | [export_version_sync.gd](scripts/export_version_sync.gd) / [version_manager.gd](scripts/version_manager.gd) | Hardcoded version labels in UI only |
| Feature stripping | [export_feature_flag_manager.gd](scripts/export_feature_flag_manager.gd) | — |
| Size audit | [export_build_size_report.gd](scripts/export_build_size_report.gd) | — |
| Custom engine strip | [export_custom_build_stripper.py](scripts/export_custom_build_stripper.py) | — unless custom builds |
| Post-export zip/manifest | [export_post_process_hook.gd](scripts/export_post_process_hook.gd) | — |

**Editor Export UI / template download prose:** use Official Documentation links in Reference — or [export-setup-guide.md](references/export-setup-guide.md) for INI/CLI/platform checklists.

## Available Scripts

> **MANDATORY**: Read the script that matches the platform decision above before implementing.

- [export_headless_pipeline.ps1](scripts/export_headless_pipeline.ps1)
- [headless_build.sh](scripts/headless_build.sh)
- [export_version_sync.gd](scripts/export_version_sync.gd) / [version_manager.gd](scripts/version_manager.gd)
- [export_post_process_hook.gd](scripts/export_post_process_hook.gd)
- [export_feature_flag_manager.gd](scripts/export_feature_flag_manager.gd)
- [export_pck_patch_loader.gd](scripts/export_pck_patch_loader.gd)
- [export_android_signing_env.ps1](scripts/export_android_signing_env.ps1)
- [export_custom_build_stripper.py](scripts/export_custom_build_stripper.py)
- [export_macos_notarize_cmd.ps1](scripts/export_macos_notarize_cmd.ps1)
- [export_build_size_report.gd](scripts/export_build_size_report.gd)
- [export_ci_github_actions.yml](scripts/export_ci_github_actions.yml) — pin **4.7** templates/executable
- [export_steam_upload.ps1](scripts/export_steam_upload.ps1) — SteamPipe via `steamcmd` + VDF
- [export_universal_manager.gd](scripts/export_universal_manager.gd)

## CI Contract (4.7)

Workflows must pull **Godot 4.7** editor + export templates (not 4.2.x). Prefer the checked-in [export_ci_github_actions.yml](scripts/export_ci_github_actions.yml) over pasted legacy YAML. Artifacts upload with `actions/upload-artifact@v4`.

## Expert Export Patterns

### 1. Platform-Specific Patching (Delta Updates)
Mount external PCKs with `ProjectSettings.load_resource_pack(path, true)` — same-path resources override base. See [export_pck_patch_loader.gd](scripts/export_pck_patch_loader.gd).

### 2. VRAM Compression Audit
- Desktop Forward+: S3TC/BPTC
- Mobile: ETC2 / ASTC
- Pixel art: compression off

### 3. SteamPipe Upload
Build locally/CI → [export_steam_upload.ps1](scripts/export_steam_upload.ps1) with `STEAM_USER` / `STEAM_PASS` / `STEAMCMD_PATH` env vars and an `app_build.vdf`.

### 4. Universal Build Manager
Iterate presets from `export_presets.cfg` via [export_universal_manager.gd](scripts/export_universal_manager.gd) for one-click multi-platform consistency.

## Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

### Official Documentation
- [Exporting (tutorial index)](https://docs.godotengine.org/en/stable/tutorials/export/index.html) — Entry map for presets, templates, platform guides, feature tags, and PCK workflows before platform deep-dives.
- [Exporting projects](https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html) — Export presets, template install, include/exclude filters, and release vs debug template choice.
- [Feature tags](https://docs.godotengine.org/en/stable/tutorials/export/feature_tags.html) — `OS.has_feature` / custom tags that drive runtime stripping of debug tools and platform forks.
- [Command line tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html) — `--headless`, `--export-release`, `--export-debug`, and `--export-pack` for CI and scripted pipelines.
- [Exporting packs, patches, and mods](https://docs.godotengine.org/en/stable/tutorials/export/exporting_pcks.html) — PCK/DLC mounting with `ProjectSettings.load_resource_pack` for delta updates.
- [Exporting for Android](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_android.html) — SDK, keystore, and signing env expectations for store and CI Android builds.
- [Exporting for macOS](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_macos.html) — Codesign, notarization, and universal binary options required for Gatekeeper distribution.
- [Exporting for Web](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html) — Threading/SharedArrayBuffer, VRAM compression, and HTML5 shell constraints for web smoke tests.
- [Exporting for dedicated servers](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_dedicated_servers.html) — Headless server templates and why client-only bake steps (e.g. shader baker) waste server builds.
- [EditorExportPlugin](https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html) — Hook API for post-export zip/manifest steps shared across team export presets.
- [Optimizing for size](https://docs.godotengine.org/en/stable/engine_details/development/compiling/optimizing_for_size.html) — SCons module stripping and size flags when custom templates must beat stock binary weight.
- [Data paths](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html) — `res://` vs `user://` so exported builds do not write into read-only packed paths.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Project layout, `project.godot` version/icon settings, and import defaults must be sane before export presets and filters.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — `EditorScript` / plugin typing and `OS.execute` patterns used by version sync, universal export, and post-process hooks.

#### Complements
- [godot-platform-desktop](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-platform-desktop/SKILL.md) — Windows/Linux/macOS runtime quirks (icons, windowing, Steam) that export presets must match.
- [godot-platform-mobile](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-platform-mobile/SKILL.md) — Android/iOS permission, orientation, and input assumptions that belong in mobile export options.
- [godot-platform-web](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-platform-web/SKILL.md) — Web host constraints (CORS, threads, memory) that decide Web export type and smoke-test matrix.
- [godot-platform-console](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-platform-console/SKILL.md) — Console certification packaging flows that extend beyond desktop/mobile export templates.
- [godot-adapt-desktop-to-mobile](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-adapt-desktop-to-mobile/SKILL.md) — Touch/UI/safe-area adaptations that must ship in mobile feature-tagged builds, not desktop-only assets.
- [godot-debugging-profiling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-debugging-profiling/SKILL.md) — Profile export vs editor differences (shader compile, memory) before blaming preset filters.
- [godot-testing-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-testing-patterns/SKILL.md) — Automated smoke tests against headless/CI artifacts so “runs in editor” never ships alone.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — Persist under `user://`; export filters must not strip save schemas players need after install.
- [godot-resource-data-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-resource-data-patterns/SKILL.md) — Resource packing and `.gdignore` hygiene that directly shrinks export footprint.

#### Downstream / consumers
- [godot-performance-optimization](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-performance-optimization/SKILL.md) — Escalate when release builds still fail budgets after filters, VRAM compression, and template choice.
- [godot-server-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-server-architecture/SKILL.md) — Consumes dedicated-server export presets and headless pipelines for authoritative hosts.
- [godot-multiplayer-networking](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-multiplayer-networking/SKILL.md) — Client/server binary pairs and feature tags for dedicated vs listen-server packaging.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting export or platform concern.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.