BetterCurseForge/README.md

# BetterCurseForge

<img src="assets/icon_512.png" alt="BetterCurseForge logo" width="96" height="96" />

A patch for the CurseForge launcher on Windows. It blocks ads, adds a theme and plugin system, unlocks the subscriber-only skins, and re-applies itself after CurseForge updates.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## What it does

- **Ad blocking.** Requests to the Overwolf, Adrta and DoubleClick ad servers are blocked at the Electron session level, and some CSS collapses whatever empty ad frames and banners are left. Ad elements are hidden, not removed from the DOM, because removing them breaks React and causes `insertBefore` errors.
- **Themes.** Themes show up in the launcher's own Settings > Themes page. CSS is injected live, so you don't need to restart to see changes. One theme is included, Purple Night.
- **Subscriber skins.** The official skins that normally need a CurseForge subscription (PixelForge, LifeForge, FantasyForge, Halloween and the rest) are unlocked.
- **Plugins.** Plugins are small JS modules with `onEnable` and `onDisable` hooks, scoped styling, and IPC to the main process. There's a sample one called Compact Mode.
- **Updates.** When CurseForge updates itself, the patch gets re-applied automatically. More on that [below](#how-the-repatch-works).

## Install

1. Download `BetterCurseForge.exe` from [Releases](http://92.5.113.44:3000/tomasalias/BetterCurseForge/releases).
2. Run it and click **Patch CurseForge**.
3. Start CurseForge as usual.

It also works from PowerShell or Command Prompt:

```bash
# show patch and watcher status
.\BetterCurseForge.exe status

# apply the patch
.\BetterCurseForge.exe patch

# go back to stock CurseForge
.\BetterCurseForge.exe unpatch

# run the background watcher in the foreground
.\BetterCurseForge.exe watch

# open the splash updater by hand
.\BetterCurseForge.exe --repatch-splash
```

## How the repatch works

When CurseForge downloads an update, the Overwolf installer overwrites `resources/app.asar` with a stock copy and relaunches `CurseForge.exe`. That undoes the patch, and the unpatched launcher would normally appear on screen. BetterCurseForge deals with it like this:

A small watcher process sits in the background and watches CurseForge's install directory. When it sees an update or an unpatched `app.asar`, it polls for a new `CurseForge.exe` every 150 ms and kills the one the installer starts, so the vanilla launcher never gets drawn. Then it opens a splash window with a progress bar and runs the repatch.

The repatch unpacks and repacks `app.asar` using the Node runtime that ships inside CurseForge (`ELECTRON_RUN_AS_NODE=1`), so it needs no internet connection and no separate Node install. It takes a few seconds. It also updates the `OWEASARSIG` integrity signature stored in `CurseForge.exe` to match the new archive. When that's done, CurseForge relaunches.

Two named Windows mutexes, `BetterCurseForgePatchMutex` and `BetterCurseForgeSplashMutex`, stop two patch runs or two splash windows from happening at the same time.

## Themes and plugins

Everything user-facing lives in `%APPDATA%\CurseForge\BetterCurseForge\`:

```
themes/
  purple-night.css
  purple-night.json
plugins/
  compact-mode/
    manifest.json
    index.js
```

The GUI has **Open Themes Folder** and **Open Plugins Folder** buttons if you don't want to dig for it.

### Writing a theme

A theme is a CSS file plus a JSON manifest with the same name. For example, `themes/my-theme.json`:

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

and `themes/my-theme.css`:

```css
:root {
  --surface-brand-brand: #10b981 !important;
  --surface-brand-brand-hover: #059669 !important;
}
```

### Writing a plugin

A plugin lives in its own subfolder, `plugins/<plugin-name>/`, with a `manifest.json`, an `index.js`, and optionally a `styles.css`.

`plugins/my-plugin/manifest.json`:

```json
{
  "name": "My Plugin",
  "description": "Custom tweak for CurseForge",
  "version": "1.0.0",
  "author": "Your Name",
  "main": "index.js",
  "styles": "styles.css"
}
```

`plugins/my-plugin/index.js`:

```javascript
// Plugins run inside the Electron renderer with access to BetterCurseForge
const { injectCSS, patcher, settings, on, off } = BetterCurseForge;

console.log("My plugin loaded");

// Cleanup when toggled off
plugin.onDisable = () => {
  console.log("My plugin disabled");
};
```

#### What plugins can do

- **UI and DOM tweaks.** Add buttons, badges, links or panels with the normal DOM APIs. If the plugin folder has a `styles.css`, it's injected when the plugin is enabled and removed when it's disabled.
- **Method patching.** Hook into or replace internal JavaScript functions with `BetterCurseForge.patcher.before()`, `after()` or `instead()`.
- **Persistent settings.** Save and read preferences across restarts with `BetterCurseForge.settings.get(key)` and `set(key, value)`.
- **Events.** Listen for app lifecycle events with `BetterCurseForge.on(event, callback)`.

## Building from source

You need Windows 10 or 11 and Python 3.10+. Node.js 20+ is only needed if you want to run the docs site.

```powershell
git clone http://92.5.113.44:3000/tomasalias/BetterCurseForge.git
cd BetterCurseForge

python -m pip install pyinstaller
python -m PyInstaller BetterCurseForge.spec --noconfirm
```

The executable ends up in `dist/BetterCurseForge.exe`.

### Syncing changes

To pull changes:

```powershell
git pull origin master
```

If you have local changes that conflict:

```powershell
git stash
git pull origin master
git stash pop
```

To push your local changes:

```powershell
git add .
git commit -m "Description of changes"
git push origin master
```

To run the VitePress docs locally:

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

## License

[MIT](LICENSE).

CurseForge and Overwolf are trademarks of their respective owners. This is an independent open-source project and isn't affiliated with or endorsed by either of them.