Images and symbols

Storage layout

Inside TCG_IMAGE_DIR, the current layout is:

Path pattern	Contents
<game>/cards/<set-id>/<printing-id>-<language>.<extension>	Cached card image; back-face files use a back suffix
<game>/sets/<set-id>.<extension>	Set icons
<game>/symbols/<color-code>.<extension>	Custom color/element symbols
<game>/rarity/<rarity-code>.<extension>	Custom rarity pictograms
default/<game>/symbols/ and default/<game>/rarity/	Copies of assets shipped by Zukan
cache/	External-source caches and downloaded metadata

Set/printing IDs here are database IDs, not necessarily printed codes. The database stores relative per-language image paths. Replacing the database without matching images can leave stale file references.

Pokémon markets share the pokemon symbol/rarity directories; Yu-Gi-Oh! markets share yugioh. Their card-image directories remain distinct.

Download and display

Image URLs come from catalog sources. Image jobs cache owned cards by default; providers can request all images for smaller catalogs. Views can obtain/cache missing images as implemented by the image service. Source refusals are recorded so a forbidden download is not retried on every view.

Collection images prefer the physical copy's language, then the provider fallback (normally English, Japanese for appropriate Asian catalogs). A provider can suppress fallback, as Pokémon China does, rather than showing an unrelated language. General card display also depends on interface language and available images.

A “No picture” placeholder does not delete the printing or prevent quantity tracking.

Import an image folder

1. Place the downloaded directory beneath the host's import directory, for example import/sorcery-pictures.
2. The API sees it under /data/import/sorcery-pictures using the supplied read-only mount.
3. In Data sync, select the game and an offered import folder, then run the image import.
4. Review stored and missing counters.

The matching filenames are provider-defined. Sorcery implements external image-folder matching; arbitrary names do not create catalog entries. The source printing must already exist.

CLI equivalent:

docker compose exec api zukan import-images sorcery /data/import/sorcery-pictures

The administrator API restricts folder selection to existing subfolders within TCG_IMPORT_DIR.

Override pictograms

Put a .svg, .png or .webp file in the appropriate non-default symbols/rarity directory, named using the provider's actual code. These files take precedence over shipped copies. Rarity icons can be language-specific, for example <rarity-code>.ja.svg; the loader tries the full language code, then its base language, then the plain code.

Do not customize the default tree: it is rewritten from shipped assets at startup. Back up your own overrides.

Migration and permissions

Older pre-0.12 layouts are moved by a database migration that also rewrites stored paths. Run migrations with the real image volume attached. The container entrypoint gives the top-level image folder to the non-root service user; nested files copied from another host may still require ownership repair.

Back up images and the database together. Source caches may be expensive to rebuild under daily request quotas.

Implementation references

• backend/app/services/layout.py
• backend/app/services/images.py
• backend/app/games/base.py