# 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**](https://gamelauncher.cloud/help/extensions/cli-releases).
{% endhint %}

<figure><img src="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2F3OP9JqFdPaypY7FA8Uxv%2Fimage.png?alt=media&#x26;token=443f9e97-13fb-4e3d-8c33-e5b598840288" alt=""><figcaption></figcaption></figure>
{% endtab %}

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

[📖 CLI Documentation](https://gamelauncher.cloud/help/extensions/cli-releases/cli-builds)

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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2FvpWsdJRcKxgFJFbfLUjR%2Fimage.png?alt=media&#x26;token=c9ad1794-0032-4eb6-a407-03ec4f5efce7" 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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2FVyIoX1J31fwFmSffvbip%2Fimage.png?alt=media&#x26;token=35b4e5d9-adfc-4479-9bc3-3d9e49083c31" 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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2FD3iE9JLXKIzx6nk7YEBf%2FCompress%20Build.gif?alt=media&#x26;token=68e41300-9e1f-4a25-ac3f-1e5c85973a24" 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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2FmIX5iVZmQSKR8kcfAY8I%2FFrame%2049.png?alt=media&#x26;token=9c6d30c4-7e5a-479f-ab49-49712fbbe1f8" 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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2FG6e5HLueTo9zYqNDoJSk%2Fimage.png?alt=media&#x26;token=d49c1b2e-2b13-48cf-8520-2dfe9f836f8e" alt=""><figcaption><p>Upload new build</p></figcaption></figure>

***

### Step 4: Build Processing

<figure><img src="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2Fk1eTUN92GkdDnceq9aDQ%2Fimage.png?alt=media&#x26;token=4319ad54-0043-420d-9d8e-a55957e894c5" 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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2Fb6qzhazf7mWzRlGGvNwn%2Fimage.png?alt=media&#x26;token=3c35b377-4e3f-46ac-8f18-56aa13d53fe1" 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="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2F45xzz4mAFpBgngP1jYKL%2Fimage.png?alt=media&#x26;token=d6ba5016-ac50-41d3-9d40-9dce146577fb" alt=""><figcaption></figcaption></figure>
{% endstep %}

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

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

<figure><img src="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2F44qi3gPPeNzWxyG1mAVg%2Fimage.png?alt=media&#x26;token=82af1b85-24b1-4475-9775-0372de8e119a" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Confirm Activation**

<figure><img src="https://4241524842-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnNH3XbUy7pSptjMVADb2%2Fuploads%2F0O0y0wbUlQzfNVE2stV4%2Fimage.png?alt=media&#x26;token=532c2e20-359b-42f8-b7e2-1a118172ac29" 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="../extensions/cli-releases/cli-builds">cli-builds</a></td></tr><tr><td><strong>📰 News &#x26; Updates</strong></td><td>Create news posts to engage your players</td><td><a href="../news-and-announcements/create-news">create-news</a></td></tr><tr><td><strong>🚀 Create Launcher</strong></td><td>Build launcher to distribute your game</td><td><a href="../launchers/create-launcher">create-launcher</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.