172 lines
7.1 KiB
Markdown
172 lines
7.1 KiB
Markdown
# 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)
|
||
[](https://github.com)
|
||
[](#features)
|
||
[](#-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).
|
||
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/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.
|