# @punktfunk/plugin-heroic

Adds your installed **Heroic Games Launcher** titles to a Punktfunk host's library — Epic, GOG and
Amazon in one source, with their cover art, and with the session ending when you quit the game.

Install it from the host's plugin store (**Library → Game sources → Add a source**), or:

```sh
punktfunk-host plugins add heroic
```

Nothing to configure: it finds Heroic's config folder in the usual places (`$XDG_CONFIG_HOME/heroic`,
`~/.config/heroic`, Flatpak) and reads the library caches from there. If yours lives somewhere else,
set the path in **Library → Game sources → Heroic → Settings**.

## What it replaces

Punktfunk used to scan Heroic from inside the host. This plugin is that scanner, lifted out — so you
install it only if you use Heroic, and it can be updated without updating the host.

It claims the `heroic` store, which means your games keep **exactly** the ids they had before
(`heroic:legendary:<appName>`): Moonlight pins, cached box art, and your enabled/disabled state all
carry over, and the host's built-in scanner switches itself off while this is installed. Remove the
plugin and the built-in comes straight back.

## What gets listed

Only titles Heroic reports as installed **and** whose install directory still exists — the second
check works around Heroic's GOG `is_installed` bug
([#2691](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher/issues/2691)), which otherwise
leaves uninstalled games sitting in your library.

Art comes straight from Heroic's cached CDN URLs, so the client fetches it directly. A sideloaded
title whose art is a local `file://` path is listed without art rather than with a picture nothing
can load.

## Commands

```sh
punktfunk-plugin-heroic detect            # is Heroic installed on this host?
punktfunk-plugin-heroic scan --preview    # what WOULD be synced, as JSON (works with no host)
punktfunk-plugin-heroic uninstall         # drop the games and release the store claim
```

## Parity — the release gate

Unit tests pin the parsing. What actually has to hold is that this plugin reproduces the in-host
scanner it replaces, down to the ids — one that parses perfectly but emits a subtly different
`external_id` breaks every Moonlight pin on the host, and no unit test notices.

So, on a box with Heroic installed, **before** installing this plugin:

```sh
punktfunk-plugin-heroic parity --snapshot before.json   # host still on its built-in scanner
punktfunk-plugin-heroic parity --compare  before.json   # offline; exits non-zero on any difference
```

`--compare` runs this plugin's own scan and diffs it: ids, titles, launch recipes, roles and
metadata exactly; art by **presence, not value**.

Worth re-checking on-glass specifically: a game launched under **Proton**. Heroic hands off to
legendary/gogdl/nile, so the `HEROIC_APP_NAME` environment marker is what lets the host recognise
the running game and end the session when you quit it.

Do not publish a version whose parity run is red.

## Development

```sh
bun install
bun run typecheck && bun test && bun run build
```

The framework — store claim, sync engine, `__config`, CLI verbs, and the launcher-file parsers —
lives in [`@punktfunk/plugin-kit/library`](https://git.unom.io/unom/punktfunk/src/branch/main/plugin-kit).
This package is the Heroic-specific part: find the config root, read the three `store_cache`
libraries, map entries. See `design/library-scanner-plugins.md` in the main repo.

## License

MIT OR Apache-2.0.