Portable Game Notation


Portable Game Notation is a standard plain text format for recording chess games, which can be read by humans and is also supported by most chess software.

History

In 1993, Steven J. Edwards devised PGN, which was first popularized and specified via the Usenet newsgroup rec.games.chess.

Usage

PGN is structured "for easy reading and writing by human users and for easy parsing and generation by computer programs".
The chess moves themselves are given in algebraic chess notation using English initials for the pieces. The filename extension is .pgn.
The PGN specification describes two related but distinct formats: the "import" format; and the "export" format.
The PGN import format describes data that might have been prepared by hand, and features a flexible syntax. Although the format is therefore somewhat lax by design, a program that purports to be able to read PGN data must be able to handle the format variations.
The PGN export format, by contrast, is quite strict, designed to describe data prepared under program control, similar to a pretty printed source program reformatted by a compiler. The export format representations generated by different programs, including on different computers, are expected to be exactly equivalent, byte for byte.
PGN text begins with a set of "tag pairs", followed by the "movetext".

Tag pairs

Tag pairs begin with an initial left bracket, followed by the name of the tag in plain ASCII text. The tag value is enclosed in double-quotes, and the tag is then terminated with a closing right bracket. A quote inside a tag value is represented by the backslash immediately followed by a quote. A backslash inside a tag value is represented by two adjacent backslashes.
The format does not allow for special control codes involving escape characters, or carriage returns, and linefeeds to separate the fields, and superfluous embedded spaces are usually skipped when parsing.

Seven Tag Roster

PGN data for archival storage is required to provide seven tag pairs – together known as the "Seven Tag Roster". In export format, these tag pairs must appear before any other tag pairs and in this order:

Optional tag pairs

The standard allows for other optional tag pairs. The more common ones include:

Movetext

[image:SCD algebraic notation.svg|right|Chessboard notation|frame]
The movetext describes the actual moves of the game. This includes move number indicators and movetext in Standard Algebraic Notation.
For most moves, the SAN consists of the letter abbreviation for the piece, an x if there is a capture, and the two-character algebraic name of the final square the piece moved to. The letter abbreviations are K, Q, R, B, and N.
The pawn is given an empty abbreviation in SAN movetext, but in other contexts the abbreviation P is used. The algebraic name of any square is as per usual algebraic chess notation; from white's perspective, the leftmost square closest to white is a1, the rightmost square closest to the white is h1, and the rightmost square closest to black side is h8.
In a few cases, a more detailed representation is needed to resolve ambiguity; if so, the piece's file letter, numerical rank, or the exact square is inserted after the moving piece's name. Thus, Nge2 specifies that the knight originally on the g-file moves to e2.
SAN kingside castling is indicated by the sequence O-O; queenside castling is indicated by the sequence O-O-O. Pawn promotions are notated by appending = to the destination square, followed by the piece the pawn is promoted to. For example: g8=Q. If the move is a checking move, + is also appended; if the move is a checkmating move, # is appended instead. For example: Rc6+.
An annotator who wishes to suggest alternative moves to those actually played in the game may insert variations enclosed in parentheses. They may also comment on the game by inserting Numeric Annotation Glyphs into the movetext. Each NAG reflects a subjective impression of the move preceding the NAG or of the resultant position.
If the game result is anything other than *, the result is repeated at the end of the movetext.

Comments

Comments are inserted by either a ;. Comments do not nest.

Handling chess variants

Many chess variants can be recorded using PGN, provided the names of the pieces can be limited to one character, usually a letter and not a number. They are typically noted with a tag named "Variant" giving the name of the rules. The term "Variation" must be avoided, as that refers to the name of an opening variation. Note that traditional chess programs can only handle, at most, a few variants. Forsyth-Edwards Notation is used to record the starting position for variants which have initial positions other than the orthodox chess initial position.

Examples

Here is the PGN format of the 29th game of the 1992 match played in Yugoslavia between Bobby Fischer and Boris Spassky:

Numeric Annotation Glyphs (NAGs)

Numeric Annotation Glyphs or NAGs are used to annotate chess games when using a computer, typically providing an assessment of a chess move or a chess position. NAGs exist to indicate a simple annotation in a language independent manner.
NAGs were first formally documented in 1994 by Steven J. Edwards in his "Portable Game Notation Specification and Implementation Guide".
Within the PGN specification, 256 NAGs are proposed, of which the first 140 values have been defined; the remaining 116 values are reserved for future definition.
A Numeric Annotation Glyph is composed of a dollar sign character immediately followed by one or more digit characters. Each NAG then has a specific meaning and often a standard typographical representation. The meanings first defined stemmed from the use of specific typographic symbols when annotators were commenting upon chess games; most especially in Chess Informant publications. The objective was to devise an alternative representation of these symbols which could be incorporated in the simple computer file format proposed as the PGN standard. This mechanism allowed often sophisticated typography to be expressed using the simple ASCII character set.
Since its inception there has been no attempt to further formalise or standardise the meaning of the undefined 116 NAGs, although some PGN editors, such as ChessPad, have variously used these higher glyphs by assigning non-standard custom definitions.
NAG rangeClassification
$0provided for the convenience of software designers as a placeholder value;
should not appear in PGN files and has no typographic representation
$1-$9Move assessments
$10-$135Positional Assessments
$136-$139Time Pressure Commentaries
$140+not defined