Export & Builds

Expert guidance for building and distributing Godot games across platforms.

NEVER Do

• NEVER export without testing on target platform first — "Works on my machine" doesn't mean it works on Windows/Linux/Android. Test early and often.
• NEVER use debug builds for release — Debug builds are 5-10x larger and slower. Always export with --export-release for production.
• NEVER hardcode file paths in exports — Use res:// and user:// paths. Absolute paths (C:/Users/...) break on other machines.
• NEVER skip code signing on macOS — Unsigned macOS apps trigger Gatekeeper warnings. Users won't run your game.
• NEVER include editor-only files in exports — Exclude .md, docs/*, .git via export filters. Reduces build size by 20-50%.

---

Available Scripts

MANDATORY: Read the appropriate script before implementing the corresponding pattern.

version_manager.gd

AutoLoad for managing game version, build hash, and window titles.

headless_build.sh

CI/CD headless export script. Automates version injection, godot --headless --export-release, code signing, and butler deployment.

---

Export Templates

Install via Editor: Editor → Manage Export Templates → Download

Basic Export Setup

Create Export Preset

1. Project → Export
2. Add preset (Windows, Linux, etc.)
3. Configure settings
4. Export Project

Windows Export

# Export settings
# Format: .exe (single file) or .pck + .exe
# Icon: .ico file
# Include: *.import, *.tres, *.tscn

Web Export

# Settings:
# Export Type: Regular or GDExtension
# Thread Support: For SharedArrayBuffer
# VRAM Compression: Optimized for size

Export Presets File

# export_presets.cfg

[preset.0]
name="Windows Desktop"
platform="Windows Desktop"
runnable=true
export_path="builds/windows/game.exe"

[preset.0.options]
binary_format/64_bits=true
application/icon="res://icon.ico"

Command-Line Export

# Export from command line
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

Platform-Specific

Android

# Requirements:
# - Android SDK
# - OpenJDK 17
# - Debug keystore

# Editor Settings:
# Export → Android → SDK Path
# Export → Android → Keystore

iOS

# Requirements:
# - macOS with Xcode
# - Apple Developer account
# - Provisioning profile

# Export creates .xcodeproj
# Build in Xcode for App Store

macOS

# Settings:
# Codesign: Developer ID certificate
# Notarization: Required for distribution
# Architecture: Universal (Intel + ARM)

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

Project Settings for Export

# project.godot

[application]
config/name="My Game"
config/version="1.0.0"
run/main_scene="res://scenes/main.tscn"
config/icon="res://icon.svg"

[rendering]
# Optimize for target platforms
textures/vram_compression/import_etc2_astc=true  # Mobile

Build Optimization

Reduce Build Size

# Remove unused imports
# Project Settings → Editor → Import Defaults

# Exclude editor-only files
# In export preset: Exclude filters
*.md
*.txt
docs/*

Strip Debug Symbols

# Export preset options:
# Debugging → Debug: Off
# Binary Format → Architecture: 64-bit only

CI/CD with GitHub Actions

# .github/workflows/export.yml
name: Export Godot Game

on:
  push:
    tags: ['v*']

jobs:
  export:
    runs-on: ubuntu-latest
    container:
      image: barichello/godot-ci:4.2.1
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Export Windows
        run: |
          mkdir -p builds/windows
          godot --headless --export-release "Windows Desktop" builds/windows/game.exe
      
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: windows-build
          path: builds/windows/

Version Management

# version.gd (AutoLoad)
extends Node

const VERSION := "1.0.0"
const BUILD := "2024.02.06"

func get_version_string() -> String:
    return "v" + VERSION + " (" + BUILD + ")"

Best Practices

1. Test Export Early

Export to all target platforms early
Catch platform-specific issues fast

2. Use .gdignore

# Exclude folders from export
# Create .gdignore in folder

3. Separate Debug/Release

Debug: Keep logs, dev tools
Release: Strip debug, optimize size

Reference

• Godot Docs: Exporting

Related

• Master Skill: godot-master