BetterCurseForge/README.md

# BetterCurseForge

<div align="center">

<img src="assets/icon_512.png" alt="BetterCurseForge Logo" width="128" height="128" />

### The modern, lightweight client modification for CurseForge Launcher.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows-0078D6.svg?logo=windows)](https://github.com/tomasalias/BetterCurseForge)
[![Zero Ads](https://img.shields.io/badge/Ads-Completely%20Blocked-success.svg)](#features)
[![Auto Repatch](https://img.shields.io/badge/Auto--Repatch-Autonomous-brightgreen.svg)](#-how-auto-repatch-works)

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

</div>

---

## ✨ 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](https://github.com/tomasalias/BetterCurseForge/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:

```bash
# 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

# Trigger the smooth splash updater GUI manually
.\BetterCurseForge.exe --repatch-splash
```

---

## 🔄 How Auto-Repatch Works

Whenever CurseForge downloads an official update, the Overwolf installer replaces `resources/app.asar` with an unpatched vanilla archive and automatically restarts `CurseForge.exe`. BetterCurseForge guarantees a **smooth, zero-delay transition** where you never lose your patch and the unpatched app is never shown on screen:

```mermaid
flowchart TD
    A[CurseForge Launcher Update] -->|Overwolf installer replaces files| B[Installer Attempts to Launch Vanilla App]
    B -->|Active Interceptor <50ms| C[Vanilla Launcher Suppressed Silently]
    C -->|Auto-Repatch Triggered| D[Dedicated Splash Updater GUI Appears]
    D -->|Real-time Status & Progress| E[Offline Extraction & Patching <3s]
    E -->|Synchronize OWEASARSIG| F[CurseForge.exe Integrity Signature Updated]
    F -->|Autonomous Relaunch| G[Modded BetterCurseForge Launches Ready!]
```

1. **Active Vanilla Interceptor**: When an update or unpatched state is detected, BetterCurseForge polls in tight 150ms slices using lightweight Win32 kernel process enumeration. If the installer starts `CurseForge.exe`, it is terminated within 50ms before Chromium or Electron can render a single frame—guaranteeing the unpatched client never flashes on screen.
2. **Dedicated Splash Updater GUI**: Rather than patching silently without visual feedback, BetterCurseForge displays a sleek, centered dark-themed card (`#121214`) featuring the official application icon, an animated purple progress bar, and real-time status updates (*"Waiting for installer..."*, *"Extracting application archive..."*, *"Unlocking native premium themes..."*, *"Injecting zero-ad rules..."*, *"Updating security signatures..."*).
3. **Global Mutex Synchronization**: Uses Windows kernel named mutexes (`BetterCurseForgePatchMutex`, `BetterCurseForgeSplashMutex`) to guarantee atomic, single-process patching with zero race conditions or duplicate windows.
4. **Resilient Win32 Watcher Daemon**: A silent background process monitors CurseForge's installation directory with 0% CPU consumption during idle. It triggers the splash updater whenever an update is applied and handles all persistence automatically.
5. **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`:

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

```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

```powershell
# Clone the repository
git clone https://github.com/tomasalias/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

```powershell
cd docs
npm install
npm run dev
```

---

## 📄 License

This project is licensed under the [MIT License](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.