🔮 Scrymat

Scrymat turns your Magic: The Gathering decks into a shared virtual playmat — offline, at the table, or remotely with no account required.

Project status

Pre-release hobby project. Single-device play works today. Remote play is written but does not work on the live site yet. Last checked 2026-09-28.

Area	Status
Deck import/export (Scrymat, Moxfield, Archidekt, MTGO/Arena) and saved decks	Works
Single-device play: shuffle, draw, mulligan, scry, tutor, fetch basic land, moving cards between zones	Works; covered by unit and Playwright tests in CI
Scryfall card images with IndexedDB cache; offline use after first load	Works
Live site (scryglass.cards)	Up, but it serves the 2026-08-03 build under the old "Scryglass" name. Deploys have failed since the repo rename.
Remote play (WebRTC + signaling worker)	Partial. Client and worker code exist and are tested, but the worker has never been deployed. The live site has no /api/room backend, and /match/:code links return an error.
Hidden-information protection (commit-reveal) and shared seeded shuffling	Partial. Implemented in @scrymat/core but not used by the app yet. Remote sync sends plain actions and full GameState snapshots.
Local AI opponent over WebSocket	Partial. The app can connect to ws://127.0.0.1:8765; the repo ships only a prompt (agent/SKILL.md), not an agent.

---

Scrymat is a free, open-source Progressive Web App (PWA) for MTG goldfishing, couch play, and casual remote games. It runs entirely in your browser, works offline after first load, and is designed for use on a phone lying flat on a game store table.

[!NOTE] The production TLD and some AWS infrastructure may still use the legacy scryglass identifier until the final DNS and deploy cutover is complete.

🚀 Quick Start (Play Tonight!)

No installation. No account. Just open and play.

Local / pass-and-play

1. Open the deployed app (today that is still scryglass.cards).
2. Paste your deck list (Scrymat format, or import from Moxfield/Archidekt/MTGO).
3. Load each deck, deal opening hands, and start moving cards around the table.

Remote Host / Join

[!WARNING] Not working on the live site yet: the signaling worker is not deployed. See Project status. The steps below describe the intended flow.

1. One player clicks Generate Room Code to host a match.
2. Share the room code or /match/:roomCode invite URL with the guest.
3. The guest enters the code, Scrymat completes the WebRTC handshake, and both browsers connect peer-to-peer.
4. Once connected, the host can resync the guest with a full GameState snapshot after reconnects or divergence.

✨ Features

• 🃏 Shared virtual playmat — The Scrymat pivot expands the state engine from library-only actions to generic card movement across public and private zones (ADR-012)
• 🪑 Dumb Table philosophy — Scrymat gives you zones, cards, and movement, but it does not enforce turn structure or comprehensive Magic rules. You stay in control of takes-backs, shortcuts, and house rules.
• 🤝 Peer-to-peer remote play — WebRTC data channels plus stateless signaling synchronize matches without a central game server (ADR-014). Not yet deployed.
• 🔐 Hidden-information protection — Commit-reveal hashing keeps opponents from trivially peeking at concealed cards during remote games. Hidden cards stay committed until you intentionally reveal them. Planned: implemented in core, not yet used by the app.
• 🎲 Deterministic shared shuffling — Seeded PRNG support lets every client derive the same deck order for a match (ADR-013). Planned: implemented in core, not yet used by the app.
• 📱 Offline-first local play — Install to your home screen and keep using it for goldfishing or pass-and-play even without WiFi
• 🖼️ Card images via Scryfall — Background prefetch with IndexedDB caching and JIT priority loading
• 📥 Multi-format import — Supports Moxfield, Archidekt, and MTGO/Arena deck formats
• 📤 Multi-format export — Export your deck to any supported format

💭 Why Scrymat?

Scrymat began as a simple answer to the frustration that shuffling takes too long. I originally built it so I could play Magic with my kids. Previously, I was spending half of our "playtime" physically manipulating our cards. I wanted a way to let the computer handle the mechanics of the library so we could focus on actually playing the game together.

The pivot to Scrymat keeps that original goal, then pushes further into shared remote play:

• Protecting High-Value Collectibles: Play with your physical dual lands, foils, and reserved list cards without subjecting them to the wear and tear of constant mash-shuffling.
• Accessibility: 100-card Commander decks are physically difficult to manipulate. Scrymat removes the physical barrier of dexterity required to shuffle, fetch, and handle a massive deck.
• Frictionless Goldfishing: Test your latest brews instantly. Just paste your Moxfield link and start drawing hands without needing to sleeve up a single card.
• Remote Table Presence: Share a synchronized tabletop over the web without a full rules engine or webcam rig.

🤝 Trust Model

Scrymat is designed for trusted casual play, not for adversarial tournament enforcement:

• The table is dumb by design. Scrymat tracks where cards are, not whether a play was legal.
• Private information uses commit-reveal. Remote peers receive commitments for hidden cards first, then the real card only when it becomes public.
• Reconnects prefer snapshots over logs. When peers reconnect, the host can send the guest the current serialized GameState so both sides converge quickly.

---

🛠️ For Builders

Architecture Decisions

All significant decisions are documented as Architecture Decision Records:

ADR	Title
ADR-001	Use Architecture Decision Records (ADRs) to Document Decisions
ADR-002	Preact + Vite for the PWA
ADR-003	Scryfall API integration & compliance
ADR-004	Fisher-Yates shuffle with Web Crypto API
ADR-005	Action/Reducer state management — agent-ready game engine
ADR-006	Semicolon-delimited deck import format
ADR-007	Monorepo structure (core/PWA separation)
ADR-008	TypeScript & Zod for strict typing
ADR-009	Client-side routing strategy

Architecture

Scrymat is built as a monorepo with strict separation of concerns:

Package	Purpose	Browser Dependencies
@scrymat/core	Pure game logic: deck parsing, shared shuffling, zone-based state management, mulligan/setup flows, and card movement	❌ None — runs in Node.js and browsers
@scrymat/pwa	Preact + Vite frontend: UI rendering, Scryfall API integration, IndexedDB caching, Service Worker, and WebRTC match sync	✅ Browser APIs required

The @scrymat/core module uses a strict JSON-in/JSON-out action-reducer pattern with Zod schema validation, making it suitable for consumption by AI agents, CLI tools, or any TypeScript/JavaScript consumer.

Monorepo Structure

repository-root/
├── packages/
│   ├── core/             # @scrymat/core — game logic library
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── pwa/              # @scrymat/pwa — Preact + Vite frontend
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── meta/                 # Development philosophy, ADRs, and plans
│   ├── adr/              # Architecture Decision Records
│   └── plans/            # Implementation plans and roadmaps
├── docs-src/             # Documentation source files (MkDocs)
├── scripts/              # Utility and automation scripts
├── .github/              # GitHub-specific configuration
└── package.json          # Root workspace configuration

Deployment (AWS S3 + CloudFront)

The repository includes a GitHub Actions workflow (.github/workflows/deploy-aws.yml) that builds the PWA and deploys it to AWS S3, fronted by CloudFront.

Required AWS resources:

• S3 bucket (static site hosting)
• CloudFront distribution (CDN, HTTPS, custom error pages for SPA routing)
• GitHub OIDC identity provider in IAM
• IAM role with S3 put/delete and CloudFront invalidation permissions

Required GitHub repository variables (Settings → Secrets and variables → Actions → Variables):

Variable	Description
AWS_ROLE_ARN	ARN of the IAM deploy role
AWS_REGION	AWS region of the S3 bucket
S3_BUCKET_NAME	Name of the S3 bucket
CLOUDFRONT_DISTRIBUTION_ID	CloudFront distribution ID
CLOUDFRONT_DOMAIN	(optional) Domain for post-deploy smoke test

The workflow runs automatically on push to main and can be triggered manually via workflow_dispatch. See docs-src/deployment.md for the full step-by-step setup guide, including the IAM policy JSON and CloudFront configuration.

[!IMPORTANT] Final Scrymat cutover still requires manual infrastructure follow-up: rename or redeploy the AWS bucket / CloudFront resources as desired, update GitHub Actions variables if those names change, rotate any environment-specific tokens tied to the legacy identifier, and repoint the public TLD when the new deployment is ready.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines. Note that this is primarily a hobby project for my own benefit - if there's something you'd like to see improved please LMK, but also know that maintaining Scrymat isn't my day job.

Scryfall Attribution

Card images and data are provided by Scryfall. Scrymat respects Scryfall's API guidelines by rate-limiting requests, caching aggressively, and including a descriptive User-Agent header. See our ROBOT_ETHICS.md policy.

License

This project is licensed under a GPL License.

Fan Content

Scrymat is unofficial Fan Content permitted under the Fan Content Policy. Not approved/endorsed by Wizards. Portions of the materials used are property of Wizards of the Coast. ©Wizards of the Coast LLC.