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 without breaking React Fiber:
  • Electron session.webRequest network request blocker stops Overwolf/Adrta/DoubleClick ad calls before they start.
  • Fail-safe CSS rules completely neutralize, hide, and collapse all ad frames, banners, and swap buttons to 0px.
  • Safe non-destructive DOM handling preserves React Fiber reconciliation, preventing insertBefore exceptions.
• 🎨 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

# Run background watcher daemon directly
.\BetterCurseForge.exe watch

---

🔄 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 -->|Watcher Detects Update| C[Auto-Repatch Triggered]
    C -->|Wait for Installer Files 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 and a task scheduler fallback.
2. Global Mutex Synchronization: Uses Windows kernel named mutexes (BetterCurseForgePatchMutex) to guarantee atomic, single-process patching with zero race conditions.
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 waits for installer files to settle, terminates the unpatched process, reapplies the patch, and relaunches the modded client seamlessly without console window popups.
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 2–3 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.