BetterCurseForge/docs/guide/installation.md

# Installation & Usage

This guide covers installing, managing, and uninstalling **BetterCurseForge** using either the desktop GUI application or the command-line interface.

---

## Prerequisites

Before using BetterCurseForge, make sure you have:

- **Windows 10 or Windows 11** (64-bit)
- **CurseForge Launcher** installed (standalone or Overwolf edition)
- CurseForge closed before running the patcher

::: tip SAFE & 100% REVERSIBLE
Before modifying any files, BetterCurseForge creates untouched vanilla backups at `resources/app.asar.vanilla` and `CurseForge.exe.vanilla`. You can cleanly revert to stock CurseForge at any time with a single click.
:::

---

## Method 1: Using the Desktop GUI (Recommended)

BetterCurseForge comes as a standalone desktop executable with a sleek, dark-themed graphical interface.

### Step 1: Download `BetterCurseForge.exe`

Download the latest executable from the official releases:

- [Download `BetterCurseForge.exe`](https://github.com/BetterCurseForge/BetterCurseForge/releases/latest)

Place it in any convenient folder (e.g., Downloads, Tools, or desktop).

### Step 2: Open BetterCurseForge

Double-click `BetterCurseForge.exe` to launch the application.

![BetterCurseForge GUI](/logo.png){width=64 style="display:block;margin:1rem auto;"}

The application automatically:
- Detects your CurseForge installation folder from the Windows Registry.
- Checks whether your client is currently vanilla or patched.
- Displays the installed CurseForge version and installation directory.

### Step 3: Click "Patch CurseForge"

1. Click the **Patch CurseForge** button.
2. The patcher will close any running CurseForge processes, create a vanilla backup, apply all enhancements (ad removal, theme engine, premium unlocks, and plugin loader), update the executable integrity signature, and repack the application.
3. You will see live output in the log panel confirming:
   ```text
   [+] Found CurseForge at: C:\Users\Username\AppData\Local\Programs\CurseForge Windows
   [+] Unlocked native premium themes (2 route checks)
   [+] Unlocked premium theme state validation
   [+] Unlocked subscription plan status for themes (4 checks)
   [+] Injected zero-ad and theme CSS rules into desktop.css
   [+] Bundled BetterCurseForge runtime into asar
   [+] Injected main-process hooks into background.js
   [+] Injected renderer script into desktop.html
   [+] Injected renderer loader into preload.js
   [+] Updated CurseForge.exe integrity signature
   [+] Auto-repatch watcher active and persistent across updates.
   [*] CurseForge successfully patched! Ads removed, themes & plugins enabled.
   ```
4. Click **Launch CurseForge** or open your usual desktop shortcut—you're done!

---

## Method 2: Command-Line Interface (CLI)

For automated workflows, scripting, or headless environments, `BetterCurseForge.exe` provides a comprehensive CLI:

### Patching via Terminal

Open PowerShell or Command Prompt in the folder containing `BetterCurseForge.exe`:

::: code-group

```powershell [PowerShell]
.\BetterCurseForge.exe patch
```

```cmd [Command Prompt]
BetterCurseForge.exe patch
```

:::

### Checking Status

Verify whether your client is patched:

```powershell
.\BetterCurseForge.exe status
```

Output:
```text
CurseForge Status: PATCHED (BetterCurseForge v1.0.0)
Path: C:\Users\Username\AppData\Local\Programs\CurseForge Windows
ASAR Hash: Verified
```

### Unpatching

Restore your vanilla CurseForge client:

```powershell
.\BetterCurseForge.exe unpatch
```

This restores `resources/app.asar` from the vanilla backup and re-verifies original executable signatures.

---

## Auto-Repatch: Surviving CurseForge Updates

When the official CurseForge Launcher downloads an automatic update, it overwrites `app.asar` with an unpatched version and attempts to restart.

BetterCurseForge provides an autonomous, smooth transition with **zero screen flashing**:

### Managing Auto-Repatch in the GUI
- In the BetterCurseForge desktop application, simply toggle the **Auto-Repatch on Update** button (turns green when active).

### Managing Auto-Repatch via CLI
```powershell
# Run the background watcher daemon directly:
.\BetterCurseForge.exe watch

# Trigger the smooth splash updater GUI manually:
.\BetterCurseForge.exe --repatch-splash

# BetterCurseForge also manages watcher persistence automatically on patch/unpatch:
.\BetterCurseForge.exe patch    # Applies patch and activates watcher autostart
.\BetterCurseForge.exe unpatch  # Restores vanilla client and stops watcher
```

### How Auto-Repatch Works
1. **Background Watcher**: Runs silently with 0% CPU consumption via Windows directory event notifications and heartbeat checks.
2. **Active Vanilla Interceptor**: When an update or unpatched state is detected, the patcher polls every 150ms using Win32 kernel process enumeration. If the installer launches `CurseForge.exe`, it is killed within 50ms before any window or frame can appear.
3. **Dedicated Splash Updater GUI**: A modern, dark-themed `#121214` card appears on screen displaying the application icon, a purple `AUTO-UPDATE` badge, an animated progress bar, and real-time status messages while extracting, unlocking themes, removing ads, and repacking.
4. **Offline Zero-Delay Engine**: Offline ASAR extraction and repacking complete in 2–3 seconds using CurseForge's built-in Node v24 runtime (`ELECTRON_RUN_AS_NODE=1`), synchronizing the `OWEASARSIG` hash directly inside `CurseForge.exe`.
5. **Seamless Relaunch**: The patched BetterCurseForge client opens automatically, and the splash window gracefully closes.

---

## How It Works Under the Hood

Modern versions of CurseForge include **ASAR Code Integrity Verification** enforced directly inside `CurseForge.exe`:

```mermaid
flowchart TD
    A["BetterCurseForge.exe"] --> B["Locate CurseForge Windows Installation"]
    B --> C["Extract app.asar & Create Vanilla Backup"]
    C --> D["Unlock Native Premium Themes & Validate Subscription State"]
    D --> E["Inject Zero-Ad & Theme CSS into desktop.css"]
    E --> F["Bundle BetterCurseForge Runtime (Main, Preload, Renderer)"]
    F --> G["Repack app.asar & Calculate SHA256 Header Hash"]
    G --> H["Update CurseForge.exe OWEASARSIG Integrity Signature"]
    H --> I["Launch Modded CurseForge with Full Permissions"]
```

1. **Multi-Layer Ad Elimination**: Blocks ad network requests at the Electron session level (`session.webRequest`) and collapses ad frames to 0px using CSS rules, completely preserving React Fiber virtual DOM reconciliation.
2. **Premium Skin Unlock**: Uses version-resilient AST/regex matching to unlock all official CurseForge skins (*Pixelforge*, *Lifeforge*, *Fantasyforge*, *Halloween*, etc.) in **Settings -> Themes**.
3. **ASAR Signature Synchronization**: Calculates the cryptographic SHA256 hash of the modified ASAR archive header and writes the new signature directly into `CurseForge.exe`, ensuring Electron boots without security errors or corruption alerts.

---

## Troubleshooting & FAQ

::: details How do I verify BetterCurseForge is running?
1. Open CurseForge.
2. Notice the total absence of banner ads and video sponsor frames.
3. Navigate to **Settings -> Themes**: you will see the **Client Themes** section with *Purple Night* available, as well as unlocked *Premium* skins (*Pixelforge*, *Lifeforge*, etc.).
4. Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> to open DevTools. The console will display:
   ```text
   [BetterCF] Initializing renderer runtime...
   [BetterCF] Theme manager ready (1 theme(s) found). Active: purple-night.css
   [BetterCF] ✓ BetterCurseForge loaded successfully!
   ```
:::

::: details Antivirus false-positive warning
Because `BetterCurseForge.exe` inspects running processes (`CurseForge.exe`), accesses the Windows Registry to locate install paths, and updates executable hashes, some heuristic scanners may flag it. BetterCurseForge is completely open source and safe. You can inspect the entire Python codebase in `patcher/` and build it yourself.
:::

::: details Permission denied / EPERM error
If your CurseForge launcher is installed under `C:\Program Files`, modifying files requires Administrator permissions. Right-click `BetterCurseForge.exe` and select **Run as Administrator**.
:::