BetterCurseForge/docs/guide/installation.md

# Installation & Usage

How to install, check, and remove **BetterCurseForge**, using either the desktop app or the command line.

---

## Prerequisites

You need:

- **Windows 10 or Windows 11** (64-bit)
- **CurseForge Launcher** installed (standalone or Overwolf edition)
- CurseForge closed when you run the patcher

::: tip BACKUPS
Before it changes anything, BetterCurseForge saves untouched copies of the original files at `resources/app.asar.vanilla` and `CurseForge.exe.vanilla`. You can go back to stock CurseForge whenever you want, with one click.
:::

---

## Option 1: Desktop GUI (recommended)

BetterCurseForge is a single executable with a dark-themed GUI.

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

Grab the latest build from the releases page:

- [Download `BetterCurseForge.exe`](http://92.5.113.44:3000/tomasalias/BetterCurseForge/releases)

Put it anywhere you like (Downloads, a tools folder, the desktop).

### Step 2: Open BetterCurseForge

Double-click `BetterCurseForge.exe` to open it.

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

On startup it:
- Finds your CurseForge install folder through the Windows Registry.
- Checks whether CurseForge is vanilla or patched.
- Shows the installed CurseForge version and install directory.

### Step 3: Click "Patch CurseForge"

1. Click the **Patch CurseForge** button.
2. The patcher closes any running CurseForge processes, backs up the vanilla files, applies the patch (ad blocking, theme engine, skin unlocks, plugin loader), updates the integrity signature in the executable, and repacks the app.
3. The log panel shows progress as it goes:
   ```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 start it from your usual shortcut. That's it.

---

## Option 2: Command line

If you want to script it or run it without the GUI, `BetterCurseForge.exe` has a CLI.

### Patching

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

::: code-group

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

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

:::

### Checking status

See whether CurseForge 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

Go back to stock CurseForge:

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

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

---

## Auto-repatch after CurseForge updates

When CurseForge updates itself, it overwrites `app.asar` with a stock copy and restarts.

BetterCurseForge handles this without the unpatched launcher ever showing up on screen.

### Managing it in the GUI
- Toggle the **Auto-Repatch on Update** button in the app. It turns green when it's on.

### Managing it from the 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 it works
1. **Background watcher**: Runs in the background on Windows directory change notifications and periodic heartbeat checks, so CPU use is negligible.
2. **Killing the stock launcher**: Once it sees an update or an unpatched install, the watcher polls every 150 ms with Win32 process enumeration. If the installer starts `CurseForge.exe`, the watcher kills it within 50 ms, before a window can appear.
3. **Splash window**: A dark `#121214` card shows the app icon, a purple `AUTO-UPDATE` badge, a progress bar, and status messages while it extracts, unlocks themes, blocks ads and repacks.
4. **Offline repatch**: Extracting and repacking the ASAR takes 2–3 seconds and needs no internet. It uses the Node v24 runtime bundled with CurseForge (`ELECTRON_RUN_AS_NODE=1`) and writes the new `OWEASARSIG` hash into `CurseForge.exe`.
5. **Relaunch**: The patched CurseForge opens and the splash window closes.

---

## Under the hood

Recent CurseForge versions verify the integrity of `app.asar` from inside `CurseForge.exe`. This is the patch flow:

```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. **Ad blocking**: Ad requests are blocked at the Electron session level (`session.webRequest`), and CSS collapses the ad frames to 0px. The elements stay in the DOM, so React Fiber's reconciliation isn't affected.
2. **Skin unlock**: AST and regex matching, written to tolerate version changes, unlocks the official CurseForge skins (*Pixelforge*, *Lifeforge*, *Fantasyforge*, *Halloween*, etc.) in **Settings -> Themes**.
3. **ASAR signature update**: It computes the SHA256 hash of the modified ASAR header and writes it into `CurseForge.exe`, so Electron starts without integrity errors.

---

## Troubleshooting

::: details How do I tell it's working?
1. Open CurseForge.
2. There should be no banner ads or video sponsor frames.
3. Go to **Settings -> Themes**. You should see a **Client Themes** section with *Purple Night* in it, and the *Premium* skins (*Pixelforge*, *Lifeforge*, etc.) unlocked.
4. Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> to open DevTools. The console should print:
   ```text
   [BetterCF] Initializing renderer runtime...
   [BetterCF] Theme manager ready (1 theme(s) found). Active: purple-night.css
   [BetterCF] ✓ BetterCurseForge loaded successfully!
   ```
:::

::: details Antivirus flags the exe
Some antivirus tools flag `BetterCurseForge.exe` as a false positive. It looks at running processes (`CurseForge.exe`), reads the Windows Registry to find the install path, and rewrites hashes in an executable, which is the kind of thing heuristic scanners react to. The project is open source: the Python code is in `patcher/`, and you can read it and build the exe yourself.
:::

::: details Permission denied / EPERM error
If CurseForge is installed under `C:\Program Files`, the patcher needs Administrator permissions to change files. Right-click `BetterCurseForge.exe` and choose **Run as Administrator**.
:::