# Fantasy Hero 6E Compendium

A Foundry VTT module with compendiums of fantasy creatures, creature options and equipment for the [Hero System 6e (Unofficial) v2](https://github.com/dmdorman/hero6e-foundryvtt) system. It's built from Hero Designer files: the HERO System Bestiary's creatures and option packages, and the Fantasy Hero equipment prefabs.

> **Private content.** The compendiums contain material from Hero Games products. This repository and its releases are private; don't publish or share them.

## Compendiums

All four sit in a **Fantasy Hero 6E** folder in the Compendium sidebar.

| Compendium | Contents | Players can see it |
|---|---|---|
| **Bestiary Creatures** | 401 creatures from the Bestiary's monster, humanoid, world-myth and animal chapters, foldered by chapter and creature family | Yes |
| **Bestiary Templates and Options** | The Bestiary's option packages (e.g. Draconic Powers), creature and humanoid templates, and animal complications | Yes |
| **Fantasy Hero Equipment** | Armor, clothing, weapons, shields, herbs, ioun stones, food, livestock and miscellaneous gear, plus the **TONS Magic Items** folder (101 campaign magic items in 8 categories) | Yes |
| **Grimoire Spells** | 727 spells from *The HERO System Grimoire*, foldered by arcanum (college) and then power type (Attack, Defense, Movement, Multipowers...) | Yes |

The Bestiary's sci-fi and modern monsters (its chapter 5) are left out, and so are the Grimoire's Cybermancy and Superheroic Thaumaturgy.

- **Built by hero6e:** each creature and item was made by hero6e's own Hero Designer import, so it matches an uploaded `.hdc`. Creatures keep their Hero Designer data, so Hero Workshop can edit them.
- **Compound equipment:** most equipment is a compound power, and each stays a single item. When one is dropped onto a character, Hero Workshop adds its parts, which is how hero6e shows compounds.
- **Creature abilities for players:** players can open a creature from the compendium and drag its powers, skills or other abilities onto their own character (with Hero Workshop 0.4.7 or later, which lets anyone who can see a sheet drag from it). To keep the Bestiary hidden, set the two Bestiary compendiums' player ownership to None in Foundry's compendium settings.
- **Icons:** they come from Foundry's built-in icon library, chosen by name.

## Requirements

- Foundry VTT v14
- Hero System 6e (Unofficial) v2 (`hero6efoundryvttv2`) 5.x
- [Hero Workshop](https://github.com/ByronWLong/hero-workshop) 0.4.7 or later

## Install

Foundry can't install from a private repository's manifest URL, so install it by hand:

1. While signed in to GitHub, download `fantasy-hero-6e-compendium.zip` from the repository's latest release.
2. Unzip it into `<Foundry data>/Data/modules/`, so you have `Data/modules/fantasy-hero-6e-compendium/module.json`.
3. Restart Foundry, then enable **Fantasy Hero 6E Compendium** (and Hero Workshop) in your world.

To update, replace the folder with a newer release's zip.

## Building

The compendiums are generated in a running Foundry, so every document is exactly what hero6e makes from the Hero Designer files. The repository keeps them as JSON in `src/packs`; releases compile that JSON into Foundry's pack format.

```bash
npm install
npm run compile        # src/packs (JSON) → packs/ (what Foundry reads)
```

### Rebuilding from the Hero Designer files

Requirements:
- The source files:
  - `HSB HD Files` (the Bestiary) and `Prefabs` (the Fantasy Hero equipment), both under `HD_ROOT`;
  - `HD_ROOT` defaults to `E:/Hero Designer/Hero Designer 6`.
- A Foundry v14 server at `FOUNDRY_URL` (default `http://localhost:30000`). It needs:
  - hero6e and Hero Workshop installed;
  - a world `FOUNDRY_WORLD` (default `test-hero-system`) with a passwordless `Gamemaster` user;
  - this folder linked as `Data/modules/fantasy-hero-6e-compendium`.
- Microsoft Edge, which Playwright drives.
- Foundry's `public` folder at `FOUNDRY_PUBLIC`, for the icon library.

```bash
npm run build:packs                                      # everything
node tools/build-packs.mjs --only=equipment              # one compendium
node tools/build-packs.mjs --only=creatures --limit=5    # a quick trial
node tools/build-packs.mjs "--sources=WEREWOLF|ERINYES"  # rebuild matching creatures in place
```

The script does the following:
1. Empties the packs.
2. Repairs each source file for hero6e with Hero Workshop's `repairForFoundry`:
   - Combat Skill Levels are linked to the attacks their text names.
   - Adjustment targets are made comma-separated.
   - "Usable As" movement is named.
3. Imports each file through hero6e and Hero Workshop.
4. Writes two reports:
   - `tools/repair-report.md`: what was repaired, and what needs a person to check.
   - `tools/icon-report.tsv`: every icon choice.
5. Shuts the world down.
6. Extracts the packs to `src/packs`.

Document IDs are derived from each entry's source file and Hero Designer ID, so a rebuild keeps them stable.

**Fixing icons:** add entries to `tools/icon-overrides.json`, then rebuild. A key is an item's name, or `kind:name` to limit it to one kind of entry (`creature`, `equipment`, `power`, `skill`, `perk`, `talent`, `complication`). The value is a path under Foundry's `icons/` folder:

```json
{
  "Longsword": "icons/weapons/swords/sword-guard-bronze.webp",
  "creature:Grizzly Bear": "icons/creatures/abilities/bear-roar-bite-brown.webp"
}
```

### TONS magic items

The TONS campaign's magic items are written by hand in `tools/tons/items.mjs`, one definition per item. Each definition holds the item's powers, modifiers and charges, built from the "Extracted Magic Items" document. Items it gives no stats for are description-only placeholders.

`node tools/tons/generate.mjs` turns the definitions into Hero Designer prefabs in `sources/tons/` (one per category). The build then imports those under **TONS Magic Items**.

The generator also writes `tools/tons/review.md`. It lists each item's built Active and Real cost beside the figure in the document, and notes every modeling call to check. Edit a definition, regenerate, then rebuild the equipment compendium with `node tools/build-packs.mjs --only=equipment`.

### Grimoire spells

The spells are read from the PDF of *The HERO System Grimoire* (6th Edition), which isn't in this repo:

1. `python tools/grimoire/columns.py <Grimoire.pdf> <stream.txt>` reads the two-column pages in order (needs `pip install pdfplumber`).
2. `python tools/grimoire/parse.py <stream.txt> tools/grimoire/spells.json` splits the text into spells: header, description, build and options.
3. `node tools/grimoire/generate.mjs` turns each build into Hero Designer data (`tools/grimoire/convert.mjs`) and writes `sources/grimoire/<Arcanum>/<Power Type>.hdp`.
4. `node tools/build-packs.mjs --only=spells` builds the compendium.

The converter matches each power and modifier to Hero Designer's catalog by name. Every modifier keeps the value the book prints, and limitations the catalog lacks become custom modifiers. Power details it can't read (No Fringe, a Summon's extras) are priced from the book's Active Points in an adder named by the text. 5E's Suppress and Boost become Drain and Aid, and NND becomes Attack Versus Alternate Defense with All Or Nothing. Spells that grant a power to others are built as the granted power, with the casting cost in their notes.

`tools/grimoire/review.md` lists each spell whose cost differs from the book's or that needed a judgment call.

Each spell's Hero Designer IDs come from a block of its own, chosen by a hash of its arcanum and name. Changing one spell therefore leaves the other spells' IDs, and their compendium document IDs, unchanged.

### Releasing

Push a tag named `v<version>` (e.g. `v0.1.0`). The release workflow compiles the packs and attaches `fantasy-hero-6e-compendium.zip` to a GitHub release.