166 lines
6.1 KiB
Markdown
166 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.
|