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 an untouched vanilla backup at resources/app.asar.vanilla.bak. 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

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

Step 2: Open BetterCurseForge

Double-click BetterCurseForge.exe to launch the application.

{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:

   [+] Found CurseForge at: C:\Users\Username\AppData\Local\Programs\CurseForge Windows
   [+] Disabled React ad component (eV -> return null)
   [+] Disabled swap ads button
   [+] Unlocked all native premium themes (Settings route)
   [+] Unlocked all native premium themes (Popup route)
   [+] Injected zero-ad and theme CSS rules into desktop.css
   [+] Bundled BetterCurseForge runtime into asar
   [+] Updated CurseForge.exe integrity signature
   [*] 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

.\BetterCurseForge.exe patch

BetterCurseForge.exe patch

:::

Checking Status

Verify whether your client is patched:

.\BetterCurseForge.exe status

Output:

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:

.\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 a new version, temporarily removing client modifications.

BetterCurseForge solves this with Auto-Repatch:

Enabling Auto-Repatch in the GUI

• In the BetterCurseForge desktop application, simply toggle the Auto-Repatch on Update checkbox.

Enabling Auto-Repatch via CLI

.\BetterCurseForge.exe --auto-repatch enable

How Auto-Repatch Works

1. Registers a lightweight Windows background task.
2. Detects whenever CurseForge's files are modified or updated by Overwolf/CurseForge.
3. Automatically closes the client, creates a new backup of the updated version, applies the BetterCurseForge patches, updates the binary signature, and re-launches your modded client silently.
4. To disable anytime:

   .\BetterCurseForge.exe --auto-repatch disable
   

---

How It Works Under the Hood

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

flowchart TD
    A["BetterCurseForge.exe"] --> B["Locate CurseForge Windows Installation"]
    B --> C["Extract app.asar & Create app.asar.vanilla.bak"]
    C --> D["Disable React Ad Components & Swap Ads"]
    D --> E["Unlock Native Premium Themes (Pixelforge, Lifeforge, etc.)"]
    E --> F["Inject Zero-Ad & Responsive CSS into desktop.css"]
    F --> G["Bundle BetterCurseForge Core Runtime into asar"]
    G --> H["Repack app.asar & Calculate SHA256 Header Hash"]
    H --> I["Update CurseForge.exe ASAR Integrity Signature"]
    I --> J["Launch Modded CurseForge with Full Permissions"]

1. AST & Component Patching: Replaces the React ad rendering module (eV -> return null) to ensure ad frames are never mounted in the virtual DOM.
2. Premium Skin Unlock: Patches the client-side plan validation routes so all 4 native CurseForge skins (Pixelforge, Lifeforge, Fantasyforge, Spookyforge) can be freely selected in Settings -> Themes.
3. ASAR Signature Patching: Calculates the cryptographic SHA256 hash of the modified ASAR archive header and writes the new signature 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 Ctrl + Shift + I to open DevTools. The console will display:

   [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. :::