Files
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

176 lines
7.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Genshin TCG Generator
Turn the [paimon-moe](https://github.com/MadeBaruna/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](https://docs.pydantic.dev) 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](https://playwright.dev/python/)'s Chromium build (installed below)
## Installation
```powershell
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):
```powershell
genshin-tcg build
# identical to:
python -m genshin_tcg build
```
Or run the stages individually:
```powershell
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:
```powershell
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:
```dotenv
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
```powershell
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`](https://genshin-impact.fandom.com/wiki/Character/List) (the
table generated by `Template:Characters by Category Table`); bosses and enemies
inherit their *family* from
[`Enemy/List`](https://genshin-impact.fandom.com/wiki/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.
```json
{ "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
```powershell
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.