Files

T

andrew 0b51d133a4 Archive Steam docs; add itch.io upload guide

Move legacy Steam-related docs into documentation/archived and add a new UPLOAD-ITCH.md describing how to publish builds to itch.io with Butler. Update top-level README to state official releases will be on itch.io. Remove Steam-specific UI/features: drop steamCloudOptIn from first-run preferences, remove the Steam Cloud teaser and summary from the setup flow, and adjust settings/setup copy to reference handheld devices and non‑Steam distribution. Also make a small wording tweak in the plugins doc about rendererPreload.

2026-02-24 20:50:00 +13:00

3.0 KiB

Raw Blame History

Uploading releases to itch.io using Butler

This document explains how to prepare and upload Nebula releases to itch.io using Butler, covering macOS, Windows, and Linux.

Overview

Butler (itch.io) is the recommended channel for distributing Nebula releases. The process is:

Build your platform-specific artifact.
Install and authenticate butler.
Push the build to your username/game:channel with butler push.

Install Butler

macOS / Linux / Windows: Download the appropriate Butler binary from the official itch.io Butler releases (follow the official docs). Unpack, make executable, and place it on your PATH.

Example (Linux/macOS):

# after downloading 'butler' binary
chmod +x butler
sudo mv butler /usr/local/bin/

On Windows, place butler.exe in a folder on PATH or use it directly from the build folder.

Authenticate

Run:

butler login

This opens a browser-based authentication flow. Verify with:

butler whoami

If automation is required, consult the official Butler docs for API-key/token login options.

Prepare platform artifacts

macOS

Create a zip of your .app bundle (keep the .app as a top-level item inside the zip):

ditto -c -k --sequesterRsrc --keepParent MyApp.app MyApp-mac.zip

Windows

Zip the folder containing your .exe and runtime files, or create an installer and zip the installer.

Compress-Archive -Path .\build\MyApp\* -DestinationPath MyApp-windows.zip

Linux

Create a tarball (or zip) of the Linux runtime files:

tar -czf MyApp-linux.tar.gz -C build/linux .

Note: ensure the main binary has executable permissions before archiving.

Push to itch.io

Basic command:

butler push <path> <username>/<game>:<channel>

Examples:

# macOS build
butler push MyApp-mac.zip myuser/nebulabrowser:mac

# Windows build
butler push MyApp-windows.zip myuser/nebulabrowser:windows

# Linux build
butler push MyApp-linux.tar.gz myuser/nebulabrowser:linux

Set a release version for itch.io using --userversion:

butler push MyApp-mac.zip myuser/nebulabrowser:mac --userversion 1.2.3

Recommended channel strategy

stable or default — production releases
beta — pre-release testing
Use platform-specific channels (e.g., mac, windows, linux) if you want separate channels per OS

Tips

Keep artifacts small and platform-specific to reduce download size.
Verify the upload with butler whoami and by visiting your game page on itch.io.
When testing on macOS, notarization and Gatekeeper may affect distribution; provide clear install instructions on your itch page.

Rollback

Butler supports pushing to a channel multiple times; the latest pushed build becomes the current for that channel. To revert, push a previous artifact or use the itch.io web UI to select a previous build.

References

Consult the official Butler documentation for advanced usage (credentials, automated CI uploads, delta uploads, and platform-specific packaging recommendations).

3.0 KiB Raw Blame History