MTGA Overlay MVP

A lightweight, open-source desktop overlay for Magic: The Gathering Arena.

Features (MVP)

• Log Watcher: Automatically detects and reads MTGA logs to track game state.
• Card Resolver: Maps MTGA card IDs to Scryfall data.
• Art Swap: View alternate art for cards in your hand/battlefield.
• Overlay: Transparent, click-through overlay that sits on top of the game.

Tech Stack

• Electron: Desktop application framework.
• React + Vite: UI rendering.
• TypeScript: Type safety across the monorepo.
• pnpm: Fast, disk-efficient package manager.

Setup

1. Prerequisites: Node.js 18+, pnpm.
2. Install:

   pnpm install

3. Run Dev:

   pnpm dev

   This will start the Electron app and the Vite dev server.

Testing & Replay

To test without running MTGA, you can use the Replay Harness. This simulates log activity by streaming lines from a fixture file to a temporary log monitored by the app.

Two-Terminal Replay (Windows PowerShell)

1. Terminal 1: Start Overlay in Replay Mode

# Set log path to a temp file and start
$env:OVERLAY_LOG_PATH="C:\temp\mtga_replay.log"; pnpm dev

2. Terminal 2: Feed Sample Data

# Build core and run the feeder
pnpm --filter @mtga-overlay/core build
pnpm --filter @mtga-overlay/core replay --source test/fixtures/sample.log --target C:\temp\mtga_replay.log --delay 1000

Live Testing (MTGA)

Simply run pnpm dev. It will automatically look for the MTGA Player.log in the standard LocalLow path.

Hotkeys

• Ctrl+Shift+O: Toggle Overlay visibility.
• Ctrl+Shift+C: Toggle Overlay click-through mode.

Architecture

See docs/ARCHITECTURE.md for details.

Troubleshooting

• Logs not found: The app looks for logs in %AppData%/LocalLow/Wizards Of The Coast/MTGA/Player.log. If your logs are elsewhere, you may need to adjust the code (MVP limitation).
• Overlay broken: Ensure you are running in "Windowed" or "Borderline Windowed" mode in MTGA for best results, though it should work in Fullscreen on some systems.

Compliance & Safety

• This tool only reads the local log file generated by the game.
• It does not inject code, read memory, or inspect network traffic.
• It does not automate gameplay.
• It is designed to be compliant with WotC's Fan Content Policy and safe for use (though standard "use at your own risk" applies).

Roadmap

See docs/ROADMAP.md for future plans.