← Back to Portfolio
Haunted Labs Initiative · RFC 0001

YGN Standard (Yu-Gi-Oh! Game Notation)

The open, human-readable, deterministic algebraic standard for competitive Yu-Gi-Oh! match logs, game state snapshots (YBN), and AI arbitration—modeled after Chess PGN and FEN.

⚡ Launch Match Notary Web Tool → View on GitHub Read RFC 0001 Specification →

The Problem: 25 Years of Format Fragmentation

Digital Yu-Gi-Oh! match history has historically suffered from extreme tooling fragmentation:

  • Manual Simulators (Dueling Book): Export raw browser DOM clickstreams (duel_log.txt), where over 91% of lines are pure UI noise (such as "Player viewed deck", "Player signaled OK"). A simple 3-turn duel produces 734 lines and 32KB of redundant text, making automated indexing, tactical analytics, and LLM reasoning impractical.
  • Automated Simulators (YGO Omega, EDOPro): Record matches in closed, binary replay formats (.yrp). These files desynchronize and break whenever card databases update, cannot be diffed in Git, and cannot be consumed by search engines or AI agents.
The Haunted Labs Mission
Just as chess revolutionized game theory and computing by standardizing on PGN (Portable Game Notation) and FEN (Forsyth-Edwards Notation), modern competitive trading card games require an open, formal, algebraic standard.

The Solution: YGN & YBN

Engineered under Haunted Labs, the specification establishes two complementary standards governed by RFC 0001:

  1. YGN (Yu-Gi-Oh! Game Notation): An action-based algebraic grammar capturing normal and special summons, effect activations, target declarations, battle steps, and LIFO chain resolution stacks.
  2. YBN (Yu-Gi-Oh! Board Notation): A snapshot descriptor encoding card identities and zone positions across all 14 field zones, graveyard, banished piles, and hands in a single line.
  3. Deck-Scoped Alias Registry: Maps 8-digit Konami passcodes from standard .ydk files into compact #1..#40 tokens, achieving an 88% to 94% compression ratio over raw simulator logs.

Canonical YGN Match Notation & YBN Snapshot

Below is a complete, verified Turn 1 sequence conforming to RFC 0001 and transcribed via the ygo-notary standard engine. It demonstrates metadata headers, the Deck-Scoped Alias Registry, chain resolution stacks, and the resulting single-line YBN board snapshot:

match_sample.ygn RFC 0001 Canonical Syntax 
[Event "Remote YCS Top 8 - Match 1"]
[Format "TCG Advanced"]
[Player1 "nedsonbr" 8000]
[Player2 "Opponent" 8000]

[Deck1_Aliases]
1:44001993:Exceptional Schedule
2:12266229:Urgent Schedule
3:98684220:Night Train Blue Traveler
4:24088928:Infinitrack Harvester
e1:59400890:Qliphort Genius

[Deck2_Aliases]
o1:70405001:Mulcharmy Purulia

T1: nedsonbr vs Opponent
@SP
  [C1: A(o.H)[#o1:Purulia]>o.GY // R1: OK ~LING(o.+H)]
@M1
  [C1: A(H)[#1:Exceptional]>S3 // R1: +H[#2:Urgent]o.M3, [#1]>GY]
  [C1: A(H)[#2:Urgent]>S3 // R1: S[#3:Blue Traveler](def)>M4M3GY]
  L[#4:M3 + #3:M4]>ER[#e1:Genius](atk))
Anatomy of the Algebraic Line
  • Deck-Scoped Aliases: #1..#4 map passcodes from .ydk decklists, compressing repetitive names while retaining deterministic card identity.
  • LIFO Chain Protocol: [C1: Activation // R1: Resolution] encapsulates action and resolution without recording redundant browser UI handshakes.
  • 2-Character Coordinates: ER (Extra Monster Zone Right), M3 (Monster Zone 3), S3 (Spell Zone 3), o.M3 (Opponent Monster Zone 3).
  • YBN Board State: Serializes all 14 field zones, graveyard contents, hand/deck tallies, and active lingering locks into a deterministic string for immediate evaluation by ygo-sim-core.

Comparative Benchmark

Format Avg. File Size (3 Turns) Signal-to-Noise LLM / Search Readable Database Desync Immune
Raw DOM Log ~32 KB (734 lines) < 9% No (Context Bloat) Yes
Binary .yrp ~4 KB (Binary) High (Engine-only) No No (Breaks on patch)
YGN Standard ~1.8 KB (35 lines) 100% Yes (Algebraic) Yes

Multi-Language Ecosystem & Governance

YGN is maintained as an open community RFC specification with cross-platform reference tooling:

  • TypeScript / JavaScript: Reference parser, Lexer, and Dueling Book converter published on npm.
  • Python 3: High-performance bindings for data science, replay analysis, and machine learning pipelines.
  • Lua Emitter: Direct integration layer for game simulator engines (EDOPro, Omega core).