Garrett Mills
dfba2403a8
Colorless There was no way to ask for colorless cards — the colour toggles are a 5-bit WUBRG mask where 0 already means "don't filter by colour", leaving nothing to express "no colours at all". That's exactly what you need to find a colorless commander's card pool. Adds a "C" pip to both colour rows, matching how ColorPips already renders colorless cards, backed by two explicit booleans rather than a sixth bit — a filter mask and a card's real colour mask staying the same shape is worth keeping. The two rows mean different things and both are useful: on the commander row C filters colour *identity*, which is the Commander rule; on the includes row it filters the card's own colours. A card printed colorless can still carry a coloured identity through mana symbols in its text, and it's the identity that bars it from a colorless commander's deck. Set listings News > Releases had its own card path and so couldn't be filtered. A new set_code filter (matched against printings.set_code, already ingested) lets the set browser run through search_reference instead, so every criterion works there identically rather than being reimplemented over a live Scryfall response. That alone would have cost the ability to browse an upcoming set, since search_reference only knows downloaded card data — and upcoming sets are half the point of the tab. So the browser picks a source per set: downloaded data where it exists, with the full filter panel; otherwise Scryfall directly, with the panel hidden and a line explaining why. A panel that silently does nothing would be worse than no panel. The source is decided by an *unfiltered* probe. Keying off whether the current criteria match anything would flip a properly indexed set to "live" the moment a filter excluded everything, dropping the panel exactly when it was in use.
mtgc — Personal Magic: The Gathering Library Catalog
A desktop and Android app (Tauri v2 + React) for cataloging your MTG collection: rapid fuzzy card entry, rich criteria search (colors, commander color-identity compatibility, mana value, type/subtype/keyword, price, format legality), and deck organization with per-card deck membership. All logic lives in a platform-agnostic Rust core, so both platforms share it.
Architecture
src/ React + TypeScript UI (swappable presentation)
src-tauri/ Tauri v2 shell — exposes the core as typed commands
crates/mtgc-core/ Pure Rust: db, fuzzy search, filters, decks, ingester
Two files:
- your library
.json— owned cards, decks, deck contents. Small, readable, and the only file you name or move. Put it somewhere synced; see Sync. reference.db— read-only card data built from Scryfall bulk. Bulky and re-downloaded per device, so it's never synced. Lives in the OS app-data dir (e.g.~/.local/share/com.garrettmills.mtgc/).
First-time setup
./scripts/devel-setup.sh # Tauri system libs (webkit2gtk/gtk3) + Tauri CLI
npm install # frontend deps
Why GTK3, not GTK4? Tauri v2's Linux backend (
wry/tao) hard-depends on GTK3 +webkit2gtk-4.1; there's no GTK4/webkitgtk-6.0 option yet. GTK4 support is tracked upstream but unmerged with no ETA: tauri#7335, tao#1104, wry#1228. Revisit once Tauri ships GTK4 support (likely Tauri v3).
Run
cargo tauri dev # launches the desktop app (dev mode)
On first launch, click Download card data — it fetches the Scryfall
Oracle Cards + Default Cards bulk (~a few hundred MB) and builds
reference.db. After that the app is fully offline.
You can also build the card database from the command line:
cargo run -p mtgc-core --bin mtgc-ingest -- /path/to/reference.db
Production build
Build an optimized app with the frontend embedded into the executable:
./scripts/devel-setup.sh # once, if not already done
cargo tauri build
Outputs (under the workspace target/release/):
target/release/mtgc— the standalone executable. The web UI and all app logic are baked into this one file. It dynamically links the system WebKit/GTK libraries (webkit2gtk4.1,gtk3), so those must be present on the machine that runs it — they are on any modern desktop Linux and are installed bydevel-setup.sh.target/release/bundle/rpm/*.rpmand.../deb/*.deb— native installers (Fedora / Debian-based) that add a menu entry and icon.
Useful variants:
cargo tauri build --no-bundle # only the bare target/release/mtgc binary
Notes:
- The
mtgcbinary is a single file but relies on the system WebKit/GTK libs being present (installed bydevel-setup.sh). - The binary does not embed card data — first run still downloads the Scryfall bulk into the OS app-data dir. Your library document defaults to that directory too; move it into a synced folder with New Library (see Sync).
- The
[profile.release]settings inCargo.toml(strip + LTO) make the release build take a few minutes but keep the binary small.
Using it
- Add Cards — type a name (typos OK); ↑/↓ then Enter adds a copy.
- Library — filter owned cards by name, colors, commander identity (color identity ⊆ chosen), mana value, power/toughness, price, format legality, type/subtype/keyword, or deck. Hover a row's thumbnail for a full-size preview that tracks the cursor. Rows show which decks a card is in and a warning (⚠) when it's assigned to more decks than you own. Toggle List / Tiles (top-right) to switch between the table and a grid of full card images; the choice is remembered.
- Card Search — the same filters over every card, owned or not. Select rows (or tiles) and bulk-add them to a deck; one undo covers the whole batch.
- Deck contents offer the same List / Tiles toggle and hover previews.
- Decks — create decks and assign owned cards; set per-deck quantities.
Both filter panels share a row of quick toggles: hide Universes Beyond (cards that exist only as another property — Lord of the Rings, Warhammer 40,000, Marvel), hide digital-only (Arena/MTGO cards such as Alchemy rebalances), hide Un-set joke cards, or keep only cards that can be a commander. The three exclusions are derived as every printing, so an ordinary card reprinted into one of those sets — Lightning Bolt appears in Marvel Commander — isn't hidden.
Those three, plus the power/toughness filters, live in
reference.db, which is rebuilt rather than migrated. After upgrading, click Update card data once to enable them; until then they're inert rather than broken. Price, format legality and can be a commander work immediately.
Sync
Your collection is a single JSON file — the only file you manage. Put it in a folder your sync tool watches (Syncthing, Dropbox, Nextcloud, Seafile, or a USB stick) and every device stays in step. Choose it with Open Library / New Library, or from the Info tab.
Editing in two places merges rather than one side overwriting the other. Sync is a three-way merge against the last version of the document that device read, which is what lets it tell "you changed this" from "they deleted it": edit different cards on a phone offline and on the desktop, and both survive. When both sides change the same field, the other copy's value wins and the change is reported so you can correct it.
It runs by itself — at launch, on every switch away from and back to the app, and every few minutes while open. Sync now in the Info tab forces a pass.
Nothing here depends on a particular sync tool. If two devices publish while both are offline, some tools leave a conflict copy behind; mtgc merges any it finds beside the document and clears it once the contents are safely published.
Upgrading from an older build? Earlier versions had you manage
library.dbyourself. The Info tab offers Convert old library once; the original file is left untouched, so it doubles as a backup.
Develop / test
cargo test -p mtgc-core # core: db, search, filters, decks, ingest, sync merge
cargo test -p mtgc # shell: document read/write, conflict-copy matching
npm run build # typecheck + build frontend
cargo build # build everything incl. the desktop app
The sync merge is a pure function over plain structs (mtgc_core::sync::merge3),
so the cases that matter — concurrent edits, a delete racing an edit, repeated
merges being a no-op — are unit tests rather than something you have to
reproduce across two devices.
To typecheck the Android Kotlin without building the APK (it doesn't invoke cargo, so it won't disturb a running dev session):
cd src-tauri/gen/android && ./gradlew :app:compileUniversalDebugKotlin
Android
The Rust core and frontend are platform-agnostic, so the Android build shares all app logic with the desktop; only data provisioning and file access differ.
One-time setup
Install Android Studio and launch it once so its wizard downloads the SDK, then:
./scripts/android-setup.sh
That adds what Android Studio doesn't install by default: the SDK
command-line tools, a pinned stable NDK, and the Rust Android targets. It
prints the three environment variables to export (ANDROID_HOME, NDK_HOME,
JAVA_HOME).
Why the NDK?
mtgc-corebuildsrusqlitewith thebundledfeature (compiles SQLite from C) andrustlspulls inring(C/asm), so a C cross-toolchain is required. The bundled SQLite can't be swapped for Android's system libsqlite3 either — the card schema needs FTS5 with thetrigramtokenizer, which platform SQLite often lacks.
Why
JAVA_HOME? Gradle/AGP reject very new JDKs. The script prefers Android Studio's bundled JetBrains Runtime (JDK 21), which needs no extra install.
Build and run
Every Android command needs ANDROID_HOME / NDK_HOME / JAVA_HOME. Source
the helper once per shell — it auto-detects all three:
source scripts/android-env.sh # bash / zsh
source scripts/android-env.fish # fish
Only the env helper is shell-specific (it has to mutate the calling shell);
android-setup.sh is executed rather than sourced, so it works from any shell.
Then, from the project root:
cargo tauri android dev --open # dev server + open in Android Studio
cargo tauri android build --apk # standalone release APK
src-tauri/gen/android is committed (unlike the rest of gen/) because
AndroidManifest.xml is hand-edited — Android permissions have no
tauri.conf.json equivalent.
Working in Android Studio
Use cargo tauri android dev --open rather than opening
src-tauri/gen/android directly. Studio's Run button delegates the Rust build
to cargo tauri android android-studio-script, which expects a running Tauri
dev session — it reads the dev-server address from
/tmp/<identifier>-server-addr. Open the Gradle project on its own and the
build fails with failed to read missing addr file.
With the dev session running, Studio's device dropdown, Device Manager (emulator), and debugger all work normally.
JetBrains Toolbox users:
--openfinds Studio by scanning XDG data dirs for a.desktopentry whoseNameis exactlyAndroid Studio. Toolbox writes a versioned name instead (e.g.Android Studio Quail 2 2026.1.2 Patch 1), so the lookup misses and the launch fails with a confusingCmd(["Android Studio"]) ... No such file or directory.android-setup.shdrops in a hidden shim entry (~/.local/share/applications/android-studio.desktop) to fix this; delete that file to undo it.
To build without Studio and without a dev server, use cargo tauri android build — that path needs no addr file.
Card data on a phone
Downloading card data streams ~740MB of JSON to build a ~73MB database, which
is slow on mobile and may be killed if the app is backgrounded. Faster: copy
reference.db from a desktop install onto the device and use Import card
data…. The file is validated before it replaces anything.
Sync on Android
Android can't hand out a filesystem path to a shared folder, so instead of
naming a file you grant access to a folder through the system picker:
Info → Choose folder…, then pick the one your sync tool watches. mtgc keeps
library.json inside it and everything in Sync applies unchanged.
That grant is per-folder and persists across restarts, so the app declares no
storage permission at all — no "All files access" prompt. The alternative,
MANAGE_EXTERNAL_STORAGE, would hand the app the entire shared volume just to
reach one directory.
Branding
The logo is an original pirate-ship silhouette in the terracotta brand color
(#C8553D) — a nod to the MTG card "Pirate Ship", not a reproduction of its
art. Source: src-tauri/icons/logo-source.svg. To regenerate the full
platform icon set after editing it:
cargo tauri icon src-tauri/icons/logo-source.svg