Add forge-scryfall-uuid-map CLI tool for patching edition files

[phughk]

Problem

To use Scryfall's rate-free CDN for card images, we need a UUID for every (set, collector-number, language) combination. Those UUIDs aren't in Forge's existing data. Scryfall publishes bulk-data exports with all of them, but they need to be processed into per-set JSON files that the runtime can fetch on demand.

This tool is the offline generator — run it once (or after each Scryfall data update) to produce the files that go in the forge-extras repository.

What it does

flowchart LR
    A[Scryfall bulk-data\nall_cards JSON] --> B[BulkDataFetcher\ndownloads & streams]
    B --> C[CardStreamParser\nreads UUID + set + cn + lang]
    C --> D["CdnUuidJsonWriter\nwrites cdn_uuid/{set}.json"]
    D --> E[~1,041 set files\nready for forge-extras]

Loading

Output — one JSON file per Scryfall set code:

cdn_uuid/neo.json
{
  "1":   {"pt":"…uuid…","de":"…uuid…","ja":"…uuid…","en":"…uuid…"},
  "2":   {"en":"…uuid…"},
  "A-40":{"en":["front-uuid","back-uuid"]}
}

DFCs with distinct face UUIDs store an array for the affected language.

Usage

Run from the repo root. No full Forge build required.

# Full multi-language output — downloads all_cards from Scryfall (~2.5 GB)
mvn -pl forge-scryfall-uuid-map exec:java \
  -Dexec.args="--output-dir /path/to/forge-extras/cdn_uuid"

# English-only, faster — downloads default_cards (~100 MB)
mvn -pl forge-scryfall-uuid-map exec:java \
  -Dexec.args="--output-dir /path/to/forge-extras/cdn_uuid --default-cards"

# Use a pre-downloaded bulk file (auto-detected if named all-cards-*.json or default-cards-*.json)
mvn -pl forge-scryfall-uuid-map exec:java \
  -Dexec.args="--output-dir /path/to/forge-extras/cdn_uuid --bulk-file all-cards-20260608.json"

The default (all_cards) includes every language variant and produces a complete multi-language UUID map. --default-cards is faster to regenerate but only covers English — the runtime falls back to the Scryfall API for non-English cards when a UUID is absent.

New module

forge-scryfall-uuid-map/ — standalone Maven module, not included in the game distribution. Added to the root pom.xml modules list.

Class	Role
Main	Entry point; arg parsing, wires components together
BulkDataFetcher	Fetches the bulk-data index from Scryfall and downloads the dataset
CardStreamParser	Streams the large JSON array card-by-card (low memory)
CardRecord	Holds parsed UUID, set code, collector number, lang
CdnUuidJsonWriter	Writes the per-set JSON files

Depends on

The output files belong in the forge-extras repository ( Card-Forge/forge-extras#33 ). The runtime code that reads them is in PR #10928 (Card-Forge/forge).