171 lines
6.7 KiB
Markdown
171 lines
6.7 KiB
Markdown
# 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.
|
||
- **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 + 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.
|