Full automated pipeline for generating printable D&D guild item pack cards from raw material text files and PNG art → SVG → DM PDF → Player PDF → Pack PDF. Tiers: Specialist (28 packs), Capable (29), Expert (28), Master (29), Grandmaster (35), Exit (4). All 7 flavors: Recovery, Defense, Offense, Stealth, Strike, Magic, Utility. Key features: - 5 rarity templates (Common through Legendary) with printer-calibrated gradients - Dynamic title fitting (single/two-line with hyphenation support) - Bold/italic formatting for D&D mechanics (dice, conditions, hit points) - Cross-flavor dual marks for shared items - Lore quality system: 100-120 words, no boilerplate, Monty Python humor - Batch processing script for large-scale generation - Skill documentation for future agent continuity Made-with: Cursor
24 KiB
Guild Pack Card Generation Scripts
Scripts for generating D&D guild item pack cards as SVGs and PDFs.
Overview
The pipeline takes raw material (item text files + PNG art) and produces credit-card-sized printable cards for use at the D&D table.
Each item becomes:
- SVG (DM master version) — contains price, DM watermark, full mechanics + lore
- DM PDF — 2-page (front + back) export of the SVG
- Player PDF — 2-page export with price, DM watermark, and bottom bars removed; mechanics text and image repositioned for visual balance without DM elements
- Pack PDF — multiple Player Singles combined via
pdfunite
Scripts
generate-card.py
Generates an SVG card from a template + raw material text file + PNG art.
python3 scripts/generate-card.py \
--template "0c Specialist/Recovery/Cleanse Draught.svg" \
--item-text "raw-materials/.../Burn Salve [Common] [450s].txt" \
--image "raw-materials/.../Burn_Salve_2.png" \
--lore-choice alt2 \
--output "0c Specialist/Recovery/Burn Salve.svg" \
--flavor Recovery \
--tier 0c
Arguments:
--template— SVG template matching the item's rarity (Common, Uncommon, or Rare)--item-text— raw material.txtfile with structured fields--image— one of the PNG art variants for the item (Tier-1 has 3 per item, Tier-2+ has 2)--lore-choice—main,alt1, oralt2(pick the funniest; rewrite if all are bad)--output— where to save the generated SVG--flavor— category name(s), comma-separated for multi-flavor (e.g.Recovery,Defense)--tier— output tier code:0c,1,2,3,4
export-player-pdf.py
Exports a Player PDF from a DM SVG card. Strips DM elements and adjusts layout.
python3 scripts/export-player-pdf.py \
"0c Specialist/Recovery/Burn Salve.svg" \
-o "0c Specialist/Recovery/PDFs Players/Singles/Burn Salve (450s).pdf"
Template Selection
| Rarity | Template Source | Background Gradient | Price Tag Color |
|---|---|---|---|
| Common | Cleanse Draught.svg (0c Specialist/Recovery) |
tan/cream #c3b8a2→#fff9e5 |
grey #f2f2f2 |
| Uncommon | Vitality Tincture.svg (0c Specialist/Recovery) |
green #c7ff99→#eeffe5 |
green #00b200 |
| Rare | Rare Template.svg (1 Capable/Recovery) |
blue #66b2ff→#9beeff |
blue #4c4cff |
| Very Rare | Very Rare Template.svg (3 Master/Recovery) |
purple gradient | purple #c34cff |
| Legendary | Legendary Template.svg (5 Exit) |
orange #ff9966→#ffc59b |
orange #ff6600 |
Important: All five rarity gradients are printer-calibrated for the credit card printer. The Legendary template was derived from the Very Rare template with gradient colors taken from the Wyrmseye Oracle reference card.
Template rarity refers to the background gradient and price tag color, not the tier. A Specialist-tier card can be Uncommon (e.g. Nerve-Calm Vapor) or Rare, just use the matching rarity template.
Card Layout Rules
Dimensions
- Card size: 53.98mm × 85.6mm (credit card)
- Two Inkscape pages per SVG (front + back)
Title Fitting (3-tier fallback)
- Single line at 4.939px — up to 15 characters
- Single line at 4.586px — up to 16 characters (e.g. "ANTITOXIN DELUXE")
- Two lines at 4.586px with
line-height:0.95— 17+ characters (e.g. "EXHAUSTION / ANCHOR")
Note: The small single-line threshold was reduced from 17 to 16 because uppercase titles with wide glyphs (W, M, X) overflow at 17 chars (e.g. "EXHAUSTION ANCHOR"). Two-line titles split naturally and look good, so the conservative threshold is preferred.
When a two-line title is used:
- Subhead y shifts from 12.37mm to 17.0mm to clear the second title line (15.7mm was tested but caused subtitle to merge into title bottom in high-fidelity Inkscape PDF rendering. 17.0mm is the correct value. SVG thumbnail previews can be misleading -- always verify in the PDF.)
- Image is scaled to 53mm instead of 58mm (less vertical space available)
- Title block bottom is treated as 19mm instead of 14mm for layout calculations
Parenthetical qualifiers are stripped from titles (e.g. "Breath of the Deep (Ampoule)" → "BREATH OF THE DEEP"). The full name is preserved in the subhead detection and lore.
Front Page Layout (DM version)
- Title: top of card, bold Ubuntu
- Subhead: italic, below title (auto-detected from item name)
- Image: scaled (58mm single-line / 53mm two-line), centered between title bottom and mechanics top; capped at available space minus 5mm buffer (
IMAGE_BUFFER) to prevent overlap - Mechanics text: positioned so bottom edge sits 3.5mm above the DM bar (~80.1mm)
- Price: rotated -90°, left edge, white text on colored tag rectangle (
text-anchor:end) - Flavor marks: top right, colored rounded rectangles (one per tier level)
- DM bar + watermark: red bar at ~80mm, "DUNGEON MASTER'S COPY" at ~84mm
Front Page Layout (Player version)
- Same as DM but: no price tag, no DM bar/watermark, no bottom red bars
- Mechanics text positioned with side-margin gap (4.3mm) to card bottom (85.6mm)
- Image centered in the available space between title and mechanics
Back Page (Lore)
- Text fills the page with natural paragraph breaks (3-5 paragraphs)
- Paragraphs separated by blank-line tspans containing
\n - Pre-wrapped lines with explicit x/y coordinates (Inkscape native format)
- Line spacing: 11.6667 user units
- Base y: 93.108 user units
Text Formatting
Mechanics (front):
- D&D conditions in italic: frightened, charmed, exhaustion, poisoned, confused, grappled, etc.
- Dramatic phrases in bold:
advantage on saving throws vs X/advantage on death saves(full phrase bolded)advantage on checks to X(full phrase bolded)resistance to X and Y/immunity to X(full phrase bolded)- Dice rolls:
2d6+5,1d4, etc. X hit points(spelled out, never abbreviated as "HP")X temporary hit points(spelled out, never abbreviated as "temp HP")- Distance:
10 ft,30 feet
HP/hp→ always spelled out ashit pointstemp HP→temporary hit pointsGM→DM- Minus signs in dice notation use mathematical minus
−(U+2212), not hyphen- - Action grammar: Always "Action to [verb]", "Bonus Action to [verb]", or "Reaction [trigger]". Never "Action [verb]" without "to". For thrown items, start with "Throw ([range])." For scrolls, "Cast [spell] once."
- "Single use." should end mechanics for consumable items
- "advantage on saves vs X for" — the bold pattern stops before "for", "and", "until", "during", "while" to avoid leaking into duration text
Lore (back):
- Inline quotes detected and wrapped in italic with curly quotes (" ")
- Quote triggers: "once said,", "remarked,", "yelled,", "whispered,", etc.
- Paragraphs split at sentence boundaries, balanced by character count
- Rewrite lore when the raw material is clearly AI-generated filler (look for repeated phrases like "fine print bans prank use in chapels" or the item name repeated excessively). Make it funny, dry, Monty Python-esque.
Subhead Auto-Detection
| Pattern in item name | Subhead |
|---|---|
| potion, draught, tonic, tincture, elixir, antitoxin, brew, broth, draft, dew, serum | potion |
| "drink" or "sip" in mechanics | potion (front-text fallback) |
| oil | oil |
| salve, wrap, poultice, balm, resin, ointment, unguent | salve / poultice |
| suture, thread, bandage, splint, weave, compress, lattice | medical supply |
| salt, salts, tabs, biscuit, tea, cup, capsule, taffy | consumable (ingest) |
| vapor, fume, ampoule, censer, snuff, incense | consumable (inhale) |
| powder, dust, anchor, charm, patch | consumable (apply) |
| pearl, bead | consumable (crush) |
| scroll | scroll |
| ammo/ammunition (in mechanics) | ammunition |
| trap | trap |
| grenade, bomb | thrown weapon |
| (fallback) | wondrous item |
Note: "flask" was removed from thrown weapon — drinkable flasks are detected by
mechanics keywords ("sip", "drink") hitting the potion fallback first.
Price Tag System
Price tags use text-anchor:end with rotate(-90). The text position (x, y) is
inherited from the template and stays fixed. Only the rect height and ry change
per price to ensure equal top and bottom margins around the text.
Heights are measured from authoritative hand-crafted reference cards, keyed by (currency, digit_count) — not character count, to avoid ambiguity with commas and spaces.
| Currency | Digits | Example | Height (mm) | ry | Source |
|---|---|---|---|---|---|
| SILVER | 2 | 75 SILVER | 24.621 | 1.1608 | Common 10-99s template |
| SILVER | 3 | 250 SILVER | 26.263 | 1.2382 | Common 100-999s template |
| SILVER | 4 | 7,700 SILVER | 29.890 | 1.4093 | Uncommon 1k-9999s template |
| SILVER | 5 | 12,500 SILVER | 31.812 | 1.4998 | Uncommon 10k-99ks template |
| GOLD | 2 | 15 GOLD | 21.948 | 1.0348 | Uncommon 10-99g template |
| GOLD | 3 | 600 GOLD | 24.603 | 1.1600 | Cloak of Protection |
| GOLD | 4 | 1,100 GOLD | 28.697 | 1.3530 | interpolated — flag for review |
| GOLD | 5 | 50,000 GOLD | 30.947 | 1.4590 | interpolated — flag for review |
| GOLD | 6 | 280,000 GOLD | 33.197 | 1.5650 | interpolated — flag for review |
| GOLD | 7 | 2,400,000 GOLD | 37.696 | 1.7770 | extrapolated (6d + 3→4d delta) — flag for review |
Note: GOLD 3d is measured from Cloak of Protection. 4d-6d are interpolated. 7d is extrapolated by adding the 3→4d delta (which represents one digit + one comma) to the 6d value. All interpolated/extrapolated values look good in practice but flag for manual review when first printing a new digit/currency combination.
Bold text width: Bold text is slightly wider than normal weight. The line count
estimator accounts for this with BOLD_WIDTH_FACTOR = 1.05 and uses an estimated
mechanics wrap width of MECHANICS_WRAP_WIDTH = 42 characters. These values match
Inkscape's shape-inside text wrapping for most cards. Edge cases with long bold
segments may still be off by ±1 line; the error direction is "slightly too much
bottom margin" which is less noticeable than too little.
Important: Reference cards in ~/Drive/Cloud/DnD Session/Resources/Item Cards/ use
text-anchor:start which is a different convention. Do NOT use those rect heights
directly — they produce misaligned tags with our text-anchor:end templates.
Missing combinations will print a WARNING during generation. If no template exists, the rect is left as inherited from the template SVG.
Flavor Mark System
| Flavor | Color Hex | Visual |
|---|---|---|
| Offense | #ff0000 |
Red |
| Defense | #0066ff |
Blue |
| Recovery | #44aa00 |
Green |
| Stealth | #c87137 |
Brown |
| Strike | #4d4d4d |
Dark grey |
| Utility | #ffcc00 |
Gold |
| Magic | #c34cff |
Purple (same as Very Rare price tag — printer-verified) |
Multi-flavor items (e.g. Antitoxin in both Recovery and Defense): marks are placed side-by-side at the same y position, rightmost = primary flavor.
Mark count = tier level in the output folder system:
0cSpecialist = 1 mark1Capable = 2 marks2Expert = 3 marks3Master = 4 marks4Grandmaster = 5 marks5Exit = 0 marks (beyond the guild tier system)
Mark spacing: y = 2.539 + n × 6.88 where n = 0, 1, ..., (mark_count − 1).
Mark injection: If the template SVG has no mark elements (e.g. Common silver templates), the script creates mark elements from scratch. No template modification needed.
Tier Mapping
| Output Folder | Rarity | Raw Material | Marks |
|---|---|---|---|
| 0a Novice | mini/grey | (none) | 0 |
| 0b Intermediate | Common | (none) | 0 |
| 0c Specialist | Common/Uncommon | Tier-1 | 1 |
| 1 Capable | Uncommon/Rare | Tier-2 | 2 |
| 2 Expert | Uncommon/Rare | Tier-3 | 3 |
| 3 Master | Rare | Tier-4 | 4 |
| 4 Grandmaster | Very Rare | Tier-5 | 5 |
| 5 Exit | Mixed (VR/L/R/U) | Tier-6 | 0 (unmarked) |
Note: Rarity is per-item, not per-tier. A Capable pack can contain both Uncommon and Rare items (and that's part of the lootbox fun). Use the item's rarity to select the template.
Standard Potions
Standard D&D potions (Healing, Greater Healing, etc.) have pre-made cards at
~/Drive/Cloud/DnD Session/Resources/Item Cards/Potions/. These cards:
- Have their own hand-crafted layout and art
- Do not carry tier/flavor marks (they're standard items, not guild-flavored)
- Use the
Healing.svg(player) andHealing DM.svg(DM) naming convention - Can appear in guild packs as-is — just export PDFs and include in pack assembly
- Drinking a potion is a bonus action in these campaigns (common homebrew)
Output Directory Structure
<Tier>/<Flavor>/
├── *.svg (DM master SVGs)
├── Rare Template.svg (if rarity template was created here)
├── PDFs DM/
│ └── <Item Name> (<price>).pdf (2-page DM PDF)
└── PDFs Players/
├── Singles/
│ └── <Item Name> (<price>).pdf (2-page Player PDF)
└── Packs/
└── NN <Tier> <Flavor> - <Pack Name>.pdf
Pack Assembly
Pack PDFs are assembled from Player Singles using pdfunite:
pdfunite \
"Singles/Item A (100s).pdf" \
"Singles/Item B (200s).pdf" \
"Singles/Item C (300s).pdf" \
"Packs/03 Specialist Recovery - Weather the World.pdf"
Pack numbering: Pack A/R1 = 01, Pack B/R2 = 02, Pack C/R3 = 03, Pack D/R4 = 04.
Items can appear in multiple packs or even across tiers. Standard potions can be included by referencing their Player PDF directly.
Lore Guidelines
Each item has a main lore plus 2 alternatives (~120 words each).
Selection: Pick the funniest. alt1 and alt2 are usually better than main.
Look for memorable imagery, cultural references, and punchlines.
Rewriting: When raw material lore is clearly AI-generated filler, rewrite it completely. Telltale signs of bad lore:
- Repeated boilerplate phrases ("fine print bans prank use in chapels...", "No one agrees who invented it; everyone agrees it works best when deployed before shouting starts")
- The item's full name repeated excessively (especially parenthetical names)
- Generic placeholder wisdom that could apply to any item
Good lore should be funny, dry, specific to the item, and make players want to read the back of the card. Think Monty Python meets a tired quartermaster writing field reports.
Additional boilerplate signals discovered across Tier-5 and Tier-6 items:
- "entered guild records after a planning meeting, two bad assumptions, and one excellent cup of tea"
- "witnesses suddenly remember they have a spine"
- "Use it once and you'll understand why the gods invented envy"
- "it turns panic into a plan, and makes the plan look like it was always the plan"
- Any lore where the item name is repeated 3+ times
Exit-tier lore should be extra epic and extra Monty Python, bordering on Benny Hill. The originals (catalog_back_expanded) for many Exit items are genuinely excellent and should be preserved with paragraph breaks added.
Homebrew Items
Some raw material items reference homebrew rules that may not exist in all campaigns. Flag these for manual review rather than generating cards automatically. Example: "Stitchweed Tea" references "minor bleeding (homebrew)" — this mechanic doesn't exist in the Northlands campaigns and the item was replaced.
Image Selection
Tier-1 items have 3 PNG art variants (_1.png, _2.png, _3.png).
Tier-2+ items have 2 variants (_1.png, _2.png).
Any variant works; pick the one that looks best at credit card size.
Images are embedded as base64 in the SVG.
Completed Packs
0c Specialist — All Flavors (Tier-1)
All 28 Specialist packs (7 flavors × 4 packs) are complete.
| Flavor | Packs | Total Items | Notes |
|---|---|---|---|
| Recovery | 4 | 18 | Includes hand-crafted cards with updated consensus prices |
| Defense | 4 | 15 | Antitoxin (Guild Reserve) has Recovery+Defense dual marks |
| Offense | 4 | 16 | 9 items shared with Strike have Offense+Strike dual marks |
| Stealth | 4 | 18 | All Common, brown marks |
| Strike | 4 | 8 unique + 9 shared | Cross-references Offense SVGs for dual-mark items |
| Magic | 4 | 12 | Purple marks (#c34cff), first flavor to use injected marks on Common templates |
| Utility | 4 | 15 | Includes Rare Potion of Arcane Focus (2,222g, blue gradient) |
Cross-flavor dual marks: Items appearing in packs of two flavors get side-by-side marks (e.g. Shock Vial has red+grey for Offense+Strike). The SVG lives in one flavor folder and is referenced from both pack assemblies.
Price normalization: All items use consensus prices from raw material files, superseding any earlier hand-crafted prices.
1 Capable — All Flavors (Tier-2)
| Flavor | Packs | Items | Notes |
|---|---|---|---|
| Recovery | 4 | 13 | Earlier automated work |
| Magic | 4 | 13 | Earlier automated work |
| Defense | 4 | 13 | All new |
| Offense | 4 | 13 | All new, replaces hand-crafted Pack A |
| Stealth | 4 | 13 | All Uncommon except Lantern-Leech (Common) |
| Strike | 4 | 10 | Includes Rare Queen's Mercy (2,400g) |
| Utility | 4 | 12 | All Common |
2 Expert — All Flavors (Tier-3)
All 28 Expert packs complete. All missing items from initial build were later delivered by the raw materials agent and integrated.
| Flavor | Packs | Items | Notes |
|---|---|---|---|
| Recovery | 4 | 17 | Includes Nerves-Like-New Elixir |
| Defense | 4 | 15 | Cushionwrap Pauldron now available |
| Magic | 4 | 15 | Spellbraid Wax now available |
| Offense | 4 | 15 | All 6 missing items delivered |
| Stealth | 4 | 16 | Full complement |
| Strike | 4 | 14 | All 6 missing items delivered |
| Utility | 4 | 18 | All 6 missing items delivered |
3 Master — All Flavors (Tier-4, Rebalanced)
Fully rebalanced from raw-materials-3. Rarity: 55% Rare, 22% VR, 21% Uncommon, 0% Common.
| Flavor | Packs | Items |
|---|---|---|
| Defense | 4 | 13 |
| Magic | 4 | 14 |
| Offense | 4 | 18 |
| Recovery | 4 | 11 |
| Stealth | 4 | 14 |
| Strike | 5 | 14 |
| Utility | 4 | 13 |
4 Grandmaster — All Flavors (Tier-5, Overhauled)
Complete overhaul. Rarity: 78% VR, 18% Rare, 0% Common/Uncommon. 5 packs per flavor. Alternate Recovery packs archived.
| Flavor | Packs | Items |
|---|---|---|
| Defense | 5 | 20 |
| Magic | 5 | 20 |
| Offense | 5 | 20 |
| Recovery | 5 | 20 |
| Stealth | 5 | 20 |
| Strike | 5 | 20 |
| Utility | 5 | 20 |
5 Exit — All Packs (Tier-6)
6 cards per pack. 8 new Legendary items added (2 per pack). Architect's Final Chalk and Titanbrace Pavise repriced to VR level.
| Pack | Name | Cards | Legendary | VR |
|---|---|---|---|---|
| A | Hands of the Grey Eminence | 6 | 4 | 2 |
| B | The Last Key | 6 | 2 | 4 |
| C | Make the World Behave | 6 | 2 | 4 |
| D | Break the Siege | 6 | 3 | 3 |
Project Totals
| Tier | Packs | Items | SVGs |
|---|---|---|---|
| 0c Specialist | 28 | 103 | 103 |
| 1 Capable | 29 | 89 | 89 |
| 2 Expert | 28 | 110 | 110 |
| 3 Master | 29 | 97 | 97 |
| 4 Grandmaster | 35 | 140 | 140 |
| 5 Exit | 4 | 24 | 24 |
| Total | 153 | 563 | 563 |
1g gold price rule: Items priced at 1g are converted to 1,000s to avoid 1-digit gold price tags (no template exists for that size).
Template Gotchas
Issues discovered when using templates from different sources:
-
Image
transform: scale(-1,1)— Some templates have a horizontal mirror on the image element. The script now strips all transforms from image elements duringembed_image(). Without this fix, the image renders off-screen to the left. -
"requires attunement" text — Some templates (especially the Uncommon 10k-99k silver) have a small "requires attunement" text element at ~2.1px font size. The script now detects this and clears it. Without this fix, the text persists on the card.
-
Template
text-anchorconvention — All templates in this project usetext-anchor:endfor price text. External reference cards (in~/Drive/Cloud/DnD Session/Resources/Item Cards/) sometimes usetext-anchor:start. Do NOT mix price tag dimensions between conventions. -
Conditions list deduplication — The
DND_CONDITIONSlist must not contain duplicates. If a condition appears twice, the italic wrapper runs twice, turning*word*into**word**which renders as bold instead of italic. -
Missing mark elements in Common templates — The Common silver templates (
0b Intermediate/Template Common *.svg) have no flavor mark rectangles. The script now creates mark elements from scratch when none exist in the template. This was required for all non-Recovery Common items (Magic, Stealth, etc.). -
Subhead keyword conflicts — "flask" was in
thrown weaponbut Breath of Warmth Flask is a drinkable. "thread" was inmedical supplybut Spell Thread is arcane. "capsule" was inconsumable (ingest)but Mage-Armor Capsule is applied to skin. Each conflict is handled with exclusion checks (e.g."thread" in name and "spell" not in name).
Line Count Estimation
The mechanics text uses Inkscape's shape-inside for wrapping, which means Inkscape
does the actual line breaking at render time. The script's estimate_text_lines() is
only used for positioning — calculating where to place the text element vertically
so the bottom margin matches the side margins.
Current parameters: MECHANICS_WRAP_WIDTH = 42, BOLD_WIDTH_FACTOR = 1.05.
These values were calibrated against 15+ cards across all tiers. The estimation is correct for most cards but inherently imprecise because character-count estimation cannot perfectly match proportional font rendering. When off, the error is typically +1 line (slightly too much bottom margin), which is less noticeable than -1 line (text too close to the card edge).
Both generate-card.py and export-player-pdf.py must use the same parameters.
Image Buffer
Both scripts use IMAGE_BUFFER = 5.0 mm to prevent images overlapping mechanics text.
The image is capped at min(target_size, available_space - IMAGE_BUFFER).
Critical: export-player-pdf.py must use the same buffer cap as generate-card.py.
An earlier version of the player exporter blindly rescaled images to a fixed 58mm target,
undoing the buffer applied during SVG generation. This caused oversized images on every
player card. The fix was to replicate the avail - IMAGE_BUFFER cap logic.
Price Consistency
Raw material prices are authoritative. Prices in the raw text file filenames
(e.g. [550s], [2,222g]) are the consensus-negotiated prices and supersede any
earlier hand-crafted prices on existing cards.
When regenerating items, the PDF filename must match the price shown on the card. Old-price PDF files should be deleted to avoid pack assembly referencing stale filenames.
PDF filename convention: <Item Name> (<price>).pdf where price includes currency
suffix: s for silver, g for gold (e.g. Shock Vial (550s).pdf, Spell Thread (26g).pdf).
Cross-Flavor Items
Items appearing in packs of two different flavors get dual flavor marks on a single card. The SVG lives in one canonical flavor folder (typically the first flavor alphabetically or the flavor it was originally created in).
| Cross-flavor pair | Items | Marks | SVG location |
|---|---|---|---|
| Offense + Strike | 9 items (Oil of Keen Edge, Surestrike, Shock Vial, etc.) | Red + Grey | 0c Specialist/Offense/ |
| Recovery + Defense | Antitoxin (Guild Reserve) | Green + Blue | 0c Specialist/Recovery/ |
Pack assembly for the secondary flavor references the canonical folder's Singles PDFs. When the item is regenerated (e.g. for price correction), both flavors' packs must be rebuilt.