mtg-online-drafter/docs/development/plans/mtg-engine-and-ux.md

Implementation Plan: MTG Rules Engine & High-Velocity UX

Objective

Implement a strict Magic: The Gathering rules engine (Backend) and a "Rich Input" high-velocity user experience (Frontend). The goal is to enforce 100% of the Comprehensive Rules on the server while allowing fluid, gesture-based actions on the client.

Reference: MagicCompRules 20251114.txt

---

PART 1: THE RULES ENGINE (Server-Side Logic)

A. Game Setup & Initialization (CR 103)

The engine must execute this sequence automatically before the first turn:

1. Deck Validation: Verify decks meet format requirements (e.g., 60 cards min).
2. Life Initialization: Set Life Totals to 20.
3. The Mulligan Process (CR 103.5):
   • Initial Draw: Both players draw 7 cards.
   • Decision Loop: Prompt players in turn order: "Keep Hand" or "Mulligan".
   • Execution: If Mulligan, shuffle hand into library and draw 7 new cards.
   • London Rule: For each Mulligan (N), user must select N cards to bottom.
   • Concurrency: Decisions sequential, Shuffles/Draws simultaneous.

B. The Turn Structure State Machine (CR 500)

Strict phase cycle. Priority (CR 117) must be passed by both players to advance.

1. Beginning Phase (CR 501)

   • Untap Step: AP untaps all permanents. No Priority.
   • Upkeep Step: Triggers go on stack. AP Priority.
   • Draw Step: AP draws. Triggers. AP Priority.

2. Pre-Combat Main Phase (CR 505)

   • AP may Play Land (Special Action, 1/turn, Stack empty).
   • AP may Cast Sorcery/Creature/Artifact/Enchantment/Planeswalker.

3. Combat Phase (CR 506)

   • Start of Combat: Triggers. Priority.
   • Declare Attackers (CR 508):
     • AP selects attackers & targets (Player/Planeswalker).
     • Engine validates restrictions & taps attackers.
     • Triggers. AP Priority.
   • Declare Blockers (CR 509):
     • DP assign blockers.
     • Engine validates (Flying, Menace, etc.).
     • Damage Ordering (if multi-blocked).
     • Triggers. AP Priority.
   • Combat Damage (CR 510):
     • AP assigns damage (Lethal to 1st, then rest).
     • Damage dealt simultaneously.
     • Priority Check.
   • End of Combat: Priority Check.

4. Post-Combat Main Phase

   • Identical to Pre-Combat Main.

5. Ending Phase (CR 512)

   • End Step: Triggers. Priority.
   • Cleanup Step (CR 514):
     • Discard to hand size.
     • Remove marked damage.
     • No Priority (unless trigger occurs).

C. The Interaction Core: Priority & The Stack (CR 405 & 117)

LIFO (Last-In, First-Out) Array.

• Priority Passing (CR 117.3d): Game advances only when all players pass on empty stack.
• Response Window: After cast, AP gets priority. If AP passes -> DP gets priority. If DP passes -> Resolve.
• State-Based Actions (The Referee Check - CR 704): Checked BEFORE every priority gain.
  • Lethal Damage: Damage >= Toughness -> Graveyard.
  • 0 Toughness: Toughness <= 0 -> Graveyard.
  • Legend Rule: Duplicate legendary -> Controller chooses capture.
  • Aura Check: Invalid attachment -> Graveyard.

D. Manual Mana Engine (CR 106)

• Production: Tap Land -> Add color to Floating Pool.
• Spending: Click symbol in pool to pay costs.
• Emptying: Pool empties at end of every Step/Phase.

E. Developer Notes & Edge Cases

• Layer System (CR 613): Must implement 7-Layer system (Copy, Control, Text, Type, Color, Ability, P/T).
• Token Generation: Spawn game object with stats.
• Failure States: Insufficient mana -> Bounce, Warning Flash.

---

PART 2: THE "HIGH-VELOCITY" UX (Frontend Specification)

1. The "Smart" Priority Button

Context-aware button (Bottom Right).

• Green ("Pass"): Stack empty. clicking passes/advances.
• Orange ("Resolve"): Stack has object. Click resolves top.
• Red ("Damage/Block"): Mandatory manual assignment waiting.
• Blue ("Choice"): Modal choice required.
• "Yield" Toggle: Auto-pass priority until End Step (unless response needed).

2. Gesture Controls (Mouse/Touch)

• Swipe-to-Tap: Drag line across background/cards. Intersected lands toggle & add mana.
• Combat Swipes:
  • Attack: Swipe Up/Forward.
  • Cancel Attack: Swipe Down/Back.
  • Block: Drag blocker onto attacker.
• Targeting Tether: Visual "rope" (Bezier curve) from source to target.

3. Contextual Radial Menus

Scenario: User taps Dual Land.

• Interaction: Pie menu spawns under cursor.
• Action: Slide toward symbol to select. Minimal travel.

4. Visualizing "The Stack"

Vertical list of tiles on screen edge.

• Hover/Long-press: Show source card.
• Targeting: Tiles must be valid targets for spells.

5. The "Inspector" Overlay

Long-press/Right-click on card.

• Display: High-Res Art + Oracle Text.
• Live Math: Show Net Power/Toughness (Base + Layers).

---

Task Breakdown & Status

Backend (Rules Engine)

• Core Structures: StrictGameState, Phase, Step Types.
• State Machine Baseline: Phase advancement logic.
• Priority Logic: Passing, resolving, resetting.
• Basic Actions: Play Land, Cast Spell.
• Stack Resolution: Resolving Spells to Zones.
• SBAs Implementation: Basic (Lethal, 0 Toughness, Legend).
• Advanced SBAs: Aura Validity check.
• Manual Mana Engine: Floating Pool Logic.
• Game Setup: Mulligan (London), Deck Validation.
• Combat Phase Detail: Declare Attackers/Blockers steps & validation.
• Layer System: Implement 7-layer P/T calculation.

Frontend (High-Velocity UX)

• Game View: Render State Types.
• Phase Strip: Visual progress.
• Smart Button: Basic States (Green/Orange/Red).
• Gesture Engine: Swipe-to-Tap.
• Stack Visualization: Basic Component.
• Gesture Polish: Combat Swipes, Targeting Tether.
• Smart Button Advanced: "Yield" Toggle.
• Radial Menus: Pie Menu for Dual Lands/Modes.
• Inspector Overlay: Live Math & Details.