165 lines
6.1 KiB
Markdown
165 lines
6.1 KiB
Markdown
# 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)
|
||
[](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:
|
||
- 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.
|