From godot-prompter
Configures export presets, platform settings, and CI/CD pipelines with GitHub Actions for distributing Godot 4.3+ games using GDScript or C#.
npx claudepluginhub jame581/godotprompter --plugin godot-prompterThis skill uses the workspace's default tool permissions.
All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, C# follows where applicable.
Runs Godot export, CI, and release packaging with reproducible presets and platform-aware checks. Use for shipping builds, stabilizing presets, or resolving platform issues.
Develop, test, build, and deploy Godot 4.x games. Includes GdUnit4 for GDScript unit tests and PlayGodot for game automation and E2E testing. Supports web/desktop exports, CI/CD pipelines, and deployment to Vercel/GitHub Pages/itch.io.
Provides specialized guidance for Godot Engine projects: .gd, .tscn, .tres file formats, component-based patterns, signals, resources, debugging, validation tools, templates, and CLI workflows.
Share bugs, ideas, or general feedback.
All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, C# follows where applicable.
Related skills: godot-testing for CI/CD test integration, godot-optimization for pre-export performance checks, responsive-ui for platform-specific resolution settings.
Open Project → Export, click Add…, and select the target platform. Each preset maps to one entry in export_presets.cfg. You can create multiple presets for the same platform (e.g., a debug build and a release build for Windows).
Required one-time setup per platform:
Godot writes export_presets.cfg to the project root. Commit this file — it is safe and contains no secrets. Secrets (codesigning passwords, keystore passwords) must never be committed; use environment variables instead.
Example preset structure (Windows release):
[preset.0]
name="Windows Desktop"
platform="Windows Desktop"
runnable=true
dedicated_server=false
custom_features=""
export_filter="all_resources"
include_filter=""
exclude_filter=""
export_path="build/windows/MyGame.exe"
encryption_include_filters=""
encryption_exclude_filters=""
encrypt_pck=false
encrypt_directory=false
[preset.0.options]
custom_template/debug=""
custom_template/release=""
debug/export_console_wrapper=1
binary_format/embed_pck=true
texture_format/s3tc_bptc=true
texture_format/etc2_astc=false
binary_format/architecture="x86_64"
codesign/enable=false
codesign/identity=""
codesign/password=""
codesign/timestamp=true
codesign/timestamp_server_url=""
codesign/digest_algorithm=1
codesign/description=""
codesign/custom_options=PackedStringArray()
application/icon=""
application/console_wrapper_icon=""
application/icon_interpolation=4
application/file_version=""
application/product_version=""
application/company_name=""
application/product_name=""
application/file_description=""
application/copyright=""
application/trademarks=""
application/export_angle=0
application/export_d3d12=0
application/d3d12_agility_sdk_multiarch=true
ssh_remote_deploy/enabled=false
ssh_remote_deploy/host="user@host_ip"
ssh_remote_deploy/port="22"
ssh_remote_deploy/extra_args_ssh=""
ssh_remote_deploy/extra_args_scp=""
ssh_remote_deploy/run_script="#!/usr/bin/env bash\nexport DISPLAY=:0\n\"{temp_dir}/{exe_name}\" {cmd_args}"
ssh_remote_deploy/cleanup_script="#!/usr/bin/env bash\nkill $(pgrep -x -f \"{temp_dir}/{exe_name} {cmd_args}\")\nrm -rf \"{temp_dir}\""
Godot regenerates
export_presets.cfgon every editor save. Do not hand-edit it while the editor is open.
| Platform | Key Setting / Consideration |
|---|---|
| Windows | Set application/icon (.ico file). Codesigning requires a .pfx certificate; set codesign/enable=true and supply codesign/identity + codesign/password via env vars. Without codesigning, Windows SmartScreen will warn users. |
| Linux | No codesigning required. After export, run chmod +x MyGame.x86_64 on the binary. Ship as a tarball or AppImage for distribution. |
| macOS | Requires notarization for Gatekeeper to allow launch without warning. Set codesign/enable=true and notarization/enable=true. Provide the codesign/identity (Apple Developer ID). The Info.plist entries (bundle ID, version, display name, privacy usage descriptions) are set under application/* options in the preset. Notarization is done post-export via xcrun notarytool. |
| Web | Requires SharedArrayBuffer for multi-threading — the web server must send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers. Disable threads (rendering/threads/thread_model=0) if hosting on a server you cannot configure. Exported output is a .html + .js + .wasm + .pck bundle. |
| Android | Requires a keystore for release signing. Set keystore/release to the .keystore path and supply keystore/release_user + keystore/release_password via env vars. Declare permissions in the preset under permissions/*. Set package/unique_name to a reverse-DNS string (e.g., com.studio.mygame). |
| iOS | Requires a valid Apple provisioning profile (.mobileprovision). Set application/bundle_identifier, codesign/identity, and application/provisioning_profile. Distribution builds require an App Store distribution certificate. |
Run Godot in headless mode to export without opening the GUI. This is the standard approach for CI/CD.
godot --headless --export-release "Windows Desktop" build/windows/MyGame.exe
godot --headless --export-debug "Windows Desktop" build/windows/MyGame.exe
Use --export-pack when you only want to ship updated game data alongside a fixed engine binary (e.g., DLC or patch distribution):
godot --headless --export-pack "Windows Desktop" build/windows/MyGame.pck
| Flag | Purpose |
|---|---|
--headless | No display server; required for server/CI environments |
--export-release "Preset Name" path | Export using release template |
--export-debug "Preset Name" path | Export using debug template |
--export-pack "Preset Name" path | Export .pck resource pack only |
--quit-after N | Quit after N milliseconds (rarely needed for export) |
The preset name in the CLI flag must match
name=inexport_presets.cfgexactly, including capitalisation and spaces.
Full workflow exporting Windows (.exe), Linux (.x86_64), and Web (.html) builds on every push to main and on tagged releases.
# .github/workflows/export.yml
name: Export Godot Game
on:
push:
branches: [main]
release:
types: [published]
env:
GODOT_VERSION: "4.3"
EXPORT_NAME: "MyGame"
jobs:
export:
name: Export — ${{ matrix.preset }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
- preset: "Windows Desktop"
artifact: windows
output_path: build/windows/MyGame.exe
- preset: "Linux/X11"
artifact: linux
output_path: build/linux/MyGame.x86_64
- preset: "Web"
artifact: web
output_path: build/web/index.html
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # needed for git describe (versioning)
- name: Set up Godot ${{ env.GODOT_VERSION }}
uses: chickensoft-games/setup-godot@v2
with:
version: ${{ env.GODOT_VERSION }}
use-dotnet: false # set true for C# projects
include-templates: true
- name: Create output directory
run: mkdir -p $(dirname ${{ matrix.output_path }})
- name: Inject version from git tag
run: |
VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "0.0.0-dev")
echo "GAME_VERSION=$VERSION" >> $GITHUB_ENV
# Patch project.godot so ProjectSettings.get_setting("application/config/version") returns it
sed -i "s/^config\/version=.*/config\/version=\"$VERSION\"/" project.godot || true
- name: Export — ${{ matrix.preset }}
run: |
godot --headless --export-release "${{ matrix.preset }}" "${{ matrix.output_path }}"
- name: Mark Linux binary executable
if: matrix.artifact == 'linux'
run: chmod +x ${{ matrix.output_path }}
- name: Upload artifact — ${{ matrix.artifact }}
uses: actions/upload-artifact@v4
with:
name: ${{ env.EXPORT_NAME }}-${{ matrix.artifact }}-${{ env.GAME_VERSION }}
path: build/${{ matrix.artifact }}/
if-no-files-found: error
For C# (Mono) projects set
use-dotnet: truein thesetup-godotstep. The action will install the .NET SDK automatically.
Store the version string in Project → Project Settings → Application → Config → Version. Then read it anywhere:
# version_label.gd
extends Label
func _ready() -> void:
text = "v" + ProjectSettings.get_setting("application/config/version", "dev")
// VersionLabel.cs
using Godot;
public partial class VersionLabel : Label
{
public override void _Ready()
{
Text = "v" + ProjectSettings.GetSetting("application/config/version", "dev").AsString();
}
}
Tag your release commit, then inject the version at export time. The CI workflow above does this via sed, but you can also run a pre-export GDScript tool (EditorScript) if you prefer to keep it in-engine:
# tools/inject_version.gd — run with: godot --headless --script tools/inject_version.gd
@tool
extends EditorScript
func _run() -> void:
var git_output: Array = []
var exit_code := OS.execute("git", ["describe", "--tags", "--always", "--dirty"], git_output)
if exit_code != 0:
push_error("inject_version: git describe failed")
return
var version: String = (git_output[0] as String).strip_edges()
ProjectSettings.set_setting("application/config/version", version)
var err := ProjectSettings.save()
if err != OK:
push_error("inject_version: failed to save project.godot — error %d" % err)
else:
print("inject_version: set version to '%s'" % version)
Run it as part of a CI step before the export step:
godot --headless --script tools/inject_version.gd
godot --headless --export-release "Windows Desktop" build/windows/MyGame.exe
Use Semantic Versioning tags: v1.2.3. git describe then produces v1.2.3-4-gabcdef for commits after a tag, giving you fully traceable builds.
Butler is the official itch.io CLI for pushing builds.
# Linux/macOS
curl -L https://broth.itch.ovh/butler/linux-amd64/LATEST/archive/default -o butler.zip
unzip butler.zip
chmod +x butler
# Or install via GitHub Actions:
# uses: Ayowel/butler-to-itch@v1
butler push build/windows/ my-studio/my-game:windows
butler push build/linux/ my-studio/my-game:linux
butler push build/web/ my-studio/my-game:web
| Channel name | Platform |
|---|---|
windows | Windows 64-bit |
linux | Linux 64-bit |
macos | macOS universal |
web | HTML5 / WebGL |
android | Android APK/AAB |
Use --userversion to tag the build with your version string:
butler push build/windows/ my-studio/my-game:windows --userversion "$GAME_VERSION"
Add this job after the export job to push all artifacts to itch.io:
deploy-itch:
name: Deploy to itch.io
needs: export
runs-on: ubuntu-latest
if: github.event_name == 'release'
steps:
- name: Download all build artifacts
uses: actions/download-artifact@v4
with:
path: artifacts/
- name: Push to itch.io
uses: Ayowel/butler-to-itch@v1
with:
butler_key: ${{ secrets.BUTLER_API_KEY }}
itch_user: my-studio
itch_game: my-game
version: ${{ github.ref_name }}
files: |
windows:artifacts/${{ env.EXPORT_NAME }}-windows-*/
linux:artifacts/${{ env.EXPORT_NAME }}-linux-*/
web:artifacts/${{ env.EXPORT_NAME }}-web-*/
Store your butler API key (from https://itch.io/user/settings/api-keys) as a GitHub Actions secret named BUTLER_API_KEY.
For Steam distribution you need three components working together:
Steam.init(), achievements, stats, UGC, and networking. Install it as a Godot plugin; follow the GodotSteam docs for the exact version matching your Godot and Steamworks SDK versions.steamcmd CLI uploads depots to Steam using app_build scripts. Builds are staged in a local content/ folder and pushed with steamcmd +run_app_build app_build.vdf.Steam integration is outside the scope of the export pipeline itself — refer to the GodotSteam documentation and Steamworks SDK guides for full setup.
Godot 4.5 introduces the Shader Baker, an export-time tool that pre-compiles shaders for the target platform. Without it, shaders compile at runtime on first use, causing visible hitches when new materials are first rendered in-game. The Shader Baker eliminates this stutter by doing the work at export time.
In Project → Export, open a preset and locate the Shader Baker section. Enable it and configure target backends (Vulkan, D3D12, Metal, GLES3) as needed.
The Shader Baker increases export build time but has no effect on game download size or runtime memory. The pre-compiled cache is embedded in the
.pckfile.
| Platform | Backend | Benefit |
|---|---|---|
| macOS / Apple Silicon | Metal | Up to 20x load time reduction on complex shader graphs |
| Windows | D3D12 | Eliminates D3D12 pipeline state compilation stalls |
| Mobile (Android/iOS) | GLES3 | Faster first-render on mid-range hardware |
| Linux / Windows | Vulkan | Moderate improvement; Vulkan caches vary by driver |
The Shader Baker runs automatically when exporting via the editor GUI or CLI (--export-release). No extra steps are needed in CI — it is controlled by the preset configuration, not a separate CLI flag.
# Shader Baker runs as part of normal export (no extra flag needed).
godot --headless --export-release "Windows Desktop" build/windows/MyGame.exe
Before Godot 4.5, modifying .exe metadata (version info, icon, copyright, company name) on Windows required the external rcedit tool. Godot 4.5 handles all of this natively at export time — no rcedit download or configuration needed.
| Export Preset Field | Effect on .exe |
|---|---|
application/file_version | File version shown in Properties → Details |
application/product_version | Product version |
application/company_name | Company name |
application/product_name | Product name |
application/file_description | Description |
application/copyright | Legal copyright |
application/icon | .ico file embedded as the executable icon |
application/* fields under Application in the preset options..exe directly.Removing rcedit from CI: If your project previously downloaded
rceditin CI and called it as a post-export step, you can remove that step. The fields in the export preset replace it entirely for Godot 4.5+.
export_presets.cfg committed to version controlname= that matches the CLI --export-release argument exactlymkdir -p)chmod +x)application/config/version in project.godot is populated at export time from a git tagCOOP + COEP headers if threads are enabled.exe metadata (version, icon, company name) set in the export preset — rcedit no longer required (Godot 4.5+)