An analytics platform for Marvel Champions: The Card Game that scores every card on a common scale, plus a rules knowledge base extracted from the official Rules Reference.
The card game is the domain. The point of the repository is the engineering: a layered Python package, a reproducible data pipeline, and 184 passing tests guarding a model whose output is a float that nobody can eyeball for correctness.
184 passed, 3 skipped in 2.81s
"Is this card good?" is normally answered by argument. The Effective Resources (ER) model answers it with a number: what a card gives you, denominated in the resources you would have had to spend to get it another way.
The anchor is deliberately boring:
ER = printed_cost + 1
A card that costs 3 resources delivers 4 ER of value when it is exactly fairly costed — the extra 1 being the card itself, since playing it consumes a card from your hand. Everything else is measured as deviation from that line. A card scoring well above its cost is efficient; well below and it is a trap.
The hard part is not the axiom, it is turning ~2 000 cards of natural-language effect text into comparable quantities: damage, threat removal, healing, card draw, resource generation, and the conditions attached to each.
An ER score is a float. If a refactor changes Hawkeye's score from 6.293 to 6.310, nothing crashes, no test fails by default, and the error is invisible until every downstream tier list is quietly wrong.
So the model output is pinned. tests/regression/regression_fixtures.json freezes the computed
score for 18 reference cards across every card type:
"Hawkeye": { "code": "50002", "type_code": "ally", "cost": 4, "er_score": 6.293 }Any change to the scoring pipeline that moves one of those numbers fails the suite and has to be justified. That is the difference between a model you can refactor and a model you are afraid to touch.
The rest of the suite splits by what it protects:
| What it covers | |
|---|---|
tests/unit/ |
effect-text pattern extraction, cost parsing, hero kits, per-mechanic values |
tests/regression/ |
the pinned ER scores above |
tests/integration/ |
end-to-end metrics and the rules knowledge base |
src/mcda/
analytics/ core scoring, mathematical models, balance analysis, effect patterns
pipeline/ card_parser/ (effect text -> structured effects), rules/ (Rules Reference)
services/ orchestration
db/ persistence
web/ dashboard
config/, utils/
scripts/
compute/ recompute derived values (baselines, tier thresholds, foundational stats)
diagnostics/ analysis passes and regression fixture generation
maintenance/ data loading, rulebook PDF processing
tests/ unit · regression · integration
data/ source JSON and computed artefacts
The split between scripts/compute, scripts/diagnostics and scripts/maintenance is by what
the script does to the data — recompute it, inspect it, or load it — so it is obvious which ones
are safe to run.
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m pytest tests -qThe test suite needs no database and no network — it runs in under three seconds.
Rebuild the derived data from source:
python -m scripts.maintenance.load_jsons
python -m scripts.maintenance.extract_scenarios
python -m scripts.compute.compute_foundational_stats
python -m scripts.compute.compute_er_baselines
python -m scripts.compute.compute_tier_thresholdsIngest the official rules PDF into the knowledge base:
python -m scripts.maintenance.process_rulebook_pdf data/rulebooks/core_rules.pdf --skip-database- The ER model is a model. It is calibrated against the
cost + 1axiom, and cards whose value is mostly positional, combo-dependent, or tied to a specific hero are scored worse than cards whose value is a number printed on them. The regression fixtures protect consistency, not correctness. - Rules extraction is LLM-assisted against Rules Reference v17, and it has not been exhaustively verified line by line against the source document.
- Single-source data. Card data comes from one upstream source; there is no cross-check against a second.
- Not affiliated with Fantasy Flight Games. Marvel Champions card data belongs to its publisher; this repository holds analysis code, and is a personal project for learning.
Francisco Merchán Cordero — pacomerchanc@gmail.com