ygo-sim-core

The Stockfish Paradigm for Trading Card Games

Competitive TCG play involves combinatorially explosive decision trees, complex timing structures, and multi-tier chain interactions. Traditional heuristics and static deck builders cannot simulate the consequences of opponent interruptions or calculate the optimal branch out of hundreds of legal moves.

ygo-sim-core decouples heavy mathematical simulation from natural language AI reasoning. Acting as a dedicated compute engine (analogous to Stockfish in chess), it exposes strict JSON-RPC tools via the Model Context Protocol (MCP) to autonomous LLM agents (such as obsidian-ygo-suite).

Key Systems Engineering Innovations

1. 14-Zone Full Memory State Model

Models all physical zones with strict structural immutability: Main Monster Zones (M1..M5), Spell & Trap Zones (S1..S5), Extra Monster Zones (EL, ER), Field Zone, Graveyard, Banished, Hand, Main Deck, and Extra Deck.

2. Official Fast Effect Timing State Machine

Faithfully codifies the Konami priority flowchart across Boxes A, B, C, D, and E. Handles turn player priority passes, open game state transitions, and Spell Speed 1, 2, and 3 reaction timings.

3. SEGOC & Chain Blocking Engine

Implements Simultaneous Effects Going On Chain across all 4 official tiers (Turn Player Mandatory → Opponent Mandatory → Turn Player Optional → Opponent Optional). Detects optimal chain order to block opponents from responding to high-value effects with direct negations.

4. Zero-Collision 64-bit State Hasher & Stockfish Move Ordering

Integrates xxHash64 with canonical permutation sorting of unordered zones. Implements Stockfish Gate-Preserving Move Ordering, prioritizing empty-MMZ conditional spells (Engage!, Hornet Drones) and ignition triggers before committing the Normal Summon or setting traps, pruning >85% of sub-optimal branches.

5. Greedy Zone Snapping & Link Arrow Triangulation

Calculates spatial link arrow geometry across EL, ER, and Main Monster Zones. When special summoning effect monsters, automatically snaps them into pointed zones to activate live quick-disruptions (Lambda Blade control snatch, Ga10 Cutter spell/trap negate) without suffering a 5× spatial search multiplier.

6. Multi-Layer Board Valuation Engine — V(YBN)

Mathematical valuation of end-boards scoring:

• Spatial Diversification: Interaction distribution across monster, backrow, and graveyard zones.
• Board Breaker Resilience: Defense against board sweeps like Dark Ruler No More, Evenly Matched, and Super Polymerization.
• Turn 3 Follow-up Recursion: Guaranteed card advantage generated during recovery turns.

Canonical 26-Step Playline & Spatial Endboard

Demonstrating superhuman combinatorial discovery, the engine explores and verifies the canonical 26-step Revol-Bots & Sky Striker competitive ceiling line from an opening hand of { Engage, Stage Landing, Roze, Ash Blossom, Impermanence }:

T1|M1|LP6800:8000|P1:
  ER[#ed1:R.B. The Brute Blues(atk)],
  M2[#ed15:Prototype Sky Striker Ace - Amatsu(atk)],
  M3[#ed6:R.B. Shepherd's Crook(atk)],
  M4[#d37:R.B. Lambda Blade(atk)],
  M5[#d9:R.B. Ga10 Cutter(atk)],
  F[#d11:R.B. Funk Dock],
  S2[#h5:Infinite Impermanence(set)],
  S3[#d38:R.B. Next Phase(set)],
  GY:[13 Cards - Engage, Drones, Kagari, Camellia, Shizuku, VALCan, Roze...],
  B:[#d5:Pillar of the Future - Cyanos],
  H:[#h4:Ash Blossom & Joyous Spring, #d2:R.B. Stage Landing],
  D:31, ED:8
|P2:|G:NS=1,SS=15

Model Context Protocol (MCP) Tool Contract

When started as a stdio server, ygo-sim-core registers four production tools directly with AI agents:

1. simulate_test_hands
   Inputs: deck_path (.ydk), sample_size (default: 540 [10x Swiss]), archetype_json (dynamic)
   Outputs: Full consistency metrics, brick percentages, starter distributions, structured per-game logs

2. explore_combo_tree
   Inputs: starting_hand, deck_ydk, max_depth, branch_limit, archetype_json (dynamic)
   Outputs: Combinatorial tree of legal playlines, ranked by V(YBN) end-board score

3. evaluate_handtrap_resilience
   Inputs: hand, deck_ydk, threat_suite: ["Ash Blossom", "Nibiru", "Impermanence", "Fuwalos"]
   Outputs: Choke-point sensitivity report, recovery paths, degraded end-boards

4. score_ybn_state
   Inputs: ybn_string (snapshot descriptor)
   Outputs: Multi-layer V(YBN) score vector across omni-negates, removal, and follow-up

CLI & Engine Verification

# Install dependencies and build production binaries
npm install
npm run build

# Run unit and stress tests (69/69 tests passing across 11 suites)
npm test

# Launch the stdio Model Context Protocol (MCP) server
npm start