Godot Setup Export

Overview

Automates multi-platform export configuration for Godot projects.

Setting up exports is tedious, error-prone, and requires platform-specific knowledge. This skill generates export presets, configures icons and splash screens, sets up feature tags, creates build scripts, and integrates with CI/CD pipelines.

When to Use

Use when:

• Creating exports for a new Godot project
• Adding support for new platforms (Windows, Mac, Linux, Web, Mobile)
• Setting up automated builds via GitHub Actions
• Configuring icons, splash screens, or feature tags
• Creating custom export build scripts
• Migrating from local exports to CI/CD

Don't use for:

• Debugging export failures (use godot-debug-exports instead)
• Platform-specific native code compilation
• One-off manual exports (use Godot editor)

Quick Reference

| Task | Tool/Method | |------|-------------| | Generate export presets | godot --headless --generate-export-presets | | Set icons | export_presets.cfg icon field | | Configure feature tags | project.godot [feature] sections | | Automated builds | GitHub Actions workflow | | Custom scripts | export_presets.cfg custom_template/release |

Core Pattern

Export Preset Generation

Windows Desktop:

[preset.0]
name="Windows Desktop"
platform="Windows Desktop"
export_filter="all_resources"
include_filter=""
export_files=[]
include_filter=""
export_path="builds/windows/Game.exe"
custom_features=""
export_filter="scenes"
export_files=PackedStringArray("res://main.tscn")
[preset.0.options]
custom_template/release=""
custom_template/debug=""

binary_format/architecture="x86_64"
codesign/enable=false
icon="res://assets/icons/windows_icon.ico"

macOS:

[preset.1]
name="macOS"
platform="macOS"
export_filter="all_resources"
export_path="builds/macos/Game.zip"
[preset.1.options]
binary_format/architecture="universal"
codesign/certificate_file=""
codesign/identity=""
icon="res://assets/icons/mac_icon.icns"
export/distribution_type=1

Linux:

[preset.2]
name="Linux"
platform="Linux"
export_filter="all_resources"
export_path="builds/linux/Game.x86_64"
[preset.2.options]
binary_format/architecture="x86_64"
custom_template/release=""
icon="res://assets/icons/linux_icon.png"

Web:

[preset.3]
name="Web"
platform="Web"
export_filter="all_resources"
export_path="builds/web/index.html"
[preset.3.options]
custom_template/release=""
custom_template/debug=""
variant/size_limit=16777216
vram_texture_compression/for_desktop=true
html/canvas_resize_policy=2
html/experimental_virtual_keyboard=false
progressive_web_app/enabled=false

Android:

[preset.4]
name="Android"
platform="Android"
export_filter="all_resources"
export_path="builds/android/Game.apk"
[preset.4.options]
gradle_build/use_gradle_build=false
gradle_build/export_format=0
gradle_build/min_sdk=21
gradle_build/target_sdk=33
version/code=1
version/name="1.0"
architectures/armeabi-v7a=false
architectures/arm64-v8a=true
architectures/x86=false
architectures/x86_64=false
keystore/debug=""
keystore/debug_user=""
keystore/debug_password=""
keystore/release=""
keystore/release_user=""
keystore/release_password=""
icon/export_identifier="com.example.game"

iOS:

[preset.5]
name="iOS"
platform="iOS"
export_filter="all_resources"
export_path="builds/ios/Game.xcodeproj"
[preset.5.options]
binary_format/architecture=1
application/app_store_team_id=""
application/bundle_identifier="com.example.game"
application/short_version="1.0"
application/version="1.0"
application/icon_interpolation=4
application/export_method_release=0
application/targeted_device_family=2
application/remove_simulator_arch=true
codesign/codesign=1
codesign/identity=""
codesign/provisioning_profile=""

Icon and Splash Screen Setup

Icon Requirements by Platform

| Platform | Format | Size | Notes | |----------|--------|------|-------| | Windows | .ico | 256x256 | Multi-resolution ICO file | | macOS | .icns | 1024x1024 | Apple icon format | | Linux | .png | 256x256 | Standard PNG | | Web | .png | 512x512 | Used for favicon/PWA | | Android | .png | 512x512 | Adaptive icons supported | | iOS | .png | 1024x1024 | App Store icon |

Project Configuration

project.godot:

[application]
config/name="Game Name"
config/description="Game description"
run/main_scene="res://scenes/main.tscn"
config/features=PackedStringArray("4.2", "Mobile")
boot_splash/bg_color=Color(0.14, 0.14, 0.14, 1)
boot_splash/image="res://assets/splash/splash_screen.png"
boot_splash/fullsize=true
boot_splash/use_filter=true

[display]
window/size/viewport_width=1920
window/size/viewport_height=1080
window/stretch/mode="canvas_items"
window/stretch/aspect="expand"

Feature Tags Configuration

Use feature tags for platform-specific behavior:

[feature_tags]
editor=false
standalone=true
debug=false
release=true

; Platform-specific features
windows=false
macos=false
linux=false
android=false
ios=false
web=false
mobile=false
desktop=false

In GDScript:

# Platform-specific code
if OS.has_feature("mobile"):
    # Mobile touch controls
    touch_controls.visible = true
elif OS.has_feature("desktop"):
    # Desktop keyboard/mouse
    touch_controls.visible = false

# Debug vs release
if OS.has_feature("debug"):
    show_debug_info()
    enable_cheats()

Custom Build Scripts

Windows Batch Script

@echo off
set PROJECT_PATH=%~dp0
set GODOT_PATH="C:\Program Files\Godot\Godot_v4.x.exe"
set BUILD_DIR=%PROJECT_PATH%builds\windows

if not exist %BUILD_DIR% mkdir %BUILD_DIR%

%GODOT_PATH% --headless --path %PROJECT_PATH% --export-release "Windows Desktop" "%BUILD_DIR%\Game.exe"

if %ERRORLEVEL% NEQ 0 (
    echo Export failed!
    exit /b 1
)

echo Export complete: %BUILD_DIR%\Game.exe

Linux/macOS Shell Script

#!/bin/bash
set -e

PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
GODOT_PATH="/usr/bin/godot"
BUILD_DIR="$PROJECT_DIR/builds"

mkdir -p "$BUILD_DIR/linux" "$BUILD_DIR/macos" "$BUILD_DIR/web"

# Linux
$GODOT_PATH --headless --path "$PROJECT_DIR" \
    --export-release "Linux" "$BUILD_DIR/linux/Game.x86_64"

# macOS  
$GODOT_PATH --headless --path "$PROJECT_DIR" \
    --export-release "macOS" "$BUILD_DIR/macos/Game.zip"

# Web
$GODOT_PATH --headless --path "$PROJECT_DIR" \
    --export-release "Web" "$BUILD_DIR/web/index.html"

echo "All exports complete!"

PowerShell Script

$ProjectPath = $PSScriptRoot
$GodotPath = "C:\Program Files\Godot\Godot_v4.x.exe"
$BuildDir = Join-Path $ProjectPath "builds"

New-Item -ItemType Directory -Force -Path $BuildDir | Out-Null

$Presets = @(
    @{ Name = "Windows Desktop"; Path = "$BuildDir\windows\Game.exe" },
    @{ Name = "Linux"; Path = "$BuildDir\linux\Game.x86_64" }
)

foreach ($Preset in $Presets) {
    $Dir = Split-Path $Preset.Path -Parent
    New-Item -ItemType Directory -Force -Path $Dir | Out-Null
    
    & $GodotPath --headless --path $ProjectPath `
        --export-release $Preset.Name $Preset.Path
    
    if ($LASTEXITCODE -ne 0) {
        Write-Error "Export failed for $($Preset.Name)"
        exit 1
    }
}

Write-Host "Exports complete!"

CI/CD Integration

GitHub Actions Workflow

name: Build and Export

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
    branches: [main]

env:
  GODOT_VERSION: 4.2.1
  EXPORT_NAME: game-name

jobs:
  export-windows:
    name: Windows Export
    runs-on: ubuntu-22.04
    container:
      image: barichello/godot-ci:4.2.1
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Godot
        run: |
          mkdir -p ~/.config/godot/
          echo "[export_presets]" > ~/.config/godot/editor_settings-4.tres
          
      - name: Windows Build
        run: |
          mkdir -p build/windows
          godot --headless --verbose --export-release "Windows Desktop" ./build/windows/$EXPORT_NAME.exe
          
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: windows
          path: build/windows

  export-linux:
    name: Linux Export
    runs-on: ubuntu-22.04
    container:
      image: barichello/godot-ci:4.2.1
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Linux Build
        run: |
          mkdir -p build/linux
          godot --headless --verbose --export-release "Linux" ./build/linux/$EXPORT_NAME.x86_64
          
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: linux
          path: build/linux

  export-web:
    name: Web Export
    runs-on: ubuntu-22.04
    container:
      image: barichello/godot-ci:4.2.1
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Web Build
        run: |
          mkdir -p build/web
          godot --headless --verbose --export-release "Web" ./build/web/index.html
          
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: web
          path: build/web
          
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/web

  export-android:
    name: Android Export
    runs-on: ubuntu-22.04
    container:
      image: barichello/godot-ci:4.2.1
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Android SDK
        run: |
          mkdir -p ~/.config/godot/
          echo "[export_presets]" > ~/.config/godot/editor_settings-4.tres
          
      - name: Android Build
        run: |
          mkdir -p build/android
          godot --headless --verbose --export-release "Android" ./build/android/$EXPORT_NAME.apk
          
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: android
          path: build/android

  export-macos:
    name: macOS Export
    runs-on: ubuntu-22.04
    container:
      image: barichello/godot-ci:4.2.1
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: macOS Build
        run: |
          mkdir -p build/macos
          godot --headless --verbose --export-release "macOS" ./build/macos/$EXPORT_NAME.zip
          
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: macos
          path: build/macos

  create-release:
    name: Create Release
    needs: [export-windows, export-linux, export-web, export-android, export-macos]
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/v')
    steps:
      - name: Download All Artifacts
        uses: actions/download-artifact@v4
        
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            windows/*.exe
            linux/*
            android/*.apk
            macos/*.zip
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Common Mistakes

| Mistake | Solution | |---------|----------| | Missing export presets file | Run Godot editor once to generate or copy template | | Wrong export path format | Use forward slashes on all platforms | | Icons not loading | Ensure icon files exist at specified paths | | Android keystore errors | Set up debug keystore or configure release keystore | | Web export fails | Check export template is installed | | CI/CD can't find Godot | Use godot-ci Docker image or install Godot manually |

Examples

Before: Manual Export (❌)

# Manual export via Godot editor
# 1. Open Project > Export
# 2. Click Add for each platform
# 3. Configure each preset manually
# 4. Click Export Project for each
# 5. Repeat every time you want to build

After: Automated Setup (✅)

# export_presets.cfg - generated once, committed to repo
[preset.0]
name="Windows Desktop"
export_path="builds/windows/Game.exe"
...

[preset.1]
name="macOS"
export_path="builds/macos/Game.zip"
...

[preset.2]
name="Linux"
export_path="builds/linux/Game.x86_64"
...

[preset.3]
name="Web"
export_path="builds/web/index.html"
...

# Then run: ./build.sh or let GitHub Actions handle it automatically

Complete Project Structure

my-game/
├── project.godot
├── export_presets.cfg          # All export configurations
├── .github/
│   └── workflows/
│       └── export.yml          # CI/CD pipeline
├── assets/
│   └── icons/
│       ├── windows_icon.ico
│       ├── mac_icon.icns
│       ├── linux_icon.png
│       ├── android_icon.png
│       └── ios_icon.png
├── scripts/
│   └── build.sh                # Local build script
└── builds/                     # Output directory (gitignored)
    ├── windows/
    ├── macos/
    ├── linux/
    ├── web/
    └── android/

Export Command Reference

# Export release build
godot --headless --export-release "Preset Name" "output/path"

# Export debug build
godot --headless --export-debug "Preset Name" "output/path"

# Export with pack file only (no executable)
godot --headless --export-pack "Preset Name" "output.pck"

# Export from specific project path
godot --headless --path /path/to/project --export-release "Preset" "output"

# Verbose output for debugging
godot --headless --verbose --export-release "Preset" "output"

Platform-Specific Notes

Windows

• Requires export template: windows_x86_64.exe
• Icon must be .ico format with multiple resolutions
• Codesigning optional but recommended for distribution

macOS

• Requires export template: macos.zip
• App Store requires specific provisioning profile
• Notarization required for distribution outside App Store

Linux

• Most straightforward export
• Single executable file
• No special requirements

Web

• Requires export template: web.zip
• SharedArrayBuffer required for threads
• May need custom HTML template for fullscreen

Android

• Requires Android SDK and export templates
• Keystore required for release builds
• Debug keystore auto-generated if not specified

iOS

• Requires macOS and Xcode
• Must export to Xcode project, then build
• Apple Developer account required

Version Control

Commit to repo:

• export_presets.cfg - Contains all export configurations
• .github/workflows/export.yml - CI/CD pipeline
• Build scripts (build.sh, build.bat, build.ps1)

Add to .gitignore:

builds/
*.tmp
*.import

Troubleshooting

"Export preset not found"

• Ensure preset name matches exactly (case-sensitive)
• Check export_presets.cfg exists in project root
• Verify preset is configured in Godot editor

"Export template not found"

• Install export templates: Editor > Manage Export Templates
• For CI/CD, use godot-ci Docker image with templates included

"Cannot open file for writing"

• Ensure output directory exists
• Check write permissions
• Use absolute paths in CI/CD environments

Android build fails

• Verify ANDROID_HOME environment variable
• Check keystore configuration
• Ensure minimum SDK version matches template

Web export blank

• Check browser console for errors
• Verify SharedArrayBuffer headers if using threads
• Try disabling threads in export options

Real-World Impact

• Setup time: 2 hours → 10 minutes
• Build consistency: Manual errors eliminated
• Release cadence: Days → Hours
• Multi-platform: Set up once, build anywhere