Portable Game Notation
Portable Game Notation (PGN) is a standard plain-text format for recording chess games, encompassing both the sequence of moves and associated metadata, designed to be easily readable and writable by humans while also facilitating parsing and generation by computer programs.[1] Developed in 1994 by Steven J. Edwards in collaboration with the rec.games.chess Usenet community, PGN emerged to resolve incompatibilities in data interchange among diverse chess software applications, enabling the global sharing of public-domain chess data among players, publishers, and researchers.[1][2]
The format's structure consists of two primary sections: a tag section containing metadata in key-value pairs enclosed in square brackets, and a movetext section detailing the game's moves using Standard Algebraic Notation (SAN), along with optional annotations, variations, and result indicators such as 1-0 for white wins or 1/2-1/2 for draws.[1] The mandatory Seven Tag Roster includes essential details like [Event], [Site], [Date], [Round], [White], [Black], and [Result], ensuring a consistent baseline for game documentation across implementations.[1] PGN files typically use the .pgn extension and support extensions like Extended Position Description (EPD) for capturing specific board positions with analytical opcodes, such as "bm" for best moves.[1]
As the most widely adopted standard for chess game storage and transmission, PGN has become integral to chess databases, analysis tools, and online platforms, with binary variants like PGC (PGN Game Coding) introduced for more efficient storage in large archives.[3][1] Its open, non-proprietary nature has promoted interoperability, though supplements and revisions—such as those by Alan Cowderoy in 2001—continue to refine its capabilities for modern applications.[4]
Introduction
Definition and Purpose
Portable Game Notation (PGN) is a standard plain text format for recording chess games, encompassing moves, metadata, and annotations, utilizing only ASCII characters to ensure broad compatibility.[1] Developed and coordinated by Steven J. Edwards in collaboration with the rec.games.chess Usenet community in 1994, PGN emerged as a non-proprietary solution to standardize chess game representation across diverse software and systems.[1]
The primary purpose of PGN is to enable human-readable documentation and machine-parsable exchange of chess games, facilitating archival storage, transmission, and analysis without reliance on specialized or proprietary tools.[1] By structuring data through core components such as tag pairs for metadata and movetext for move sequences, PGN supports efficient sharing among players, publishers, and researchers worldwide.[1]
PGN files typically bear the .pgn extension and can contain multiple games in a single sequential file, allowing for compact organization of game databases.[1] This format's emphasis on portability ensures seamless integration with various chess applications for viewing, editing, and studying games.[1]
Portable Game Notation (PGN) defines two distinct formats for handling game data: the import format, which provides flexibility for user-generated input, and the export format, which ensures strict consistency for machine-readable output. These formats allow software to parse and generate PGN files reliably while accommodating variations in how data is created. The distinction balances ease of use for human editors with the need for interoperability across chess programs.[1]
The PGN import format employs lax rules to tolerate ambiguities and variations commonly found in manually prepared files, facilitating easier entry and editing by users. It permits flexible spacing between tokens, inconsistent capitalization (such as varying cases for piece symbols), and optional elements like line breaks or justifications within the movetext and headers. Comment delimiters can include both semicolon-based inline notes and curly brace-enclosed blocks, and the format accepts minor deviations as long as core tokens—such as move symbols in Standard Algebraic Notation (SAN)—remain recognizable. This leniency ensures that software can process a wide range of input without requiring perfect adherence to syntax, reducing errors during data ingestion.[1]
In contrast, the PGN export format imposes strict rules to produce uniform, byte-equivalent output across different programs, promoting reliable parsing and archival storage. Tokens must be separated by exactly one space, with no tabs or multiple spaces allowed, and all lines are left-justified and limited to fewer than 80 characters to avoid wrapping issues. Capitalization is standardized—for instance, piece designations use uppercase letters (P for pawn, N for knight, etc.) and castling moves are written as "O-O" or "O-O-O." Comments are restricted to specific structured forms, and the format mandates complete inclusion of required elements, such as the seven-tag roster in headers, without undefined symbols or ambiguities. This precision enables efficient tokenization and processing in downstream applications.[1]
The key differences between the formats lie in their tolerance for flexibility versus enforcement of exactness: import accommodates varied human input to prevent rejection of valid but imperfect files, while export eliminates such variations to guarantee consistent machine handling. This dual approach, outlined in the original 1994 PGN specification, addresses the practical needs of chess software development by separating input parsing from output generation, ultimately enhancing usability and data reliability without compromising the notation's core structure.[1]
History
Origins
Portable Game Notation (PGN) originated in late 1993 when Steven J. Edwards (1957–2016), an American computer scientist and chess programmer, proposed it as a standardized text-based format for recording and sharing complete chess games. Edwards developed PGN through discussions in the Usenet newsgroup rec.games.chess, aiming to unify disparate notation systems used by chess enthusiasts for electronic exchange via email and early online forums. This effort addressed the growing need for a portable, human- and machine-readable method to distribute game data among global players, publishers, and researchers.[1][5][2]
Before PGN, existing formats such as the Extended Position Description (EPD)—co-authored by Edwards and John N. Stanback in the early 1990s—focused solely on static board positions, lacking support for move sequences or contextual metadata like player identities or tournament details. PGN extended these concepts to encompass full game notation, incorporating standard algebraic notation for moves alongside structured header tags, making it ideal for transmission over bandwidth-limited connections like those in 1990s bulletin board systems. EPD's position-centric design, first implemented in chess engines like Zarkov, highlighted the gap PGN filled by enabling comprehensive game archives.[1][6]
Edwards released the first draft of the PGN specification in late 1993, influenced by established algebraic notation practices and the practical demands of email-based chess communication. This initial version rapidly gained adoption within online chess communities, appearing in bulletin board systems for game sharing and being integrated into early software tools, which accelerated its use for analyzing and distributing professional and amateur matches.[1][7]
Standardization and Evolution
The formal specification for Portable Game Notation (PGN) was published on March 12, 1994, as the "Portable Game Notation Specification and Implementation Guide," coordinated by Steven J. Edwards with contributions from the rec.games.chess Usenet community.[1][8] This document established PGN as a plain-text format for chess game data, defining essential elements such as the seven-tag roster for headers, standard algebraic notation for moves, and numeric annotation glyphs (NAGs) with codes from $0 to $139 for evaluations like good moves ($1) or blunders ($4).[1]
Key evolutions included the 2001 supplement, revised on September 8 by Alan Cowderoy and collaborators, which added optional tags like WhiteClock and BlackClock for recording time controls and introduced embedded comment commands (e.g., [%clk h:mm:ss]) for precise clock data from electronic boards.[4] Variant support was facilitated early through the optional FEN tag in the original specification, allowing non-standard starting positions for games like Chess960.[1] NAGs saw de facto expansions beyond the initial 140 via software implementations, with additional codes (e.g., $136 for White severe time control pressure) adopted for richer annotations without formal revision. No major official updates occurred after 2000, but practical extensions emerged through widespread software adoption, maintaining backward compatibility.[9]
Adoption milestones in the late 1990s saw PGN integrated into leading chess databases, including ChessBase, enabling efficient import and export of game collections.[10] By this period, PGN became standard for FIDE tournament reporting, with requirements for PGN files in title norm submissions and rating lists.[11]
As of 2025, PGN remains the de facto standard for chess game exchange across software, databases, and organizations like FIDE, supporting millions of games annually.[11] Minor de facto updates for online platforms include embedding URLs in the Site tag to reference game pages, a practice common since around 2020 on sites like Chess.com and Lichess for enhanced digital sharing.[3]
Seven Tag Roster
The Seven Tag Roster (STR) consists of seven mandatory tag pairs that form the essential header section at the beginning of every Portable Game Notation (PGN) file, providing standardized metadata for chess games to facilitate archival storage and data interchange.[1] These tags ensure a minimal but consistent set of information about the game context, required for any valid PGN record.[1]
Each tag pair follows the syntax [TagName "TagValue"], where the tag name is a case-sensitive identifier without spaces, and the value is enclosed in double quotes as a string, potentially containing escaped special characters if needed.[1] In the standard export format, the STR tags must appear in a fixed sequential order before any optional tags, with no whitespace immediately adjacent to the brackets, and a single space separating the tag name from its value.[1] The order is not strictly enforced in all import scenarios but is recommended for interoperability across chess software.[1]
The specific tags in the STR are as follows:
| Tag | Description | Example Value |
|---|
| Event | The name of the tournament, match, or event in which the game was played. | "World Chess Championship" |
| Site | The location where the event took place, including city and venue if applicable. | "New York, NY USA" |
| Date | The starting date of the game in YYYY.MM.DD format, using leading zeros where necessary. | "1992.09.05" |
| Round | The round number or identifier within the event, as an integer or descriptive string. | "3" or "Semifinal" |
| White | The player or team playing the white pieces, typically in "Lastname, Firstname" format. | "Kasparov, Garry" |
| Black | The player or team playing the black pieces, in the same naming convention. | "Karpov, Anatoly" |
| Result | The final outcome of the game: "1-0" for white wins, "0-1" for black wins, "1/2-1/2" for draw, or "*" for ongoing or unfinished games. | "1-0" |
Optional Tag Pairs
Optional tag pairs in Portable Game Notation (PGN) consist of non-mandatory header elements that follow the same syntactic structure as the core tags, enclosed in square brackets as [Tag "Value"], providing supplementary metadata to enhance the representation of chess games without altering the fundamental format.[1] These tags extend beyond the foundational Seven Tag Roster—such as Event, Site, Date, Round, White, Black, and Result—by allowing for additional details that support richer data interchange, including information on annotations, initial positions, and game conditions.[1]
Key examples of optional tag pairs include the Annotator tag, which specifies the name or names of individuals who provided commentary on the game, formatted as [Annotator "Name"], to credit analytical contributions.[1] The FEN tag records a custom starting position using Forsyth-Edwards Notation, such as [FEN "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"], and must be paired with [SetUp "1"] to indicate a non-standard setup, enabling the notation of variant games or interrupted positions.[1] TimeControl describes the game's timing rules, for instance [TimeControl "40/9000"] for 40 moves in 150 minutes or [TimeControl "300"] for a 5-minute sudden-death limit, aiding in the replication of tournament conditions.[1] For the Result tag, which is part of the Seven Tag Roster, optional details can clarify outcomes like ongoing games marked by an asterisk in the movetext (), such as [Result ""], to denote unfinished matches.[1] PlyCount provides the total number of half-moves (plies) in the game, e.g., [PlyCount "86"], offering a quick summary of game length for archival purposes.[1]
Usage guidelines emphasize that optional tags should be added selectively to increase informational depth without conflicting with the Seven Tag Roster's essentials; they are case-sensitive, with tag names starting in uppercase, and in export format, each appears on a separate line followed by a blank line before the movetext.[1] Import parsers must tolerate flexibility, such as multiple tags per line, to ensure broad compatibility across software implementations.[1] These tags must not redefine or override the core roster values, maintaining structural integrity while allowing customization.[1]
The framework for optional tag pairs was formalized in the 1994 PGN specification by Steven J. Edwards, which expanded the system to theoretically support up to 255 distinct tags through a flexible symbol set, though only a limited number have become standardized for practical use in chess databases and analysis tools.[1] This evolution reflects PGN's design goal of balancing simplicity with extensibility for evolving needs in game documentation.[1]
Game Body
Movetext
The movetext section in Portable Game Notation (PGN) constitutes the body of a game record, following the header information and encoding the sequence of moves using Standard Algebraic Notation (SAN).[1] It begins with White's first move and alternates between White and Black, ensuring a complete and unambiguous representation of the game progression.[1] Each line in the movetext is left-justified, limited to fewer than 80 characters, with tokens separated by single spaces, and the section concludes with an empty line or the game result.[1]
Moves are numbered sequentially, starting from 1 for White's initial move, followed by the corresponding Black response on the same line where possible.[1] For example, the opening might appear as 1. e4 e5 2. Nf3 Nc6, where the integer indicates the move number, followed by a period for White's turn and optionally ellipsis (...) for Black's.[1] In SAN, pieces are denoted by uppercase letters—K for king, Q for queen, R for rook, B for bishop, N for knight, and P for pawn (though P is typically omitted for pawn moves in export format).[1] The destination square is specified using file (a-h) and rank (1-8), such as e4 for a pawn advancing to e4.[1] Captures are marked with an "x" before the destination, as in Bxc5 for a bishop capturing on c5, and ambiguities (e.g., multiple possible pieces) are disambiguated by including the origin file, rank, or both, like Nbd2.[1]
Special move types follow defined suffixes: checks are indicated by "+" (e.g., Qh5+), and checkmates by "#" (e.g., Qh7#).[1] Promotions append an equals sign followed by the promoted piece symbol, such as e8=Q for a pawn promoting to queen on e8.[1] Castling is represented compactly as O-O for kingside or O-O-O for queenside.[1]
Variations and alternatives are handled through a recursive structure using parentheses, allowing nested branches for alternative lines.[1] For instance, 1. e4 e5 2. Nf3 (2. Bc4) Nc6 denotes a variation where White plays Bc4 instead of Nf3 on move 2.[1] The movetext must terminate with a result symbol: 1-0 for White's victory, 0-1 for Black's, 1/2-1/2 for a draw, or * for an ongoing or unknown result.[1] Comments can be inserted inline within curly braces {} for explanatory notes, but they do not alter the move sequence.[1]
In Portable Game Notation (PGN), comments provide explanatory text that does not affect the parsing of the main game moves, allowing authors to include analysis, diagrams, or notes while preserving the format's portability across chess software and databases.[1] These comments are integrated into the movetext structure, the core sequence of moves, to support detailed game records without disrupting automated processing.[1]
There are two primary types of comments in PGN. The first type uses a semicolon (;) to initiate a "rest of line" comment, which extends from the semicolon to the end of the line and is ignored by parsers.[1] For example, after a move like "1. e4 ; This opens the center", the semicolon-prefixed text serves as a trailing note.[1] The second type employs curly braces {} to enclose inline or multi-line text, starting with an opening brace and terminating with a matching closing brace, which can span multiple lines for more extensive remarks.[1] Within these braces, curly braces are escaped using a backslash (e.g., { for a literal opening brace and } for a closing brace); double quotes and backslashes do not require escaping.[1]
Variations in PGN represent alternative move sequences or branches from the main line, enclosed in parentheses () to form Recursive Annotation Variations (RAVs), which can be nested recursively for complex analyses.[1] For instance, a game might read "1. e4 e5 2. Nf3 (2. Nc3 ; sidelines) Nc6", where the parenthetical section outlines an alternative second move with its own comment.[1] PGN imposes no formal limit on nesting depth for variations, though practical constraints recommend shallow recursion to maintain readability and processing efficiency.[1]
Both comments and variations are excluded from move parsing, enabling software to extract the primary game flow while optionally rendering the supplementary content for human review.[1] This design facilitates in-depth tactical or strategic commentary, such as embedding textual diagrams or evaluation notes, without compromising the notation's interoperability.[1]
Annotations
Numeric Annotation Glyphs
Numeric Annotation Glyphs (NAGs) are standardized tokens in Portable Game Notation (PGN) used to provide concise, language-independent annotations for moves or positions within the movetext. They consist of a dollar sign ($) immediately followed by a non-negative decimal integer ranging from 0 to 255, though the original 1994 specification defines 140 standard values (0 through 139).[12][1]
NAGs serve as a compact alternative to verbose textual comments, enabling universal parsing by chess software and databases for automated analysis and display.[12] They annotate either the preceding move (values 1–9) or the resulting position (values 10–139), with value 0 acting as a null placeholder.[1] Multiple NAGs can be combined sequentially after a move, such as $1$10 to indicate both a good move and a drawish position.[12]
In the movetext, NAGs appear as distinct tokens immediately following the move they annotate, often alongside symbolic suffixes like ! or ?, though NAGs replace these in export formats for precision. For example, "e4 $1" denotes a good move, while "Qxa8 $4" marks a blunder.[1] This placement ensures they integrate seamlessly into the recursive structure of game records without disrupting move sequences.[12]
The standard NAGs are categorized into move evaluations and positional assessments, drawing from common chess annotation conventions. Representative examples include:
| NAG | Meaning | Traditional Symbol |
|---|
| $1 | good move | ! |
| $2 | poor move | ? |
| $3 | very good move | !! |
| $4 | very poor move | ?? |
| $5 | speculative move | !? |
| $6 | questionable move | ?! |
| $10 | drawish position | = |
| $14 | White has a slight advantage | ↗ |
| $16 | White has a moderate advantage | ↑ |
| $18 | White has a decisive advantage | ↑↑ |
| $36 | White has the initiative | |
| $40 | White has the attack | |
| $140 | reserved (e.g., for future time pressure annotations in extensions) | |
Non-Standard Extensions
In the Portable Game Notation (PGN) standard, Numeric Annotation Glyphs (NAGs) with values from $140 to $255 are explicitly reserved for future definition, allowing implementers to use these 116 slots for custom or software-specific annotations while maintaining the overall format's integrity.[1] This reservation enables extensions beyond the core set of defined NAGs ($1 to $139), but their use is not part of the official specification, potentially leading to implementation variations.[1]
Software vendors have utilized these reserved NAGs for proprietary enhancements. For instance, ChessBase defines additional meanings for NAGs $140 to $167, extending the standard symbols to include more nuanced chess annotations such as specialized tactical or positional markers, which are rendered in their database and publishing tools.[13] Similarly, the Palview chess publishing software assigns meanings to NAGs up to approximately $167, incorporating these for visual representations like diagrams or enhanced symbols in HTML output, though compatibility depends on the importing application.[13]
The primary risk of employing non-standard NAGs lies in diminished portability; many PGN parsers adhere strictly to the defined range and may ignore, strip, or misinterpret extended values during import, resulting in loss of annotation data across different chess software or databases.[1] This issue has prompted ongoing discussions in the chess programming community about formalizing extensions, though no consensus update to the 1994 specification has been adopted as of November 2025.[7]
To mitigate compatibility problems, guidelines recommend avoiding non-standard NAGs in PGN exports destined for general distribution, reserving them instead for internal or specialized workflows.[1] When custom NAGs are necessary, their definitions should be clearly documented in optional PGN header tags, such as [NAGExtensions "Vendor-specific: $150=EngineEval"], to inform users and parsers of the intended meanings.[13]
Examples and Applications
Basic Game Example
A basic example of a Portable Game Notation (PGN) file demonstrates the core structure using the seven tag roster for headers, followed by simple movetext in Standard Algebraic Notation (SAN), and terminated by a game result. This format ensures human readability and machine parsability while adhering to the minimal requirements of the 1994 specification.[1]
Consider the following short game, representing a hypothetical quick resignation after White's opening move:
[Event "Example Game"]
[Site "?"]
[Date "1994.??.??"]
[Round "?"]
[White "Example White"]
[Black "Example Black"]
[Result "1-0"]
1. e4 e5 1-0
[Event "Example Game"]
[Site "?"]
[Date "1994.??.??"]
[Round "?"]
[White "Example White"]
[Black "Example Black"]
[Result "1-0"]
1. e4 e5 1-0
This PGN file begins with the required seven tag roster headers enclosed in square brackets: Event, Site, Date, Round, White, Black, and Result, each providing essential metadata about the game.[1] The movetext section follows, listing moves in numerical order with White's moves prefixed by the move number (e.g., "1. e4") and Black's responses on the same line, using SAN for brevity and clarity.[1] The game concludes with the result token "1-0", indicating White's win, which serves as the termination marker for a valid single-game file.[1]
Such minimal PGN examples highlight the format's simplicity, making it accessible for beginners to record and share games without annotations, variations, or extensions. A single PGN file typically contains one game in this reduced export format, though multi-game files are possible by separating games with blank lines.[1]
Variant and Annotated Example
To illustrate advanced features of Portable Game Notation (PGN), consider an annotated example based on game 29 of the 1992 Fischer-Spassky return match, adapted to demonstrate comments, Numeric Annotation Glyphs (NAGs), and variations as supported in modern PGN implementations. Lichess enables users to add such annotations in studies and export them in PGN format, preserving inline details for analysis.[14]
The following PGN represents the full game with added annotations typical of Lichess exports (e.g., a comment on the opening, a NAG for a development move, and a variation). Optional tags like "Annotator" and "Site" are included to show extended metadata. In a multi-game PGN file, this would be separated from subsequent games by the result marker followed by new tag pairs.
[Event "F/S Return Match"]
[Site "Sveti Stefan/Belgrade, Yugoslavia"]
[Date "1992.11.05"]
[Round "29"]
[White "Fischer, Robert J."]
[Black "Spassky, Boris V."]
[Result "1/2-1/2"]
[Annotator "Example User"]
1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 {This opening is the Ruy Lopez, a sharp Spanish defense variant leading to complex middlegames.} 4. Ba4 Nf6 5. O-O Be7 6. Re1 b5 7. Bb3 d6 8. c3 O-O 9. h3 Nb8 10. d4 Nbd7 11. c4 $6 {Aggressive space gain, but allows Black counterplay (NAG $6 indicates an inaccuracy).} ( 11. Nbd2 {Safer development, maintaining tension.} Bb7 ) b4 12. cxb5 axb5 13. Nc3 Bb7 14. Bg5 h6 15. Bh4 c5 16. dxe5 Nxe5 17. Nxe5 dxe5 18. Bxe7 Qxe7 19. f3 Rd8 20. Qe2 Bc6 21. Rad1 Qf8 22. a3 bxa3 23. bxa3 Qg8 24. Kh1 Rd7 25. Rxd7 Nxd7 26. Rd1 Nc5 27. Qc2 Rb8 28. Rd6 Be7 29. Rxc6 {Initiating exchanges to simplify.} Nxc6 30. Qxc6 Qf8 31. Qc2 Rd8 32. Rxd8 Qxd8 33. Qd3 Qxd3 34. Nxd3 Bf6 35. a4 Kf8 36. Kf2 Ke7 37. Ke2 Kd6 38. Kd2 Kc6 39. Kc3 Kb6 40. Kb4 Ka6 41. a5 Kb7 42. Kc5 Kc7 43. Kd5 Kd7 44. Ke5 Ke7 45. Kf4 Kf6 46. g3 g5+ 47. Kf4 gxf3 48. Kxf3 Bd4 49. h4 Be5 50. g4 Bf4 51. Kg2 Bg3 52. h5 Bf4 53. Kf2 Bg5 54. Kg2 Bf6 55. Kf2 Bg5 56. Kg2 1/2-1/2
[Event "F/S Return Match"]
[Site "Sveti Stefan/Belgrade, Yugoslavia"]
[Date "1992.11.05"]
[Round "29"]
[White "Fischer, Robert J."]
[Black "Spassky, Boris V."]
[Result "1/2-1/2"]
[Annotator "Example User"]
1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 {This opening is the Ruy Lopez, a sharp Spanish defense variant leading to complex middlegames.} 4. Ba4 Nf6 5. O-O Be7 6. Re1 b5 7. Bb3 d6 8. c3 O-O 9. h3 Nb8 10. d4 Nbd7 11. c4 $6 {Aggressive space gain, but allows Black counterplay (NAG $6 indicates an inaccuracy).} ( 11. Nbd2 {Safer development, maintaining tension.} Bb7 ) b4 12. cxb5 axb5 13. Nc3 Bb7 14. Bg5 h6 15. Bh4 c5 16. dxe5 Nxe5 17. Nxe5 dxe5 18. Bxe7 Qxe7 19. f3 Rd8 20. Qe2 Bc6 21. Rad1 Qf8 22. a3 bxa3 23. bxa3 Qg8 24. Kh1 Rd7 25. Rxd7 Nxd7 26. Rd1 Nc5 27. Qc2 Rb8 28. Rd6 Be7 29. Rxc6 {Initiating exchanges to simplify.} Nxc6 30. Qxc6 Qf8 31. Qc2 Rd8 32. Rxd8 Qxd8 33. Qd3 Qxd3 34. Nxd3 Bf6 35. a4 Kf8 36. Kf2 Ke7 37. Ke2 Kd6 38. Kd2 Kc6 39. Kc3 Kb6 40. Kb4 Ka6 41. a5 Kb7 42. Kc5 Kc7 43. Kd5 Kd7 44. Ke5 Ke7 45. Kf4 Kf6 46. g3 g5+ 47. Kf4 gxf3 48. Kxf3 Bd4 49. h4 Be5 50. g4 Bf4 51. Kg2 Bg3 52. h5 Bf4 53. Kf2 Bg5 54. Kg2 Bf6 55. Kf2 Bg5 56. Kg2 1/2-1/2
This example breaks down key PGN elements: The seven standard tags provide core metadata, while optional tags like "Annotator" credit contributions. Inline comments in curly braces {} offer explanatory notes without altering the game flow. NAGs, such as $6 after move 11, use numeric codes to denote move quality (e.g., $1 for a good move, $6 for inaccuracy, as defined in the PGN specification). Variations in parentheses ( ) branch from the main line, showing alternatives like 11. Nbd2, which Lichess studies often use for exploring options. Multi-game files simply concatenate such structures, with each game ending in a result (e.g., 1/2-1/2) before the next set of tags begins.[1]
PGN's annotated format integrates seamlessly into databases like PGN Mentor, a utility for viewing, searching, and analyzing games with support for comments and NAGs. Similarly, SCID (Shane's Chess Information Database) imports and exports annotated PGN files, enabling users to query variations and annotations across large collections. Parsing tools, such as the python-chess library, handle these elements programmatically for automated analysis.[15][16]
As of 2025, PGN supports AI-generated annotations from engines like Stockfish, which can append NAGs, comments, and evaluation scores (e.g., centipawn loss) to movetext via integrated tools, enhancing post-game reviews in platforms like Lichess.[17]
Support for Variants
Chess Variant Handling
Portable Game Notation (PGN) supports chess variants through an optional header tag, [Variant "Name"], which identifies the specific ruleset of the game, such as [Variant "Fischer Random"] for Chess960 or [Variant "Crazyhouse"] for the variant involving piece drops.[18] This tag allows software to interpret the game under non-standard rules without altering the core PGN structure.[19]
In the movetext section, PGN adapts Standard Algebraic Notation (SAN) to variant-specific mechanics, including modifications to castling availability and pawn promotion rules. For example, in Chess960, castling notation remains similar to standard chess but depends on the randomized starting position, while in variants like Crazyhouse, drops of captured pieces are denoted using the "@" symbol, as in "N@e4" for a knight drop to e4.[19] These adjustments ensure moves reflect the variant's legal possibilities, though implementations must handle rule deviations programmatically.[18]
Despite these extensions, the foundational PGN specification is designed for FIDE-standard chess, assuming conventional piece movements and board setup, which can limit interoperability for highly divergent variants that require custom parsers or additional conventions.[1] For instance, shogi-inspired promotions and drops in variants like Crazyhouse rely on generalized SAN extensions beyond the original standard.[19]
PGN with the Variant tag is employed in platforms such as Lichess for variant modes, facilitating the storage and sharing of games across multiple rulesets, including atomic chess and horde chess, through extended PGN exports.[20] Starting positions for these variants can be integrated using the FEN tag in conjunction with [SetUp "1"] for precise setup description.[18]
Position Notation Integration
Portable Game Notation (PGN) integrates Forsyth-Edwards Notation (FEN) through dedicated header tags to specify custom starting positions, allowing representation of games that deviate from the standard chess setup. The FEN tag contains a string describing the board state, including piece placement across eight ranks separated by slashes, the active color (white "w" or black "b"), castling availability (e.g., "KQkq" for both sides' kingside and queenside options or "-" for none), the en passant target square (e.g., a file-rank pair or "-" if unavailable), the halfmove clock (number of halfmoves since the last capture or pawn advance, starting at 0), and the fullmove number (starting at 1 for white's first move). For the standard initial chess position, this tag is formatted as [FEN "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"].[1]
This integration is activated by the accompanying SetUp tag, which takes a value of "1" to indicate a non-standard starting position, thereby requiring the presence of a valid FEN tag; a value of "0" (the default) assumes the conventional board setup without needing FEN. When SetUp is "1", the FEN overrides the standard initial arrangement, establishing the board state from which the subsequent movetext is interpreted, with move numbering beginning at the fullmove number specified in the FEN (typically 1, but adjustable for mid-game scenarios). The FEN tag must appear in the PGN header before the movetext and is often paired with the Variant tag (e.g., [Variant "Chess960"]) to denote rule modifications, ensuring parsers correctly handle deviations like altered castling in variants. This setup is essential for non-FIDE starting positions, as omitting a valid FEN with SetUp "1" renders the file non-compliant.[1]
Applications of FEN integration in PGN extend to supporting chess variants such as Chess960 (also known as Fischer Random Chess), where randomized back-rank piece arrangements are defined via FEN to enable standard movetext notation from unconventional starts. It also facilitates mid-game analysis by capturing positions for study or puzzle sets, allowing games to resume from any legal board state without reconstructing the full history. Strict PGN export guidelines mandate validating the FEN string for legality—ensuring no overlapping pieces, correct king placement, and adherence to the six-field format—before inclusion, promoting interoperability across chess software and databases.[1]