# Upload Builds and Patches

Upload your game builds to distribute updates to players through your launcher. Supports large files (depending your plan) with automatic patching.

***

## Build Types

* **Baseline:** A standard upload containing all your files.
* **Merge Builds:** This option allows you to upload only a your changed files *(e.g., small typo fixes or menu updates)* and have Game Launcher Cloud automatically **merge** them with the existing files in the "Baseline" (default) build.

## Upload Methods

{% tabs %}
{% tab title="Dashboard (Web)" %}
🌐 **Web Dashboard Upload**

Perfect for small to medium builds (\~5 GB)

{% hint style="success" %}
For larger files, use the [**CLI Tool**](/help/extensions/cli-releases.md).
{% endhint %}

<figure><img src="/files/OCSTbnHOaZOxmlyCboCm" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="CLI (Command Line)" %}
**Command Line Interface (CLI)**

[📖 CLI Documentation](/help/extensions/cli-releases/cli-builds.md)

Perfect for large builds and automation

**Advantages:**

* ✅ Upload large files (depending your plan)
* ✅ Faster for large files
* ✅ CI/CD integration
* ✅ Scriptable and automated
* ✅ Direct to Cloudflare R2

**Best for:**

* Large game builds
* Automated workflows
* CI/CD pipelines
* Team collaboration
  {% endtab %}
  {% endtabs %}

***

## Dashboard Build[^1] Upload Guide

### Step 1: Navigate to Your Application

{% stepper %}
{% step %}
**Access Dashboard**

Log in to your [Game Launcher Cloud](https://app.gamelauncher.cloud/dashboard) account
{% endstep %}

{% step %}
**Select your Game App**

In the sidebar → Click on your app

<div align="left"><figure><img src="/files/qlxYZy4OumTO5kpq9SgX" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Open App Builds Tab**

Click on the **App** **Builds** tab in your application page

<div align="left"><figure><img src="/files/xHAhimFGO3You3gfqZN8" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

***

### Step 2: Prepare Your Build

Before uploading, ensure your [game build](#user-content-fn-1)[^1] meets these requirements:

{% hint style="warning" %}
**Important:** Do not include unnecessary files like source code, logs, .git folders, or development tools to keep build size minimal.
{% endhint %}

<table data-full-width="false"><thead><tr><th width="150">Requirement</th><th width="264">Details</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Format</strong></td><td>ZIP compressed file</td><td>Must be a .zip file</td></tr><tr><td><strong>Size</strong></td><td>Up to 5 GB (Dashboard)<br>Or large files with <a href="#cli-command-line">CLI</a></td><td></td></tr><tr><td><strong>Files Structure</strong></td><td><strong>Files must be in the ZIP Root</strong><br><em>(Avoid single folder compress)</em></td><td>Select all your files and compress</td></tr></tbody></table>

<figure><img src="/files/dRNpT7kkLo564VoM6fpM" alt=""><figcaption><p>Compress your game as a ZIP</p></figcaption></figure>

{% hint style="success" %}
**Make sure to select all the files and compress to keep them in the root of the ZIP**
{% endhint %}

<figure><img src="/files/dPD2krh3xAbqwFqBWtoI" alt=""><figcaption><p>CORRECT: Select all the files and compress as a ZIP</p></figcaption></figure>

***

### Step 3: Upload Your Build[^1]

#### Upload Interface

1. **Drag & Drop or Browse**: Select your .zip file
2. **Add Build Notes** (optional): Describe changes, bug fixes, new features
3. **Click "Upload Your Build"**: File upload begins immediately
4. **Wait for Processing**: Monitor the build status until it completes

<figure><img src="/files/NVoJNGc5MjyGGilL4R0R" alt=""><figcaption><p>Upload new build</p></figcaption></figure>

***

### Step 4: Build Processing

<figure><img src="/files/2boHHWD97QanFdSNnR6W" alt=""><figcaption><p>Jobs Monitor - Processing App Build</p></figcaption></figure>

After upload, the system processes your build:

**Processing Stages:**

1. **⬆️ Uploading** - File upload to cloud storage
2. **⬇️ Downloading** - Server retrieves the file
3. **📦 Unzipping** - Extracting build contents
4. **🔧 Creating Patch** - Generating delta patches
5. **✅ Completed** - Build is ready for distribution

{% hint style="info" %}
**Processing Time (depends on build size and file count)**

* Small builds (<1 GB with \~500 files): 5-30 seconds
* Medium builds (1-5 GB with \~1,000 files): 3-5 minutes
* Large builds (5-50 GB with \~25,000 files): 5-25 minutes
  {% endhint %}

***

### Step 5: Set Active Build[^1]

Once your build is processed, you need to activate it so players can download it:

{% stepper %}
{% step %}
**Navigate to App Builds Tab**

Go to your application → **App** **Builds** tab

<div align="left"><figure><img src="/files/rdcmxkRdJR3VMXlPLaqw" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Find Your Build**

Locate below the newly uploaded build in the builds list (status should be **Completed**)

<figure><img src="/files/c8QwTqOHTvnLpw4Ok9JZ" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Set as Active**

Scroll up to the Environments section and click **"Change Active Build"**

<figure><img src="/files/jkrJTaGwKKYgkF9X47Ww" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Confirm Activation**

<figure><img src="/files/M62sk9jlMRbNRFEBiJbA" alt=""><figcaption><p>Change active build dialog</p></figcaption></figure>

Select the latest build and click **Set Build** button.

\
After this just return to your launcher and click refresh to fetch the new update!
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Active Build**: Only ONE build per platform and environment can be active at a time. When you set a new build as active, it replaces the previous one.
{% endhint %}

{% hint style="success" %}
**Players Update**: Once a build is set as active, players will automatically receive the update next time they open the launcher.
{% endhint %}

***

## Reference

### Build File Recommended Structure

Your ZIP file should contain a clean game structure:

```
MyGame.zip
├── MyGame.exe              (Windows)
├── assets/
│   ├── textures/
│   ├── sounds/
│   └── models/
├── data/
│   ├── config.json
│   └── settings.ini
└── README.txt
```

### Platform-Specific Examples

{% tabs %}
{% tab title="Windows" %}

```
MyGame_Windows.zip
├── MyGame.exe           ← Main executable
├── MyGame_Data/         ← Unity/Unreal data
├── MonoBleedingEdge/    ← Unity runtime
├── UnityCrashHandler64.exe
└── UnityPlayer.dll
```

{% endtab %}

{% tab title="macOS" %}

```
MyGame_macOS.zip
├── MyGame.app/          ← macOS application bundle
│   └── Contents/
│       ├── MacOS/
│       ├── Resources/
│       └── Info.plist
└── README.txt
```

{% endtab %}

{% tab title="Linux" %}

```
MyGame_Linux.zip
├── MyGame.x86_64        ← Linux executable
├── MyGame_Data/
├── UnityPlayer.so
└── run.sh               ← Optional launch script
```

{% endtab %}
{% endtabs %}

***

### Delta Patching

Game Launcher Cloud automatically generates delta patches between builds:

#### How It Works

{% @mermaid/diagram content="graph LR
A\[Build #1<br/>1.5 GB] --> C\[Delta Patch<br/>150 MB]
B\[Build #2<br/>1.6 GB] --> C
C --> D\[Player<br/>Downloads<br/>Only 150 MB]

```
style C fill:#10b981,stroke:#333,stroke-width:2px,color:#fff
style D fill:#667eea,stroke:#333,stroke-width:2px,color:#fff" %}
```

**Benefits:**

* **90% smaller downloads** on average
* **Faster updates** for players
* **Lower bandwidth costs**
* **Automatic** - no configuration needed

{% hint style="success" %}
**Example:** If you change 100 MB in a 5 GB game, players only download 100 MB instead of the full 5 GB!
{% endhint %}

***

### Smart Bundles Technology

{% hint style="success" %}
**NEW:** Revolutionary Smart Bundles system for dramatically faster downloads, especially for games with many small files!
{% endhint %}

#### What are Smart Bundles?

Smart Bundles automatically group small files into optimized packages during patch generation, reducing download overhead and dramatically improving update speeds.

**Example Impact:**

* A **1.16 GB** game with **309 files** becomes **1.07 GB** with only **5 files**
* Result: **Significantly faster downloads** for players

#### How It Works

{% @mermaid/diagram content="graph LR
A\[Many Small Files] --> B\[Smart Bundling]
B --> C\[Optimized Packages]
C --> D\[Faster Downloads]

```
style A fill:#ef4444,stroke:#333,stroke-width:2px,color:#fff
style D fill:#10b981,stroke:#333,stroke-width:2px,color:#fff" %}
```

**Process:**

1. **Analysis** - System identifies small files (< 5 MB)
2. **Bundling** - Groups related files into optimized packages
3. **Compression** - Applies efficient compression
4. **Distribution** - Launcher downloads and extracts bundles seamlessly

#### Benefits

* **Dramatically Faster** - Reduced overhead for games with many small assets
* **Automatic** - No configuration or changes needed on your part
* **Efficient** - Better compression and organization
* **Adaptive** - Intelligently bundles based on file size and patterns

{% hint style="info" %}
**Availability:** Smart Bundles are available for newer builds. Older builds continue using standard patching without issues.
{% endhint %}

#### Performance Impact

**For Developers:**

* \~20% additional storage during patch generation for bundle optimization
* Significantly faster end-user downloads

**For Players:**

* Much faster update downloads, especially for games with thousands of small files
* Seamless experience - bundles are extracted automatically

***

### xxHash64 - Faster File Verification

{% hint style="success" %}
**MAJOR UPGRADE:** xxHash64 is now the primary hashing method, providing **10-20x faster** performance than MD5!
{% endhint %}

#### What Changed?

The platform now uses **xxHash64** for all file verification and integrity checks, replacing the slower MD5 algorithm.

**Speed Comparison:**

* MD5: Traditional speed
* xxHash64: **10-20x faster** ⚡

#### Impact

**For Build Creation:**

* ✅ **Much faster patch generation** (both local and server-side)
* ✅ **Faster file verification** during downloads
* ✅ **Reduced CPU usage** during processing
* ✅ **Quicker build processing** on the server

**For Players:**

* ✅ **Shorter verification times** during updates
* ✅ **Faster integrity checks**
* ✅ **Improved download performance**

#### Compatibility

* ✅ **Fully Backward Compatible** - Old patches using MD5 continue working
* ✅ **Automatic Detection** - System detects which algorithm each patch uses
* ✅ **Seamless Transition** - No action needed from you or your players

{% hint style="info" %}
**Server Transition:** For 2 weeks, server-side builds generate patches with both MD5 and xxHash64. After this period, only xxHash64 will be used for maximum performance.
{% endhint %}

***

### Build Notes Best Practices

Good build notes help players understand what's new:

#### ✅ Good Example

```markdown
**Version 1.2.0 - November 2025**

🎮 New Features:

- Added multiplayer co-op mode
- New character customization options
- 5 new maps in rotation

🐛 Bug Fixes:

- Fixed crash when loading large maps
- Improved FPS on low-end systems
- Fixed audio sync issues

⚖️ Balance Changes:

- Reduced weapon damage by 10%
- Increased player movement speed
```

#### ❌ Poor Example

```
update
```

{% hint style="info" %}
**Tip:** Use markdown formatting for better readability. Players see this in the launcher before downloading.
{% endhint %}

***

## Troubleshooting

Common issues and solutions:

<table data-full-width="false"><thead><tr><th width="200">Issue</th><th width="150">Cause</th><th>Solution</th></tr></thead><tbody><tr><td><strong>Stuck at "Enqueued"</strong></td><td>Build waiting in processing queue</td><td>Should process after a few minutes. If it continues stuck, contact support immediately with Build ID.</td></tr><tr><td><strong>Stuck at "Processing"</strong></td><td>Large file being processed</td><td>Wait 15-60 minutes for large builds. Check status regularly.</td></tr><tr><td><strong>Build shows "Failed"</strong></td><td>Corrupt ZIP or invalid structure</td><td>Re-compress the file, ensure no corrupted files inside</td></tr><tr><td><strong>Upload very slow</strong></td><td>Network connection</td><td>Use CLI for better upload performance, check internet speed</td></tr><tr><td><strong>Can't find build after upload</strong></td><td>Wrong environment selected</td><td>Check all environments (Dev/Prod/Custom)</td></tr></tbody></table>

{% hint style="success" %}
**Need Help?** Join [Discord](https://discord.com/invite/FpWvUQ2CJP) or email <support@gamelauncher.cloud>
{% endhint %}

***

## Best Practices

### 🎯 Optimize Build Size

* Remove unnecessary files (source code, temp files)
* Compress textures and audio appropriately
* Use game engine's compression settings
* Test build locally before uploading

### 🔄 Version Control

* Upload to Development environment first
* Test thoroughly before promoting to Production
* Keep build notes detailed and organized
* Archive old builds periodically

### 📊 Monitor Performance

* Check download analytics after release
* Monitor player feedback on updates
* Track build sizes over time
* Use delta patching effectively

### 🚀 Deployment Strategy

* **Development**: Immediate testing and iteration
* **Staging/Beta**: Limited player testing
* **Production**: Stable releases only
* Schedule updates during off-peak hours

***

## Next Steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>⚡ CLI Upload</strong></td><td>Upload large builds via command line</td><td><a href="/pages/ldf8xMmJffACG4lfxUOK">/pages/ldf8xMmJffACG4lfxUOK</a></td></tr><tr><td><strong>📰 News &#x26; Updates</strong></td><td>Create news posts to engage your players</td><td><a href="/pages/uquAxcCnbM4zORBOKUyW">/pages/uquAxcCnbM4zORBOKUyW</a></td></tr><tr><td><strong>🚀 Create Launcher</strong></td><td>Build launcher to distribute your game</td><td><a href="/pages/1cNgvv5uy79qCeQbdGPa">/pages/1cNgvv5uy79qCeQbdGPa</a></td></tr><tr><td><strong>📊 Analytics</strong></td><td>Track downloads and player engagement</td><td></td></tr></tbody></table>

***

{% hint style="success" %}
**🎉 Ready to upload?** Start with a Development build to test the process before going to Production!
{% endhint %}

[^1]: A build is a packaged version of your game.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gamelauncher.cloud/help/applications/upload-builds.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.