BetterCurseForge

The modern, lightweight client modification for CurseForge Launcher.

Zero Ads • Custom Themes • Unlocked Skins • Extensible Plugins • Autonomous Auto-Repatch

✨ Features

🚫 Complete Zero-Ad Experience: Multi-layer ad elimination:
- Electron session.webRequest network request blocker stops Overwolf/Adrta/DoubleClick ad calls before they start.
- React component interception replaces ad renderers with clean empty nodes.
- Fail-safe CSS rules neutralize ad frames, banners, and swap buttons.
🎨 First-Class Theme Engine:
- Seamlessly embedded into CurseForge's native Settings > Themes screen.
- Live CSS injection with instant hot-reloading (no launcher restarts needed).
- Bundled with Purple Night—a custom dark theme featuring violet accents, sleek card elevations, and custom badge styling.
🔓 Unlocked Native Premium Themes & Skins:
- Unlocks all official CurseForge subscriber skins (PixelForge, LifeForge, FantasyForge, Halloween, etc.) without requiring a CurseForge subscription.
🧩 Extensible Plugin System:
- Modular plugin architecture with lifecycle hooks (onEnable, onDisable), safe IPC communication, and scoped styling.
- Includes sample plugins like Compact Mode.
🛡️ Autonomous Auto-Repatch Engine:
- Survives in-app CurseForge updates automatically!
- Offline, zero-delay ASAR extraction and repacking (< 3 seconds) using CurseForge's internal Node v24 runtime—no internet connection or external npm/npx required.
- Synchronizes Overwolf's binary OWEASARSIG integrity hashes directly inside CurseForge.exe.
- Background watcher daemon ensures your modifications are immediately re-applied when CurseForge updates.

🚀 Quick Start

Easy Installation (GUI)

Download the latest BetterCurseForge.exe from Releases.
Run BetterCurseForge.exe.
Click Patch CurseForge.
Launch CurseForge Launcher—your modded client is ready to use!

Command-Line Interface (CLI)

BetterCurseForge.exe can also be run directly from PowerShell or Command Prompt:

# Check current patch and watcher status
.\BetterCurseForge.exe status

# Apply BetterCurseForge patch
.\BetterCurseForge.exe patch

# Restore original vanilla CurseForge
.\BetterCurseForge.exe unpatch

🔄 How Auto-Repatch Works

Whenever CurseForge downloads an update, the Overwolf installer replaces resources/app.asar with a vanilla archive and restarts CurseForge.exe. BetterCurseForge guarantees you never lose your patch:

flowchart TD
    A[CurseForge Launcher Update] -->|Installer downloads update| B[CurseForge Quitting / Replacing Files]
    B -->|Hook & Watcher Detect Update| C[Auto-Repatch Triggered]
    C -->|Wait for Installer to Settle| D[Settle Verified]
    D -->|Offline Extraction & Patch <3s| E[Dist & BetterCF Injected]
    E -->|Recalculate ASAR SHA-256| F[Synchronize OWEASARSIG in CurseForge.exe]
    F -->|Autonomous Relaunch| G[Modded CurseForge Launcher Ready!]

Permanent Daemon Installation: On first patch, BetterCurseForge installs to %LOCALAPPDATA%\BetterCurseForge with an autostart registry entry in HKCU\...\Run.
Proactive In-App Update Interceptor: BetterCurseForge monitors updater states on app quit (before-quit) to initiate patching before the new launcher process initializes.
Resilient Win32 Watcher Daemon: A silent background process monitors CurseForge's installation directory with 0% CPU consumption. If an unpatched state is detected (e.g., after an update), it terminates the unpatched process, reapplies the patch, and relaunches the modded client.
100% Offline Zero-Delay ASAR Engine: Unpacking and repacking use bundled tools combined with CurseForge's built-in Node runtime (ELECTRON_RUN_AS_NODE=1), completing the entire repatch cycle in 3–4 seconds without requiring an internet connection.

🎨 Themes & Plugins

User configurations, themes, and plugins are stored in your AppData directory:

%APPDATA%\CurseForge\BetterCurseForge\
├── themes/
│   ├── purple-night.css
│   └── purple-night.json
└── plugins/
    └── compact-mode/
        ├── manifest.json
        └── index.js

You can open these folders anytime via the Open Themes Folder and Open Plugins Folder buttons in the BetterCurseForge GUI.

Creating a Custom Theme

Create a CSS file and manifest in %APPDATA%\CurseForge\BetterCurseForge\themes\my-theme.css:

{
  "name": "My Theme",
  "description": "Custom color theme for CurseForge",
  "author": "Your Name",
  "version": "1.0.0",
  "css": "my-theme.css"
}

:root {
  --surface-brand-brand: #10b981 !important;
  --surface-brand-brand-hover: #059669 !important;
}

🛠️ Building from Source

Prerequisites

Windows 10 / 11
Python 3.10+
Node.js 20+ (for docs)

Build Instructions

# Clone the repository
git clone https://github.com/your-username/BetterCurseForge.git
cd BetterCurseForge

# Build standalone executable with PyInstaller
python -m pip install pyinstaller
python -m PyInstaller BetterCurseForge.spec --noconfirm

# Output executable will be in:
# dist/BetterCurseForge.exe

Running VitePress Documentation

cd docs
npm install
npm run dev

📄 License

This project is licensed under the MIT License. CurseForge and Overwolf are trademarks of their respective owners. BetterCurseForge is an independent open-source project and is not affiliated with or endorsed by Overwolf or CurseForge.

6.1 KiB Raw Blame History Unescape Escape