# mtga-assistant

A native Linux deck and game tracker for **Magic: The Gathering Arena** running under Steam/Proton.
It follows MTGA's `Player.log`, much like Untapped.gg and other trackers do, and shows:

Switch views with the buttons in the top bar (or Ctrl+1/2/3):

- **Deck**
  - *My deck*: remaining library with draw odds, hand, battlefield, graveyard, exile, sideboard.
    Between matches, it shows the last deck you submitted.
  - *Opponent*: battlefield, stack, graveyard, exile, cards *known* to be in their hand or library
    (cards you saw that went back into a hidden zone, or were revealed), and every card seen this match.
  - *Card preview*: hover a card to see its image from [Scryfall](https://scryfall.com).
- **Match**: life totals, poison/energy and other player counters, emblems, hand/library/graveyard
  counts, turn timer and timeouts used, turn/phase, Bo3 score and game time. The deck view fills
  the bottom half.
- **Turn**: what happened this turn, for you, your opponent and in total: cards drawn, spells cast,
  lands played, creatures died, life gained/lost, damage, discards, mills, exiles, counters and
  tokens, plus land drops used/allowed. Use ◀ ▶ to browse earlier turns; the "Whole game" table
  shows game totals.
- **History**: every finished game with date, event, opponent, both decks' colours, who was on
  the play, the result, turns and length. Click a game to open it in the Deck/Match/Turn views
  ("Back to live" returns). Games from the previous MTGA session (`Player-prev.log`) are imported
  on startup.

The Match view also shows who was on the play and, in best-of-three, who has been on the draw more.

*⚙ Customize* shows or hides the items in the current view. *Customize → Arrange…* lets you
reorder (drag, or ↑/↓) and show/hide the sections of the My deck and Opponent panels, or the
rows of the turn view. Your choices are remembered.

Card names, mana costs and types come from MTGA's own local card database, so they work offline.

## Requirements

- MTGA installed through Steam (Proton). The log, install and card DB are auto-detected from your
  Steam library folders.
- **Detailed logs enabled** in MTGA: *Options → Account → Detailed Logs (Plugin Support)*.
- [uv](https://docs.astral.sh/uv/) (`pacman -S uv`).

## Running

```sh
uv run mtga-assistant                       # follow the live Player.log
uv run mtga-assistant --replay path/to/Player-prev.log --rate 40   # replay a saved log
uv run pytest                               # tests
```

Start it before or after MTGA: on startup it reads the existing log to catch up on a match in
progress, then follows new lines. When MTGA restarts and replaces the log, the tracker resets.

On Wayland the window's app id is `mtga-assistant`. For example, to keep it floating on another
workspace in Hyprland:

```
windowrule = float, class:^(mtga-assistant)$
windowrule = workspace 2, class:^(mtga-assistant)$
```

## Configuration

Optional: `~/.config/mtga-assistant/config.toml`

```toml
log_path = "/path/to/Player.log"   # override auto-detection
mtga_dir = "/path/to/steamapps/common/MTGA"
cache_max_mb = 500                 # image cache cap
history_max_mb = 300               # cap for stored game details (summaries are always kept)
```

Game history lives in `~/.local/share/mtga-assistant/history.db` (roughly 20–100 KB per game).

## Image cache

Images are downloaded only for cards that actually appear, at Scryfall's `normal` size (about
60–100 KB each), and stored in `~/.cache/mtga-assistant/images`. When the cache passes
`cache_max_mb`, the least recently viewed images are deleted. *Cache → Clear image cache* empties it.

## Known limitations

- MTGA leaves oversized game-state messages out of the log ("Message summarized because one or
  more GameStateMessages exceeded the 50 GameObject or 50 Annotation limit"), typically during board
  wipes. Some zones can then be stale until they next change. The app detects this and shows a
  warning.
- After a library shuffle, a known card's position in the opponent's library is lost. It stays listed
  under "Library … known" until it shows up again. If it is drawn without being revealed, it may
  stay listed.