# BetterCurseForge

<div align="center">

<img src="docs/public/logo.svg" 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)
[![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:
  - 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](https://github.com).
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
```

---

## 🔄 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:

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

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

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