🎨 Daggerheart: Art Mapper

Bring your own artwork to the Daggerheart system. Drop image files into the module's folders, click one button, and the module matches them to compendium entries by name — adversaries, environments, classes, subclasses, ancestries, communities, domain cards, druid beastforms, and compendiums from any other module you choose.

The module ships no artwork. It is a mapper, not an art pack. The folders arrive empty and you fill them with the images you own or have made.

✨ Features

• Compendium Art Mapping
  Scans your image folders and applies the art to the matching compendium entries. Matching is by document name, so there is no ID list to maintain.
• Beastform Art
  Gives druid wild shapes a gallery to choose from at transformation time. Works for players even though they cannot browse the server's filesystem, and it never modifies the Daggerheart system compendium.
• Actor Image Sync
  Compendium art does not reach items already sitting on an actor. This scans world actors and updates only those items whose image is still the system default.
• Custom Compendiums
  Extends everything above to Actor or Item compendiums shipped by other modules — homebrew adversary packs, extra domain cards, and so on.
• Native Foundry integration
  Registers through Foundry's own Compendium Art system, so the core Compendium Art screen controls it: per-category toggles and priority against other art modules.

📋 Requirements

🚀 Quick Start

1. Enable the module. On first load it creates the folder structure and asks you to reload.
2. Put your images into the folders (see below). Filenames must start with the entry's name.
3. Open Game Settings → Configure Settings → Daggerheart: Art Mapper and click Regenerate Art Mappings.
4. Reload when prompted. Your art is now on the compendium entries.

Repeat steps 2–4 whenever you add or rename images.

🗂️ How to Organize Your Assets

1. Put images in the matching folder. See the structure below.

2. Name your images after the entry. The filename must start with the document's name. All of these match an adversary called Dread Knight:

dread-knight.webp      dread_knight.webp      Dread Knight.webp
dread-knight-1.webp    Dread-Knight2.webp     dread knight 03.webp

Matching is lenient — spaces, hyphens and underscores all work, and capitalisation is ignored. The bundled art follows one convention, and copying it is the safest choice:

Dread-Knight_1.webp    ← hyphens between words, "_" before the number

⚠️ Why the separator before the number matters. "Merchant" and "Merchant Baron" are both adversaries, and so are "Tangle Bramble" and "Tangle Bramble Swarm". When one entry's name starts another's, a number placed straight after the name makes the shorter entry's wildcard swallow the longer entry's images — Merchant* also matches Merchant-Baron1.webp. Keeping the number on a separator that never appears between words fixes it:

Merchant_1.webp   Merchant_2.webp          ← "Merchant_*" stops here
Merchant-Baron_1.webp                      ← never reached by "Merchant_*"

Name a prefix pair so it shares a plain prefix and the module refuses to guess: the shorter entry drops to a single fixed image, and a warning naming both entries appears in the console (F12). Only prefix pairs can actually break, but using _ everywhere means never having to check which entry names are prefixes of which.

3. Supported formats. Every image format Foundry supports — PNG, JPG, WebP, and so on.

4. Multiple images per entry. In token/ folders, add more than one file for the same entry (dread-knight_1.webp, dread-knight_2.webp) and the module builds a wildcard path with Foundry's native Randomize Wildcard Images flag on that entry's prototype token. This is Foundry's own feature, not custom logic: each time you drop the actor on a scene, Foundry picks one of the matching images for that token.

Keep capitalisation consistent inside one entry's set. Zumbi_1.png and zumbi_2.png are matched to the same entry, but Foundry's server resolves the wildcard case-sensitively, so no single pattern covers both. The module falls back to one fixed image and says so in the console. Pick one casing per entry and stick to it.

5. Regenerate. Click Regenerate Art Mappings to apply changes.

📌 Your files are safe. Everything inside storage/ — your images and the module's generated files — is preserved across module updates. The module never deletes or rewrites images you added.

📁 Folder Structure

storage/
├── assets/
│   ├── adversary/
│   │   ├── portrait/          → daggerheart.adversaries (actor portraits)
│   │   └── token/             → daggerheart.adversaries (token images)
│   ├── ancestry/              → daggerheart.ancestries (item art)
│   ├── class/                 → daggerheart.classes (item art)
│   ├── community/             → daggerheart.communities (item art)
│   ├── domain-card/           → daggerheart.domains (item art)
│   ├── environment/
│   │   ├── portrait/          → daggerheart.environments (actor portraits)
│   │   └── token/             → daggerheart.environments (token images)
│   ├── subclass/              → daggerheart.subclasses (item art)
│   └── druid-transformation/  → beastform galleries, by tier
│       ├── tier1/
│       │   ├── agile-scout/         ├── tier3/
│       │   ├── aquatic-scout/       │   ├── aquatic-predator/
│       │   ├── household-friend/    │   ├── great-predator/
│       │   ├── nimble-grazer/       │   ├── great-winged-beast/
│       │   ├── pack-predator/       │   ├── legendary-beast/
│       │   └── stalking-arachnid/   │   ├── legendary-hybrid/
│       ├── tier2/                   │   └── mighty-lizard/
│       │   ├── armored-sentry/      └── tier4/
│       │   ├── mighty-strider/          ├── epic-aquatic-beast/
│       │   ├── pouncing-predator/       ├── massive-behemoth/
│       │   ├── powerful-beast/          ├── mythic-aerial-hunter/
│       │   ├── striking-serpent/        ├── mythic-beast/
│       │   └── winged-beast/            ├── mythic-hybrid/
│       │                                └── terrible-lizard/
└── custom/                    → folders for compendiums from other modules

Every folder is kebab-case. Beastform folders are the form's name lowercased with spaces turned into hyphens — "Agile Scout" → agile-scout, "Great Winged Beast" → great-winged-beast.

🐺 Beastform Art

🔍 What it does

Each beastform gets its own folder. Put any number of images in it, and when a druid transforms into that form the module shows Daggerheart's image picker filled with your gallery, letting the player choose which one their token becomes.

🛠️ How to use it

1. Drop images into the folder for each form — e.g. druid-transformation/tier1/agile-scout/.
2. As GM, click Regenerate Art Mappings.
3. Done. Players pick from the gallery on their next transformation; no reload needed on their side beyond the usual one.

🧩 Notable behaviour

• Empty folders are left alone. A form with no images keeps Daggerheart's own artwork and transforms exactly as it does without this module. You can fill in as few or as many forms as you like.
• Players do not need extra permissions. Listing server files requires the Browse File Explorer permission, which players do not have by default. The GM does the scanning once and the result is published as a small file every client can simply read, so nothing is asked of players.
• The system compendium is never modified. The gallery is supplied at transformation time. If you uninstall this module, every beastform reverts to its stock artwork with nothing left behind and no broken image paths — in this world or any other world on your server.
• Evolved and hybrid forms are supported exactly like the normal ones, each with its own folder.

📦 Custom Compendiums (Other Modules)

🔍 What it does

The standard folders cover the Daggerheart system's own compendiums. Custom Compendiums extends the same "drop an image, the name matches, the art is applied" workflow to Actor or Item compendiums from any other active module.

🛠️ How to use it

1. Open Manage Custom Compendiums in the module settings.
2. Every active Actor or Item compendium not already built in is listed, unchecked.
3. Check the ones you want and click Save. The subfolders are created under storage/custom/, and the dialog shows the exact folder name.
   

   The folder name is generated by the module and cannot be renamed. This keeps names short and guarantees two compendiums never point at the same folder by mistake.

4. Add images, following the same naming rule as everywhere else.
5. Click Regenerate Art Mappings.

📐 Folder shape

• Actor compendiums get portrait/ and token/ subfolders, like Adversaries and Environments.
• Item compendiums get one flat folder. This works even when a pack mixes several item subtypes — matching is by document name, not by subtype, so nothing extra needs configuring.

🗑️ Removing a compendium

Unchecking a compendium only stops the module from scanning it. It never deletes the folder or your images. If the source module is later disabled, its entry stays listed as Unavailable rather than vanishing, so you keep the configuration and can remove it deliberately.

🔄 Actor Image Sync

🔍 What it does

Compendium art applies to compendium entries. Items already on an actor keep the image they had when they were added. Sync Actor Images closes that gap: it scans every world actor and updates only the img field of eligible embedded items. No other field is ever touched.

🛡️ What it protects

Only images that are still the system default are replaced. Anything you or a player set deliberately is left alone. Running it repeatedly is safe — once everything is current, nothing changes.

📚 Covered item types

Classes, Subclasses, Ancestries, Communities and Domain Cards out of the box, plus any item type found in a custom Item compendium you added. Items with no compendium counterpart are untouched.

▶️ Running it

Click Sync Now in the module settings. GM only. Generate the art mappings first if you have just added images.

⚙️ Settings Reference

Found under Game Settings → Configure Settings → Daggerheart: Art Mapper.

The two Include toggles take effect the next time you regenerate — they do not retroactively change an existing mapping.

🎚️ Compendium Art Priority

This module registers through Foundry's native compendium art system, so it appears on the core Compendium Art screen (Configure Settings → Core, palette icon) alongside any other art module you have installed. There you can:

• toggle Portraits, Tokens and Items independently for each source;
• reorder sources, deciding who wins when two modules provide art for the same entry.

The module only appears on that screen once a mapping has been generated.

💻 Console / Macro Commands

Run from a script macro or the browser console (F12 → Console). Also reachable as game.modules.get("dh-assets").api.

// Apply module art to items on world actors. GM only.
// Returns { actorsAffected, itemsUpdated }.
await dhAssets.syncActorImages();

// Rescan the beastform folders and republish the galleries. GM only.
await dhAssets.generateBeastformArt();

// Re-read the published galleries on this client, without reloading.
await dhAssets.loadBeastformArt();

// Inspect what this client currently has: Map of "tier1/agile-scout" → [file paths].
dhAssets.getBeastformArt();

❓ Troubleshooting

My art did not appear.
Click Regenerate Art Mappings and reload. If a specific entry is missing, check that the filename starts with that entry's exact name.

One entry always shows the same token instead of a random one.
Open the console (F12) — the warning says which of the two causes applies. Either its name starts another entry's name and the files share a plain prefix, or the files for that entry disagree on capitalisation. Both are covered under How to Organize Your Assets, step 2.

A druid transformation shows no gallery.
That form's folder is empty, or the GM has not regenerated since the images were added. Ask the GM to click Regenerate Art Mappings; players can then run dhAssets.loadBeastformArt() to pick it up without reloading.

Art from another module is winning over mine (or vice versa).
Adjust the order on the core Compendium Art screen — see Compendium Art Priority.

🧰 My Daggerheart Modules

🗺️ Adventures