MTG Card Maker

A card featuring artwork of a fiery dragon and anvil

A Ruby gem for creating high quality fan-made Magic: The Gathering cards. This tool generates custom MTG cards with authentic formatting, comprehensive mana cost support, and precise card layouts. Perfect for game designers, content creators, and MTG enthusiasts.

Please note this gem is for fan content creation only. Using it commercially is a violation of the license. If you have ideas for improvements, please create a feature request after reviewing the open issues here: https://github.com/joe-sharp/mtg_card_maker/issues

Features

🎨 Card Customization

Core Card Properties:

  • Card Name: Customizable card titles with embedded font support
  • Mana Cost: Complete MTG symbol support including hybrid, Phyrexian, and numeric costs
  • Type Line: Customizable card types and subtypes (Creature, Instant, Sorcery, etc.)
  • Rules Text: Rich text with automatic word wrapping and symbol replacement
  • Flavor Text: Optional italicized flavor text with proper formatting
  • Power/Toughness: Dynamic power/toughness display

Visual Customization:

  • Color Schemes: 8 card colors (white, blue, black, red, green, colorless, gold, artifact)
  • Border Colors: Customizable borders (white, black, gold, silver)
  • Art Integration: Flexible artwork support via URLs or local paths
  • Font Embedding: Base64 font embedding for portability

🖼️ Advanced Sprite Sheet Features

Performance Optimizations:

  • Shared Assets: Fonts, gradients, and masks defined once per sprite sheet
  • File Size Reduction: Significantly smaller than individual card files
  • Layout Optimization: Ideal for web applications, printing and digital displays

Layout Control:

  • Cards Per Row: Configurable grid layout (default: 4)
  • Spacing Control: Pixel-perfect spacing between cards (default: 30px)
  • Dynamic Sizing: Automatic sprite sheet dimensions based on card count

Batch Processing:

  • YAML Configuration: Structured card definitions with validation
  • CLI Integration: Streamlined command-line workflow
  • Error Handling: Robust validation and helpful error messages

🛠️ Technical Excellence

SVG Generation:

  • Vector Graphics: High-quality SVG output suitable for any scale
  • Print Ready: Optimized for both digital and print applications
  • Cross-Platform: Compatible with all modern browsers and design software
    • NOTE: inline symbols in rule text may not render in some design software

Development Infrastructure:

  • Guard Integration: Automated testing and quality monitoring
  • Status Summary: Real-time development feedback with integrity checks
  • Comprehensive Testing: 480+ tests with fixtures and helpers
  • Code Quality: Zero RuboCop violations, consistent style

Documentation:

  • YARD Documentation: 96.30% documented with local server
  • CLI Help: Comprehensive command-line help and examples
  • Examples: Multiple configuration examples and use cases

💽 Installation

Prerequisites

This gem requires Ruby 3.2 or higher. The version of Ruby included with macOS is typically outdated and won't work. You can install a newer version of Ruby using tools like asdf (with the Ruby plugin), rbenv or RVM. Note: This gem seems to work just fine on Ruby 3.5.0 but cannot be tested in CI currently.

Install the gem:

gem install mtg_card_maker

Usage

🔧 Configuration Options

Card Properties:

Optionals without a default hide when omitted.

name: "Card Name"                 # Required
type_line: "Creature - Dragon"    # Required
rules_text: "Card rules text"     # Required
mana_cost: 2RR                    # Optional
flavor_text: "Flavor text"        # Optional
power: 4                          # Optional
toughness: 4                      # Optional
color: red                        # Optional (default: colorless)
border_color: gold                # Optional (default: white)
art: path/to/art.jpg              # Optional
embed_font: false                 # Optional (default: true)

Color Schemes Available:

`artifact`  => Artifact cards (Brown, legacy)
`black`     => Black cards
`blue`      => Blue cards
`colorless` => Artifact/Land cards (Grey)
`gold`      => Multicolor cards (Metallic Gold)
`green`     => Green cards
`red`       => Red cards
`white`     => White cards

Symbols Available for Mana Cost:

Mana Symbols:

  • W - White mana
  • B - Black mana
  • R - Red mana
  • G - Green mana
  • U - Blue mana
  • C - Colorless mana
  • S - Snow mana
  • {C/P} - Colorless Phyrexian mana
  • {R/P} - Red Phyrexian mana
  • {G/P} - Green Phyrexian mana
  • {U/P} - Blue Phyrexian mana
  • {B/P} - Black Phyrexian mana
  • {W/P} - White Phyrexian mana

Advanced Mana Support: Hybrid and Phyrexian mana are now fully supported! See all the notations below in the rule text section. The notation uses curly braces for complex symbols:

  • {R/G} Red / Green Mana
  • {G/W/P} Green / White Phyrexian Mana

Numeric Symbols:

  • 0 through 99 - Generic mana costs (0-99)
  • X - X symbol

Combination Examples:

  • 16US - 16 generic + 1 blue + 1 snow
  • XG - X generic + 1 green
  • X3R - X generic + 3 generic + 1 red
  • 3WU - 3 generic + 1 white + 1 blue
  • WU{B/P}RG White, Blue, Phyrexian Black, Red, Green
  • X - X generic only
  • 3 - 3 generic only
  • B - black only

Symbols Available in Rules Text:

You can use MTG symbols in your rules text by wrapping them in curly braces "C". The following symbols are supported:

Mana Symbols:

  • {W} - White mana
  • {B} - Black mana
  • {R} - Red mana
  • {G} - Green mana
  • {U} - Blue mana
  • {C} - Colorless mana
  • {S} - Snow mana symbol
  • {C/P} - Colorless Phyrexian mana
  • {R/P} - Red Phyrexian mana
  • {G/P} - Green Phyrexian mana
  • {U/P} - Blue Phyrexian mana
  • {B/P} - Black Phyrexian mana
  • {W/P} - White Phyrexian mana

Hybrid Mana Symbols:

White hybrid: {W/B} {W/R} {W/G} {W/U} -

Black hybrid: {B/W} {B/R} {B/G} {B/U} -

Red hybrid: {R/W} {R/B} {R/G} {R/U} -

Green hybrid: {G/W} {G/B} {G/R} {G/U} -

Blue hybrid: {U/W} {U/B} {U/R} {U/G} -

"Two-brids": {2/W} {2/B} {2/R} {2/G} {2/U} -

Colorless hybrid: {C/W} {C/B} {C/R} {C/G} {C/U} -

Phyrexian Hybrid Mana Symbols:

White Phyrexian hybrid: {W/B/P} {W/R/P} {W/G/P} {W/U/P} -

Black Phyrexian hybrid: {B/W/P} {B/R/P} {B/G/P} {B/U/P} -

Red Phyrexian hybrid: {R/W/P} {R/B/P} {R/G/P} {R/U/P} -

Green Phyrexian hybrid: {G/W/P} {G/B/P} {G/R/P} {G/U/P} -

Blue Phyrexian hybrid: {U/W/P} {U/B/P} {U/R/P} {U/G/P} -

Numeric Symbols:

  • {0} through {99} - Generic mana costs (0-99)
  • {X} - X symbol

Special Symbols:

  • {T} - Tap symbol
  • {Q} - Untap symbol
  • {E} - Energy symbol

Example Usage:

rules_text: "{T}: Add {W} or {U} to your mana pool."

T : Add W or U to your mana pool

🧪 Basic Examples

Single Card

Generate:

mtg_card_maker generate_card \
  --name="Lightning Bolt" \
  --mana-cost=R \
  --type-line=Instant \
  --rules-text="Deal 3 damage to any target." \
  --color=red

Add to YAML:

mtg_card_maker add_card deck.yml \
  --name="Counterspell" \
  --mana-cost="UU" \
  --type-line="Instant" \
  --rules-text="Counter target spell." \
  --color="blue"

Shortcuts:

  • g or gc for generate_card
  • a or ac for add_card

Generate a Sprite Sheet

For printing or displaying multiple cards on a webpage, using a sprite sheet is recommended. This approach embeds fonts and gradients once per sheet instead of repeating them for each individual card, improving file size and loading efficiency. Generate a sprite sheet from YAML configuration:

Required Arguments:

  • YAML_FILE: Path to YAML configuration file
  • OUTPUT_FILE: Output filename for the sprite sheet

Optional Options:

  • --cards-per-row: Number of cards per row in sprite (default: 4)
  • --spacing: Spacing between cards in pixels (default: 30)
mtg_card_maker generate_sprite deck.yml sprite_sheet.svg \
--cards-per-row=3 --spacing=5

Shortcuts:

  • gs or gcs for generate_sprite

🖼️ Experimental WebP Conversion

⚠️ Experimental Feature - Mac Only

The gem includes experimental support for converting SVG cards to WebP format using Chrome's headless mode. This feature is currently Mac-only and requires specific dependencies.

Why?: It seems a lot more user-friendly for use in things like this README.md file. The file size is bigger and it can't scale so I wouldn't use this option unless something in the SVG isn't working with whatever you are trying to do. You should also report that at https://github.com/joe-sharp/mtg_card_maker/issues . Thanks in advance!

Prerequisites:

  • macOS: Chrome must be installed at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • cwebp: Google's WebP encoder must be installed (install via Homebrew: brew install webp)

Usage:

# Convert a single SVG card to WebP
bin/svg_to_webp output_card.svg

# Convert any SVG file to WebP
bin/svg_to_webp path/to/your/card.svg

Features:

  • Lossless Conversion: High-quality WebP output with transparency support
  • Automatic Cropping: Removes Chrome's window chrome for clean card output
  • Optimized Dimensions: Outputs at 630x880 pixels (standard MTG card ratio)
  • Transparent Background: Preserves transparency for web and design use

Caveats:

  • Platform Limitation: Currently only works on macOS with Chrome installed
  • Dependency Required: Requires cwebp command-line tool for final processing
  • Experimental Status: May have issues with complex SVG content or Chrome updates
  • File Size: WebP files may be larger than optimized SVGs for simple cards

Future Plans:

  • Cross-platform support (Windows, Linux)
  • Integration with main CLI commands

🔮 Examples

A card featuring artwork of a bearded man writing on a magical scroll with a feather pen

Generate a creature card:

mtg_card_maker generate_card \
  --name="Joe Sharp" \
  --mana-cost=3UR \
  --type-line="Engineer - Fullstack" \
  --rules-text='When Joe Sharp enters the battlefield, all malfunctioning computers begin working.\nWhenever you cast a Red spell, draw a card.\n\n{E}: Debug program. Ignore this cost, if a Coffee token is in play.\n\n' \
  --flavor-text='\"Nothing is true, everything is a string.\"\n\t\t\t\t- The ENV Creed' \
  --power=3 \
  --toughness=3 \
  --border-color=gold \
  --color=blue \
  --art=images/joe.webp

Add multiple cards to a YAML file:

mtg_card_maker add_card deck.yml --name="Lightning Bolt" --mana-cost="R" --type-line="Instant" --rules-text="Deal 3 damage to any target." --color="red"

mtg_card_maker add_card deck.yml --name="Counterspell" --mana-cost="UU" --type-line="Instant" --rules-text="Counter target spell." --color="blue"

Generate a sprite sheet from YAML:

mtg_card_maker generate_sprite deck.yml sprite_sheet.svg --cards-per-row=3 --spacing=20

🚧 Development

Setup

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Development Workflow with Guard

This project uses Guard for automated testing and code quality checks during development. Guard monitors file changes and automatically runs relevant tests and checks.

Start Guard:

bundle exec guard

What Guard monitors:

  • RuboCop: Automatically checks code style when Ruby files change
  • RSpec: Runs tests when spec files or corresponding lib files change
  • Status Summary: Monitors changes and runs bin/status_summary to check card generation integrity (end-to-end tests)

Guard Output:

  • RuboCop results are saved to tmp/rubocop_status.txt
  • RSpec results are saved to tmp/rspec_status.txt
  • Status summary provides real-time feedback on code quality and card generation

Development Benefits:

  • Zero Configuration: Just run bundle exec guard and start coding
  • Instant Feedback: See test results and code quality status immediately
  • Regression Prevention: Automatic integrity checks prevent breaking changes
  • Productivity Boost: Focus on coding while Guard handles quality assurance

Status Summary Script

The bin/status_summary script provides a comprehensive development status overview, it is meant to only be run by guard.

What it does:

  • Generates test cards and sprite sheets to verify functionality
  • Compares generated output against expected fixtures
  • Checks for unexpected changes in SVG files
  • Displays status indicators, requires you run with guard:
    • ✅ RuboCop violations (with count if any)
    • ✅ RSpec test failures (with count if any)
    • ✅ Card generation integrity
    • ✅ Sprite sheet generation integrity

Status Indicators:

  • ✅ - All good
  • ⚠️ - Issues detected (with count)
  • ❌ - Failures
  • 🔄 - Unexpected changes detected

Interactive Development

Console:

bin/console

Start an interactive Ruby console with the gem loaded for experimentation.

Manual Testing: Note: just use guard

# Run all tests
bundle exec rspec

# Check code style
bundle exec rubocop

# Generate test cards

# See examples above, but you will need to use bin/mtg_card_maker from the project root to use the in-development code.

# Or run `bundle exec guard` and monitor output_card.svg and color_cards_sprite.svg for changes, it is far better, really.

🏗️ Technical Architecture

Design Patterns & Best Practices:

  • Layered Architecture: Clean separation between card components (art, text, frame, border)
  • Factory Pattern: LayerFactory provides flexible layer creation
  • Service-Oriented Design: Dedicated services for icons, sprites, gradients, and text rendering
  • Single Responsibility: Each class has a focused, well-defined purpose
  • Dependency Injection: Clean interfaces and testable components

Advanced Features:

  • Symbol Replacement Engine: Sophisticated parsing of MTG notation with regex optimization
  • Dynamic Gradient Generation: Real-time SVG gradient creation for card colors
  • Font Embedding System: Base64 font embedding for portable SVG files
  • Sprite Sheet Optimization: Shared asset management reducing file sizes considerably
  • Comprehensive Validation: Robust error handling and input validation throughout

📰 Documentation

API Documentation

The gem includes comprehensive YARD documentation for all classes and methods. You can generate and view the documentation locally:

Generate Documentation:

bundle exec yard doc

Serve Documentation Locally:

bundle exec yard server

Then visit http://localhost:8808 to browse the documentation.

Installation and Release

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

🤝🏻 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/joe-sharp/mtg_card_maker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

🪪 License

MTG Card Maker © 2025 by Joe Sharp is licensed under CC BY-NC-ND 4.0

The gem is available as open source under the terms of this license.

© 2025 Joe Sharp. Some rights reserved. MTG Card Maker 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.

The removal or alteration of copyright notices, attributions, and/or QR codes from generated images constitutes a material breach of the license agreement. All copyright notices and identifying marks must remain intact and unmodified in accordance with the terms of use.

🧙🏻 Code of Conduct

Everyone interacting in the MTG Card Maker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.