Community Add-ons

Add-ons are optional extensions you install from a community catalogue. There are two kinds:

• Metadata scrapers look a game system or a book up on an external source and offer to fill in its details, so you don't have to type publisher, year, licence, authors, and genre by hand.
• Character importers read a character built in another tool - a Forge Steel hero, a Pathbuilder export - and build it on one of Grimoire's character sheets. See Importing from other tools.

Settings → Add-ons lists each kind under its own heading.

The same community repository also publishes character sheets and the content packs they draw from. Those are installed from Characters → Manage sheets rather than here — see Characters.

Definitions live in the separate community-add-ons repository rather than inside Grimoire, so when a source changes its layout the fix is a community pull request — not a wait for the next Grimoire release.

Grimoire Codex DB, the community catalogue, is not an add-on: it is built in and needs no install. Once an admin sets GRIMOIRE_CODEX_DB_API_TOKEN, it appears first in Fetch metadata alongside any add-ons you install.

Books also get File metadata, built in as well: it reads the details a PDF, EPUB or comic carries inside itself - a PDF's title, author, subject, keywords, creation date, language and ISBN; an EPUB's title, authors, description, publisher, ISBN, subjects, language and date; or a comic's ComicInfo.xml (title, writer, artists, summary, publisher, genres, tags, links, language, date and ISBN). It needs no internet connection and is listed after your add-ons. Placeholder values that export tools leave behind, like a "Microsoft Word - draft.docx" title or an "Administrator" author, are skipped. As with any source, you review what it found before anything is applied.

Installing an add-on

Go to Settings → Add-ons (admin only).

1. Click Refresh. Grimoire fetches the catalogue from the index URL — by default the community repo.
2. Find the add-on you want and click Install.

Installed add-ons appear under Installed, where you can disable one temporarily or remove it entirely.

Keeping add-ons up to date

Add-ons change — that's rather the point of them living outside Grimoire. When a source redesigns its site or moves its data, the fix ships as a new version of the add-on rather than waiting for a Grimoire release.

When a newer version is available, the add-on is badged with it and an Update button appears. Update all does the lot in one go.

Updates that change a script

If an update changes an add-on's Python script, its approval is reset and you'll be asked to confirm again — even via Update all. You approved the old code, not the new code. Add-ons without scripts update silently.

Some updates need a newer version of Grimoire, for example a scraper that fills a field Grimoire didn't have before. Those aren't offered until you update Grimoire. An update that fails for any reason leaves the version you had installed and working.

An add-on you installed by hand isn't in the catalogue, so Grimoire can't tell when it changes; update it the same way you installed it.

Filling in metadata

1. Open a game system or a book and click Edit. While reading a book, you can instead open its details panel and click the pencil.
2. Click Fetch metadata.
3. Choose a source and confirm the search term (it starts as the system's name or the book's title).
4. Pick the right match from the results.
5. Review the changes and tick the ones you want, then Apply.

Each add-on works on one kind of thing, so the button only offers sources that suit what you're editing.

Links are added, never replaced

Fetching adds the source's own page to your links rather than replacing them, so anything you'd added yourself stays put. The dialog shows only the links being added.

Nothing is overwritten behind your back

Fields you have already filled in are not ticked by default. Only genuinely empty fields are pre-selected, and anything that conflicts is shown with your current value struck through so you can decide. Nothing is written until you press Apply.

Each row is labelled:

Label	Meaning
new	You have nothing here yet — ticked by default
differs	You already have a different value — left unticked
already set	Yours already matches — nothing to do

Because editions are usually separate entries upstream, searching a bare system name often returns several results. Pick the edition you actually own.

Filling in many at once

To work through a whole shelf, select the systems or books, open Bulk edit, and click Fetch metadata at the bottom of the editor (or press F). The dialog then stays open and walks through the selection for you:

• It searches for each item's name as soon as that item comes up, using the source you picked last.
• The top match is already focused, so Enter picks it. Use ↑ and ↓ to choose a different match, or ↑ from the first match to go back to the search box and change the search.
• On the review step, Enter presses Apply & next. That saves the ticked fields and moves on to the next item.
• The top of the dialog has the same item bar as the bulk editor. The right arrow skips to the next item without changing anything, and the left arrow goes back one item.
• The dialog keeps each item's search results, so going back shows the same matches without searching again, with the match you picked marked picked last time. If you picked the wrong one of two similar books, choose the right match. The fields the wrong match filled in are ticked for you, so applying replaces them.

When the top match is right, that makes each item two key presses: Enter to pick the match, Enter to apply it.

Outside the dialog, ← and → move between items whenever you aren't typing in a field.

Fetched fields are saved straight away

As in the single editor, Apply saves the fetched fields immediately. You don't need to press Save all afterwards, and closing the bulk editor without saving your other edits won't undo them.

When you already know which one

Searching a big catalogue can be fiddly — DriveThruRPG in particular returns a lot of near-misses for a well-known title. If you already have the item's page open on the source, you can skip searching entirely.

Click "Know the exact one? Paste a link or ID", paste the page's URL, and press Look up. It goes straight to the review step.

It accepts:

• a full page URL — https://www.drivethrurpg.com/en/product/170689/blades-in-the-dark
• a shorter one — drivethrurpg.com/product/170689
• just the ID — 170689

Any tracking or affiliate parameters on the end of a pasted link are ignored. If the text isn't a link for that source, you'll be told so rather than left waiting on a request that can't succeed.

Not every source offers this — the option only appears when the add-on knows how to read an ID out of that source's URLs.

Available sources

For game systems

Add-on	Source	Fills in
TTRPG Wiki	ttrpgwiki.com	Description, publisher, year, licence, system family, edition, genres, dice, tags, links

For books

Add-on	Source	Fills in
DriveThruRPG	drivethrurpg.com	Title, description, authors, artists, publisher, genres, ISBN, product code, year, links

DriveThruRPG's catalogue is enormous and full of third-party supplements, stock art, and translations, so searching a well-known title returns a lot of near-misses. Check the publisher shown next to each result before applying it — that's why it's there. A book sold only through its publisher's own store won't be found at all.

Character importers

Add-on	Reads	Builds on
Forge Steel	.ds-hero files from Forge Steel's Export	Draw Steel
Pathbuilder 2e	Pathbuilder 2e's Export JSON, saved as a file	Pathfinder 2e

Once an admin installs an importer, everyone on the server - guests included - can use it from Characters → Import a character. An importer that only reads uploaded files (both of these) doesn't need an admin at all: anyone can install it for their own account from that dialog. Importers that fetch links or run scripts stay admin-only. An import only ever creates a character in the importing person's own account.

More are welcome — see contributing below, and Writing a character importer for importers.

Add-ons that run code

Most add-ons are plain configuration files. Grimoire reads them itself, and no third-party code ever runs on your server.

A few sources are too awkward for that, so an add-on may include a Python script. Those run code on your machine, and Grimoire treats them accordingly. A scripted add-on runs only if you have:

1. Turned on Allow add-on scripts (off by default), and
2. Approved that specific add-on when installing it, in a dialog that names the script and shows its checksum.

Add-ons that include a script are labelled Runs code in the list.

When one does run, it runs in a separate short-lived process with a time limit and no access to your database — so a buggy add-on can't take Grimoire down with it. That contains accidents, but it is not a full sandbox: a script can still reach the network and read files your server can read.

Treat it like any other program

Installing a scripted add-on is like running software someone sent you. Only install ones you trust. Every add-on's source is public in the community repo precisely so it can be read before you install it — and downloads are checked against a checksum, so a tampered file is refused.

If an add-on updates and its script changed, approval resets and you'll be asked again.

Using a private add-on

You don't have to publish an add-on to use it. Put its folder in DATA_PATH/add-ons/<id>/ and restart Grimoire; it appears alongside the rest.

To test one you're developing, serve the repo locally:

python3 -m http.server 8000

Then set the index URL to http://localhost:8000/index.json and hit Refresh.

Using a private repository

A source can be a private repository - licensed or non-SRD content packs for your table, say. Give it an access token and Grimoire browses, installs and updates from it like any other source, update badges and Update all included.

1. Add the repository's index URL under Settings → Add-ons → Add-on Sources.
2. Click the key beside it, paste the token, and click Save token. The source is marked Private.

The token covers everything that source offers: add-ons, character sheets, content packs, themes and note templates.

Grimoire sends the token only to files inside that source - the same site, under the folder holding its index. A private repository on GitHub does not hand its token to the public community repository, a redirect elsewhere drops it, and an add-on's lookups on other sites never carry it.

The token is stored encrypted and never shown again; the dialog can only replace or remove it. Removing the source removes its token too.

GitHub

Use the repository's raw URL, for example https://raw.githubusercontent.com/our-table/packs/main/index.json. Create a fine-grained personal access token with Only select repositories set to that one repository and Contents set to read-only. Fine-grained tokens usually expire, so replace yours before it does.

Gitea and Forgejo

Use the API's raw URL, which serves the default branch: https://git.example.org/api/v1/repos/our-table/packs/raw/index.json. Create a token under Settings → Applications with read access to repositories.

Other hosts

Any host that serves the repository's files at stable URLs works. If it expects the token under a different header - GitLab's PRIVATE-TOKEN, say - change Header in the dialog. By default the token is sent as Authorization: Bearer <token>; a token you type with its own scheme (token abc123) is sent as typed.

To set tokens on the server instead, use ADDON_INDEX_CREDENTIALS. A token set there shows as read-only in the dialog.

Writing your own

The add-ons repo has the authoring reference. In short, a scraper is a small YAML file describing where the data lives, how to match a search against it, and how its fields map onto Grimoire's:

id: my-source
name: My Source
version: 1.0.0
kind: scraper
target: game-system

source:
  url: https://example.com/data.json
  format: json
  cache_ttl: 86400

search:
  fields:
    - { field: name, weight: 1.0, strategy: fuzzy }
  identity: { from: id }
  label: { template: "{name} ({edition})" }

map:
  description: { from: summary }
  year: { from: released }
  publishers: { from: publisher, as: link_list }

Contributions are welcome. Please respect the source you're scraping: check its terms, set a generous cache_ttl, prefer a bulk endpoint over hammering individual pages, and credit it with an attribution line.

Frequently asked

Does fetching metadata overwrite my edits? No. Fetching only shows you a comparison. Nothing changes until you tick fields and press Apply, and fields you've already filled in start unticked.

Will it change my page count or file size? No. Those are read from your actual file when the library is scanned, which is more trustworthy than a store listing, so no scraper maps them.

How often does it hit the source? As little as it can. Where a source publishes its whole catalogue in one file (TTRPG Wiki), Grimoire downloads it once and caches it — typically a single request per day covers every lookup, and the cached copy keeps working if the source goes down. Where it has to search (DriveThruRPG), each search is one request, cached for an hour, plus one more when you pick a result.

Can players use this? No. Fetching metadata requires the GM or admin role, and managing add-ons is admin-only.

An add-on stopped working. The source probably changed. Open an issue on the add-ons repo — the definition can be fixed there without updating Grimoire.