Andreas/mtg_python_deckbuilder
1
0
Fork 0
mirror of https://github.com/mwisnowski/mtg_python_deckbuilder.git synced 2025-12-16 07:30:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
mtg_python_deckbuilder/docs/commander_catalog.md
matt 88cf832bf2 Finalize MDFC follow-ups, docs, and diagnostics tooling 
document deck summary DFC badges, exporter annotations, and per-face metadata across README/DOCKER/release notes

record completion of all MDFC roadmap follow-ups and add the authoring guide for multi-face CSV entries

wire in optional DFC_PER_FACE_SNAPSHOT env support, exporter regression tests, and diagnostics updates noted in the changelog
2025-10-02 15:31:05 -07:00

4.8 KiB
Raw Blame History

Commander Catalog Onboarding

The Commander Browser and deck builder both read from csv_files/commander_cards.csv. This file is generated during setup and must stay in sync with the fields the web UI expects. Use this guide whenever you need to add a new commander, refresh the dataset, or troubleshoot missing entries.

Where the file lives

  • Default path: csv_files/commander_cards.csv
  • Override: set CSV_FILES_DIR (env var) before launching the app; the loader resolves commander_cards.csv inside that directory.
  • Caching: the web layer caches the parsed file in process. Restart the app or call clear_commander_catalog_cache() in a shell if you edit the CSV while the server is running.

Required columns

The loader normalizes these columns; keep the header names exact. Optional fields can be blank but should still be present.

Column Notes
name Printed front name. Used as the fallback display label.
faceName Front face name for MDFCs/split cards. Defaults to name when empty.
side Leave blank or A for the primary face. Secondary faces become distinct slugs.
colorIdentity WUBRG characters (any casing). C marks colorless identities.
colors Printed colors; mainly used for ordering badges.
manaCost Optional but keeps rows sortable in the UI.
manaValue Numeric converted mana cost.
type Full type line (e.g., Legendary Creature — Phyrexian Angel).
creatureTypes Python/JSON list or comma-separated string of creature subtypes.
text Oracle text. Enables partner/background detection and hover tooltips.
power / toughness Optional stats. Leave blank for non-creatures.
keywords Comma-separated keywords (Flying, Vigilance, …).
themeTags Python/JSON list of curated themes (e.g., ['Angels', 'Life Gain']).
edhrecRank Optional EDHREC popularity rank (integer).
layout Layout string from MTGJSON (normal, modal_dfc, etc.).

Additional columns are preserved but ignored by the browser; feel free to keep upstream metadata.

Recommended refresh workflow

  1. Ensure dependencies are installed: pip install -r requirements.txt.
  2. Regenerate the commander catalog with the MDFC-aware helper (multi-face merge always on): 
    python -m code.scripts.refresh_commander_catalog
    • Pass --compat-snapshot when you need both csv_files/commander_cards.csv and csv_files/compat_faces/commander_cards_unmerged.csv so downstream consumers can diff the historical row-per-face layout.
    • The legacy --mode argument is deprecated; it no longer disables the merge but still maps --mode compat to --compat-snapshot for older automation. Use --skip-setup if determine_commanders() has already been run and you simply need to reapply tagging.
    • When running the web service during staging, set DFC_COMPAT_SNAPSHOT=1 if you need the compatibility snapshot written on each rebuild. The merge itself no longer requires a feature flag.
    • Use the staging QA checklist (docs/qa/mdfc_staging_checklist.md) to validate commander flows and downstream consumers before promoting the flag in production.
  3. Restart the web server (or your desktop app) so the cache reloads the new file.
  4. Validate with the targeted test: 
    python -m pytest -q code/tests/test_commander_catalog_loader.py
    The test confirms required columns exist, normalization still works, and caching invalidates correctly.

Manual edits (quick fixes)

If you need to hotfix a single row before a full regeneration:

  1. Open the CSV in a UTF-8 aware editor (Excel can re-save with a UTF-8 BOM — prefer a text editor when possible).
  2. Add or edit the row, ensuring the slug-worthy fields (name, faceName, side) are unique.
  3. Keep the themeTags value as a Python/JSON list (e.g., ['Artifacts']), or a comma-delimited list without stray quotes.
  4. Save the file and restart the server so the cache refreshes.
  5. Backfill the curated themes in config/themes/ if the new commander should surface dedicated tags.

Manual edits are acceptable for emergency fixes but commit regenerated data as soon as possible so automation stays trustworthy.

Troubleshooting

  • Commander catalog is unavailable error: The app could not find the CSV. Verify the file exists under CSV_FILES_DIR and has a header row.
  • Row missing in the browser: Ensure the commander passed eligibility (legendary rules) and the row’s layout/side data is correct. Slug collisions are auto-deduped (-2, -3, …) but rely on unique name+side combos.
  • Theme chips absent: Confirm themeTags contains at least one value and that the theme slug exists in the theme catalog; otherwise the UI hides the chips.

For deeper issues, enable verbose logs with SHOW_LOGS=1 before restarting the web process.