HLO Importer Alpha
A Foundry VTT module that imports HeroLab Online characters directly into Pathfinder 2e and Starfinder 2e games. From-scratch modernization of the dormant zarmstrong/hlo-importer, built to last.
What this is
| Module ID | hlo-importer-abyssal-engine |
| HLO API tool name | HeroLab to Foundry - Powered by Abyssal Engine |
| Author | Shinra CC |
| License | MIT |
| Foundry compatibility | V13 minimum, V14.361 verified, V14 maximum |
| Target systems | pf2e, sf2e |
| Source repository | github.com/ShinraEngineer/hlo-importer-abyssal-engine |
| Bug tracker | GitHub Issues |
Why this exists
This module exists because the previous two, zarmstrong's hlo-importer and its companion conversion service, are dead. They served the Pathfinder 2e Foundry community well from 2020 through September 2022, and then they stopped. The PHP backend was the single point of failure, and once it stopped getting updated the whole pipeline froze at PF2e Foundry data version 3.13.5. Anyone running a current Foundry world has been stuck pasting characters by hand for years.
The slot is empty, nobody else has stepped up to fill it, and the people who would benefit have been quietly going without. So I'm building it again, properly this time: the conversion logic lives inside the module, there is no third-party service in the critical path, and Starfinder 2e is supported from day one rather than bolted on later.
Install
The module is in alpha. It is not yet published to the Foundry package registry. To try the current build:
Install via Manifest URL (recommended)
Inside Foundry V13.351 or V14.361, open Add-on Modules, click Install Module, and paste this URL into the Manifest URL field:
https://shinra.cc/hlo-importer-abyssal-engine/module.json
Or direct download
Download the latest release zip:
Unzip into your Foundry user data folder at Data/modules/hlo-importer-abyssal-engine/ and enable the module in a PF2e or SF2e world.
Roadmap
The full phased roadmap with per-commit detail lives in the changelog. At a glance:
| Phase | Scope | Status |
|---|---|---|
| 0 | Repo scaffolding and Foundry module skeleton. | Done |
| 1 | JSON-paste parser, matcher, PF2e actor builder, ApplicationV2 dialog. | Done |
| 2 | Full compset coverage (feats, spells, weapons, armor, gear, augmentations). | Done |
| 3 | SF2e actor builder, attachment handling, Lore items, matcher polish. | Done |
| 4 | Direct HLO Public API (element token mode) with cached access token. | Done |
| 5 | Upload-JSON file picker mode. | Done |
| 6 | Polish: live Foundry verification, public release, Foundry package registry submission. | In progress |
| 7+ | Future: SignalR live sync, bulk import, differential re-import, custom HLO content. | Future |
Architecture
The Foundry module sends a request directly to https://api.herolab.online, runs the response through an in-module parser, then through an in-module compendium matcher (hybrid strategy: slug-first, fuzzy-name second, curated overrides third), then through an in-module Foundry actor builder, and finally hands the result to Actor.create() (or Actor.update() for re-imports). There is no third-party hosted service in the critical path.
Three input modes feed the same parser:
- Element Token (API): primary UX. Paste your HLO User Token once in module settings; paste a per-character Element Token at import time; the module fetches and converts.
- Paste JSON: air-gapped fallback. Paste an HLO export directly into a textarea.
- Upload File: file-picker variant of paste. Drag in the downloaded HLO .json.
The matcher draws on the PF2e and SF2e compendium packs in the active Foundry system, with optional pf2e-anachronism and sf2e-anachronism module packs as cross-system fallback. The slug-first strategy catches the easy hits; a curated overrides table handles the long tail of HLO-to-Foundry name drift (seeded from 134 versions of zarmstrong's conversion-service changelog). Unmatched items appear in the conversion log so users can patch manually.
Documentation
| README | User-facing project intro and quickstart. |
| Changelog | Every release and what changed in it. |
| License | MIT plus trademark acknowledgements. |
| Legal & Attribution | Full trademark and licensing disclosure for Hero Lab, Paizo, and Foundry VTT. |
| Contributor guide | Developer reference for adding compset handlers, matcher overrides, and HP table entries. |
| Handoff document | The architectural source-of-truth. |
Support & Contact
If the module saves you time and you want to send a token of appreciation, the Ko-Fi tip jar is open:
For direct contact, Discord (shinra.engineer) is the fastest route. For bugs or feature requests, file a GitHub Issue; the bug tracker is the canonical place to raise concerns and offers the highest-bandwidth back-and-forth on technical details.
The HLO Importer (Powered by Abyssal Engine) is a from-scratch reimplementation of zarmstrong/hlo-importer (MIT) and its companion conversion service. The original served the Pathfinder 2e Foundry community from 2020 through 2022 and is now dormant. No source code is redistributed from those projects.
Hero Lab and the Hero Lab logo are registered trademarks of LWD Technology, Inc. Pathfinder, Starfinder, and associated trademarks are property of Paizo Inc. Foundry Virtual Tabletop is a trademark of Foundry Gaming, LLC. This project is not affiliated with, endorsed by, or sponsored by any of these companies.