Easy Itch.io Push (Auto Build & Deploy)

Step 0: Prerequisites

Easy Itch Push requires the Butler utility from itch.io. The plugin supports several discovery methods:

• Automatic detection: Checks if Butler is installed via the official itch.io desktop app.
• System PATH: Searches for the Butler executable in your system PATH.
• Local install: Installs Butler locally via the plugin settings (see Butler Configuration below).

Step 1: Plugin Installation

• Copy the plugin folder into your project’s Plugins directory (create it if it does not exist), or into the engine’s global Plugins folder.
• Open Unreal Editor and enable the plugin under Edit → Plugins.
• After restart, a Push to itch.io button will appear on the main toolbar.

Step 2: Butler Configuration

Navigate to Project Settings → Plugins → Easy Itch Push. In the Butler section you can manage the CLI state:

Auth Method lets you choose how to authorize: use Pass for the classic login/password flow (Sign in / Sign out), or API Key to authorize using an API key from your itch.io account.

• Status: Shows whether Butler is installed and ready.
• Download: Opens the official Butler download page in your browser (from there you can download the latest builds for Windows, macOS, and Linux from https://itchio.itch.io/butler).
• Install…: Installs Butler from a .zip archive into the project folder at Saved/EasyItchPush/bin.
• Refresh: Refreshes version info and authorization status.
• Upgrade: Updates Butler to the latest version directly from the editor.

Step 3: Account & Project Configuration

Still in Project Settings → Plugins → Easy Itch Push, configure the itch.io section:

• itch.io username: Your profile name from the URL. For https://tessermind.itch.io/ use tessermind.
• Game / project name: The project slug from the URL. For https://user.itch.io/my-game use my-game.
• Channel: Upload channel, e.g. windows-x64, linux-universal, mac-os. Default is windows.
• Project ID: Numeric game ID from the edit URL, e.g. https://itch.io/game/edit/999999 → 999999. Used to open the game’s edit page after upload.
• Use version / Version: Enables passing --userversion to Butler. The value (e.g. v1.0.4, alpha-2) appears in the build list on itch.io.
• Open itch.io page on finish: Automatically opens the game’s edit page in your browser after a successful upload.

Step 4: Packaging Settings

In the Packaging section configure how the build is created before upload:

• Build Configuration: Shipping, Development or Debug.
• For Distribution: Recommended for release builds; disables debugging features.
• Full Rebuild: Forces a full rebuild of the project before every upload.
• Use IoStore: Enables Zen Loader (recommended for UE5) for faster streaming.
• Compress Content: Compresses .pak files to reduce final archive size.
• Include Prerequisites: Includes installers for dependencies (DirectX, VC++, etc.).
• Custom Build Path: Custom output folder. Default is Saved/EasyItchPush/Build.
• Levels to Cook: Explicit list of maps to include. If empty, all maps are cooked.
• Localizations to Package: Select which cultures to include in the build.

One-click Upload

To publish a new build, simply click the Push to itch.io button on the main toolbar. The plugin will:

• Validate: Check plugin settings and Butler readiness.
• Package: Run the standard Unreal Engine packaging process.
• Push: Upload the resulting files to itch.io using Butler.

Progress & Notifications

• Progress and status are shown in a notification in the bottom-right corner of the editor.
• Audible cues indicate start, success and failure of the process.
• A Cancel button in the notification allows aborting the operation at any time.
• Detailed logs are available in Output Log under categories: LogEasyItchPush, LogEasyItchPushBuild, LogEasyItchPushUpload.

Slug Normalization

The plugin automatically normalizes your username and game slug to match itch.io standards:

• Converts to lowercase.
• Replaces spaces with dashes.
• Removes unsupported characters where possible.

Security & Auth

Easy Itch Push never stores your password. Authentication uses the official itch.io OAuth flow.