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)

1. Download the latest BetterCurseForge.exe from Releases.
2. Run BetterCurseForge.exe.
3. Click Patch CurseForge.
4. 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!]

1. Permanent Daemon Installation: On first patch, BetterCurseForge installs to %LOCALAPPDATA%\BetterCurseForge with an autostart registry entry in HKCU\...\Run.
2. Proactive In-App Update Interceptor: BetterCurseForge monitors updater states on app quit (before-quit) to initiate patching before the new launcher process initializes.
3. 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.
4. 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.