Files
rick 0489a2dbdc fix(1 Capable): restore mechanics destroyed by broken rewrite-mechanics.py
The prior editorial commit used a positional-arg version of
rewrite-mechanics.py (overwritten by Expert-tier agent) which wrote
the literal flag text "-m" or "--subhead" as mechanics content.

Fixed rewrite-mechanics.py to use argparse with -m/--mechanics and
-s/--subhead flags (with positional fallback). Restored correct
mechanics for all 32 affected items and reapplied all editorial fixes.

Made-with: Cursor
2026-04-17 15:14:43 +02:00
..

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:

  1. SVG (DM master version) — contains price, DM watermark, full mechanics + lore
  2. DM PDF — 2-page (front + back) export of the SVG
  3. Player PDF — 2-page export with price, DM watermark, and bottom bars removed; mechanics text and image repositioned for visual balance without DM elements
  4. 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 .txt file 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, or alt2 (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)

  1. Single line at 4.939px — up to 15 characters
  2. Single line at 4.586px — up to 16 characters (e.g. "ANTITOXIN DELUXE")
  3. 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 as hit points
  • temp HP → temporary hit points
  • GM → 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:

  • 0c Specialist = 1 mark
  • 1 Capable = 2 marks
  • 2 Expert = 3 marks
  • 3 Master = 4 marks
  • 4 Grandmaster = 5 marks
  • 5 Exit = 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) and Healing 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:

  1. Image transform: scale(-1,1) — Some templates have a horizontal mirror on the image element. The script now strips all transforms from image elements during embed_image(). Without this fix, the image renders off-screen to the left.

  2. "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.

  3. Template text-anchor convention — All templates in this project use text-anchor:end for price text. External reference cards (in ~/Drive/Cloud/DnD Session/Resources/Item Cards/) sometimes use text-anchor:start. Do NOT mix price tag dimensions between conventions.

  4. Conditions list deduplication — The DND_CONDITIONS list 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.

  5. 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.).

  6. Subhead keyword conflicts — "flask" was in thrown weapon but Breath of Warmth Flask is a drinkable. "thread" was in medical supply but Spell Thread is arcane. "capsule" was in consumable (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.