drawhand 🃏

TCG/CCG draw probability calculator — compute the odds at your terminal.

drawhand is a zero-dependency CLI tool that computes card draw probabilities for any trading card game — Pokémon TCG, Magic: The Gathering, Yu-Gi-Oh!, Hearthstone, or your own custom format. It uses exact hypergeometric distribution for analytical results and Monte Carlo simulation for complex scenarios.

$ drawhand hand -d 60 -c 4

  🃏 Opening Hand Analysis (One Shot — Custom)
  Deck: 60 cards  |  Hand: 7 cards  |  Copies: 4x

  Opening hand probabilities for '4× card':

    Exactly 0: 60.0%  ████████████░░░░░░░░
    Exactly 1: 33.6%  ██████░░░░░░░░░░░░░░
    Exactly 2:  5.8%  █░░░░░░░░░░░░░░░░░░░
    Exactly 3:  0.4%  ░░░░░░░░░░░░░░░░░░░░
    Exactly 4:  0.0%  ░░░░░░░░░░░░░░░░░░░░

  At least 1: 40.0%
  Expected:   0.47 cards  (σ ≈ 0.65)

Features

• Hypergeometric calculations — exact analytical probabilities (P(exactly k), P(at least k), P(at most k))
• Opening hand analysis — full probability distribution for your opening hand
• Monte Carlo simulation — simulate thousands of opening hands for complex deck analysis
• Multi-card tracking — OR probability: chance of drawing Card A OR Card B in opening hand
• Mulligan simulation — Pokemon-style mulligans: auto-redraw when no Basic Pokemon in hand
• Keep/mulligan analysis — Monte Carlo analysis of keepable hands with game-specific heuristics
• Turn-by-turn tracking — cumulative probability of seeing a card by each turn
• Decklist parsing — read real decklist files in plain text format with section-aware parsing
• Game presets — built-in configurations for MTG, Pokémon, Yu-Gi-Oh!, Hearthstone, LoR
• JSON output — machine-readable output for scripts and pipelines
• Zero dependencies — pure Python, uses only stdlib. pip install and go.

Installation

pip install drawhand

Or run from source after cloning:

git clone https://github.com/novaoc/drawhand.git
cd drawhand
python -m drawhand --help

Usage

Basic hypergeometric odds

# Probability of drawing at least 1 copy (4-of in 60-card deck, 7-card hand)
drawhand odds -d 60 -c 4 -n 7

# Probability of drawing exactly 2 copies
drawhand odds -d 60 -c 4 -n 7 -k 2 --exact

# Probability of drawing at most 1 copy
drawhand odds -d 60 -c 4 -n 7 -k 1 --at-most

Opening hand analysis

# Quick calculation
drawhand hand -d 60 -c 4

# From a decklist file — Pokémon TCG format
drawhand hand --deck-list my-deck.txt --game pokemon

# From a decklist, tracking a specific card
drawhand hand --deck-list deck.txt --card "Charizard ex"

# JSON output
drawhand hand --deck-list deck.txt --json

Monte Carlo simulation

# Simulate 100,000 opening hands, show all card probabilities
drawhand simulate my-deck.txt

# Track a specific card with fewer trials for quick feedback
drawhand simulate my-deck.txt --card "Nest Ball" -t 10000

# Multi-card OR probability — "what's my chance of drawing at least one search card?"
drawhand simulate my-deck.txt --cards "Nest Ball" "Ultra Ball" "Quick Ball"

# Pokemon mulligan simulation — auto-detect Basics from decklist sections
drawhand simulate my-deck.txt --mulligan --game pokemon

# Pokemon mulligan with explicit basics
drawhand simulate my-deck.txt --mulligan --basics "Pidgey" "Pidgeotto" "Pidgeot ex"

# Mulligan + track a specific card's probability after mulligans resolve
drawhand simulate my-deck.txt --mulligan --game pokemon --card "Rare Candy"

Keep/mulligan decision analysis

# Pokemon — auto-detect Basic Pokemon from decklist sections
drawhand keep my-pokemon-deck.txt -g pokemon

# Pokemon with explicit basics
drawhand keep my-deck.txt -g pokemon --basics "Pidgey" "Pidgeotto" "Pidgeot ex"

# MTG — auto-detect lands from decklist sections
drawhand keep my-mtg-deck.txt -g mtg

# MTG with custom keep range (3-4 lands)
drawhand keep my-mtg-deck.txt -g mtg --min-lands 3 --max-lands 4

# MTG with explicit land list
drawhand keep my-deck.txt -g mtg --lands "Island" "Plains" "Hallowed Fountain"

# JSON output
drawhand keep my-deck.txt -g pokemon --json

Turn-by-turn probabilities

# Probability of drawing a card by each turn
drawhand turns my-deck.txt --card "Rare Candy" --max-turns 5

# With game preset for default hand size and cards/turn
drawhand turns my-deck.txt --card "Rare Candy" --game pokemon

Game presets

drawhand games

Decklist format

drawhand accepts simple plain-text decklists:

4 Pidgeot ex
4 Pidgeotto
4 Pidgey
3 Rare Candy
4 Arven
4 Nest Ball
4 Ultra Ball
2 Boss's Orders
1 Super Rod
5 Grass Energy

Section headers

Add section headers to enable auto-detection of card types (Basic Pokemon, lands, etc.):

Pokemon (12):
4 Pidgeot ex
4 Pidgeotto
4 Pidgey

Trainers (18):
3 Rare Candy
4 Arven
4 Nest Ball
4 Ultra Ball
2 Boss's Orders
1 Super Rod

Energy (7):
5 Grass Energy
2 Double Turbo Energy

With section headers, drawhand keep and drawhand simulate --mulligan --game pokemon can auto-detect Basic Pokemon without --basics. For MTG, sections like Lands: enable auto-detection of land cards.

Comments (#) and section headers are skipped automatically. Set codes ((SCR), collector numbers 123/162) are stripped.

Why drawhand?

There are plenty of web calculators for card draw odds. drawhand is different:

• Works offline — no internet, no browser tabs
• Scriptable — pipe JSON output into your own tools
• Fast — instant hypergeometric results, no round-trip latency
• Batch-friendly — run hundreds of calculations from a shell script
• Privacy-respecting — your decklists never leave your machine

License

MIT