Files
genshin-tcg/README.md
T
V d651455499
CI / quality (3.11) (push) Has been cancelled
CI / quality (3.12) (push) Has been cancelled
First version
2026-10-15 17:37:05 +02:00

144 lines
5.2 KiB
Markdown
Raw 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.
- **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.
- **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 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 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, so nation tags are supplied
locally. Drop icons into `assets/tcg/icons/factions/<faction>.png` and map cards
to them in `assets/overrides/factions.json`:
```json
{ "ganyu": "liyue", "diluc": "mondstadt", "rhodeia_of_loch": "fatui" }
```
## 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
├── 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.