Files
genshin-tcg/README.md
T
V 89855f78f3
CI / quality (3.11) (push) Has been cancelled
CI / quality (3.12) (push) Has been cancelled
Nice cards templates
2026-10-16 02:37:28 +02:00

7.1 KiB
Raw Blame History

Genshin TCG Generator

Turn the paimon-moe Genshin Impact TCG data into printable cards: standalone HTML per card, high-resolution PNGs and an A4 imposition PDF ready for a home printer or a print shop.

The pipeline is deliberately split into three inspectable stages.

       fetch                    render                     impose
 ┌───────────────┐      ┌───────────────────┐      ┌────────────────────┐
 │ fr.json       │      │ Jinja2 templates  │      │ ReportLab A4 grid  │
 │ + PNG assets  │ ───► │ → HTML per card   │ ───► │ 3x3, 9 cards/page  │
 │ → catalog.json│      │ → PNG (Playwright)│      │ + crop marks       │
 └───────────────┘      └───────────────────┘      └────────────────────┘

Features

  • Data mining – downloads src/data/tcg/<lang>.json and every required image from paimon-moe into a local assets/ cache, then parses it into typed Pydantic models (character vs action cards).
  • Modular rendering – each card is written as a self-contained .html file (CSS inlined, images referenced relatively) so a badly laid-out card can be tweaked by hand and re-rasterised without re-running the earlier stages.
  • Official-style card faces – templates reproduce the printed TCG look: a gold frame with corner stars, HP teardrop, engraved name plaque, the element / faction / weapon tag column, hexagonal cost dice and a frosted description panel. Keyword colours are re-mapped at render time so the dataset's pastel palette stays legible on the light panel.
  • Print-ready output – cards are rendered at the classic 63x88 mm poker format at 300 DPI (configurable) and imposed 3x3 on A4 with optional crop marks.
  • Wiki-derived factions – genshin-tcg factions resolves each character's nation (and each enemy's faction) from the community wiki and caches the pages locally, so cards can show a region tag.
  • Typed and tested – strict mypy, ruff, and a pytest suite.

Requirements

  • Python 3.11+
  • Playwright's Chromium build (installed below)

Installation

python -m venv .venv
.venv\Scripts\Activate.ps1          # or: source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium         # one-off browser download

Usage

Run the full pipeline (download → render → PDF):

genshin-tcg build
# identical to:
python -m genshin_tcg build

Or run the stages individually:

genshin-tcg fetch                    # download data + assets, write build/catalog.json
genshin-tcg factions                 # resolve factions from the wiki -> assets/overrides + emblems
genshin-tcg render                   # build/html/<id>.html and build/png/<id>.png
genshin-tcg impose                   # build/cards-fr.pdf

Useful flags:

genshin-tcg --language en build                      # English dataset
genshin-tcg --dpi 600 build                          # 600 DPI output
genshin-tcg render --only ganyu --only diluc         # a subset of cards
genshin-tcg render --no-screenshot                   # only regenerate the HTML
genshin-tcg factions --dry-run                       # preview the faction mapping
genshin-tcg factions --no-icons                       # mapping only, no emblems
genshin-tcg list                                     # browse the local catalogue

Output layout:

build/
├── catalog.json        # the intermediate "source of truth"
├── html/ganyu.html     # self-contained, hand-editable
├── png/ganyu.png       # 744x1039 px @ 300 DPI
└── cards-fr.pdf        # A4 imposition
assets/                 # cached downloads (git-ignored)

Configuration

Settings can be set through the CLI or environment variables (prefix GTCG_, nested keys separated by __), or a .env file:

GTCG_LANGUAGE=fr
GTCG_CARD__DPI=300
GTCG_PAGE__CUT_MARKS=true
GTCG_RENDER__KEEP_HTML=true
Setting Default Description
language fr Dataset language code
assets_dir assets Where downloads are cached
build_dir build Where output is written
card.width_mm / card.height_mm 63 / 88 Card size (poker format)
card.dpi 300 Output resolution
page.columns / page.rows 3 / 3 Imposition grid
page.cut_marks true Draw crop marks on the PDF
render.keep_html true Keep generated HTML after rasterising

Factions / nations

The upstream dataset does not ship faction artwork or metadata. Run

genshin-tcg factions

to derive the mapping from the community wiki (via its MediaWiki API) and write assets/overrides/factions.json. Playable characters inherit the region of Character/List (the table generated by Template:Characters by Category Table); bosses and enemies inherit their family from Enemy/List (Fatui → fatui, Hilichurls → hilichurl, everything else → monster). Pages are cached under assets/source/wiki/ for reproducibility; use --force to refresh them.

The file is plain JSON keyed by card id and is safe to edit by hand: re-running the command keeps your entries and only fills in the gaps. Use --overwrite to discard hand-made values and regenerate from scratch, or --dry-run to preview.

{ "ganyu": "liyue", "diluc": "mondstadt", "rhodeia_of_loch": "monster" }

The command also downloads the nation emblems into assets/tcg/icons/factions/<faction>.png, so the tag renders as an image next to the element and weapon icons. Enemy factions (fatui, hilichurl, monster) have no wiki emblem and keep the localised label. Use --no-icons to skip the download, or drop in your own <faction>.png to override an emblem.

Development

ruff check .
mypy
pytest

Project layout

src/genshin_tcg/
├── cli.py              # Typer entry point
├── config.py           # pydantic-settings configuration
├── constants.py        # domain enums + asset path helpers
├── models.py           # typed domain models (Pydantic)
├── markup.py           # description normalisation + sanitisation
├── pipeline.py         # fetch / render / impose orchestration
├── data/               # remote source, catalogue, asset download, wiki factions
├── rendering/          # Jinja environment, view models, converter, renderer
│   └── templates/      # base/character/action templates + macros + stylesheet
└── pdf/                # ReportLab imposition

Licence

This tool only downloads publicly available assets from paimon-moe; all game assets and texts remain the property of HoYoverse. Use for personal printing.