@punktfunk/plugin-itch

Adds the games the itch.io app installed to a Punktfunk host's library — with their cover art, launched straight from their install folder, 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:

punktfunk-host plugins add itch

Nothing to configure on Linux: it finds butler's database in the usual places ($XDG_CONFIG_HOME/itch, ~/.config/itch, Flatpak) and syncs from there. If yours lives somewhere else, set the path in Library → Game sources → itch.io → Settings.

What is read

The itch app keeps its library in butler's SQLite database, butler.db, which the plugin opens read-only. Installed games (butler's caves) are joined to their games and install locations:

Host Database
Linux ~/.config/itch/db/butler.db, Flatpak ~/.var/app/io.itch.itch/config/itch/db/butler.db
Windows C:\Users\<name>\AppData\Roaming\itch\db\butler.db, every profile tried
Setting Meaning
databasePath Absolute path to butler.db. Leave empty to find it automatically.

What gets listed

Only caves whose game is classified game and whose butler verdict holds an executable this host runs directly: a native Linux binary (64-bit preferred) or a shell script on Linux; a native Windows binary or a batch script on Windows. Browser (html), Java (jar) and LÖVE games need the itch app's own runtime and are skipped, as is any cave whose executable is no longer on disk.

Each title launches its own executable from its install folder, so the host owns the process and knows when the game exits. Art is the game's still cover (or its cover) from itch's CDN.

This store never had a built-in host scanner, so the kit's parity verb has no baseline here.

Windows: the itch folders

The itch app keeps its database in your profile. The manifest names its folder, %AppData%\itch\db, by its own files: a current host opens it to the plugin when it installs, and an older host asks for it under Library → Game sources, where Allow is all it takes. The install location, %AppData%\itch\apps by default, is asked for the same way: the host runs each game from there, so it needs the whole folder. Until the database is readable detect reports absent and nothing syncs.

Commands

punktfunk-plugin-itch detect            # is a readable butler.db on this host?
punktfunk-plugin-itch scan --preview    # what WOULD be synced, as JSON (works with no host)
punktfunk-plugin-itch uninstall         # drop the games and release the store claim

Development

bun install
bun run typecheck && bun test && bun run build

This plugin needs @punktfunk/plugin-kit 0.4.5 (the launch field). The lockfile is regenerated once the kit is published.

The framework — store claim, sync engine, __config, CLI verbs, and the launcher-file parsers — lives in @punktfunk/plugin-kit/library. This package is the itch-specific part: find butler.db, read it, map caves to entries, answer the host's launch-time ask. See design/library-scanner-plugins.md in the main repo.

Use of AI

This project uses AI for writing code.

License

MIT OR Apache-2.0.

S
Description
A Punktfunk plugin that adds the games installed by the itch app as a library source
Readme
151 KiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 100%