Portable Game Notation
Encyclopedia
Portable Game Notation is a computer
-processible format for recording chess
games (both the moves and related data
); many chess programs recognize this extremely popular format due to its being stored in plain text
.
newsgroup rec.games.chess.
by human
users and for easy parsing
and generation
by computer program
s." The chess moves themselves are given in algebraic chess notation
. The usual filename extension
is ".pgn".
There are two formats in the PGN specification, the "import" format and the "export" format. The import format describes data that may have been prepared by hand, and is intentionally lax; a program that can read PGN data should be able to handle the somewhat lax import format. The export format is rather strict and describes data prepared under program control, similar to a pretty printed
source program reformatted by a compiler
. The export format representations generated by different programs on the same computer should be exactly equivalent, byte for byte.
PGN code begins with a set of "tag pairs" (a tag name and its value), followed by the "movetext" (chess moves with optional commentary).
). The tag value is enclosed in double-quotes, and the tag is then terminated with a closing right bracket "]". There are no special control codes involving escape characters, or carriage returns and linefeeds to separate the fields, and superfluous embedded spaces (or SPC characters) are usually skipped when parsing.
PGN data for archival storage is required to provide seven bracketed fields, referred to as "tags" and together known as the STR (Seven Tag Roster). In export format, the STR tag pairs must appear before any other tag pairs that may appear, and in this order:
The standard allows for supplementation in the form of other, optional, tag pairs. The more common tag pairs include:
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" (king
), "Q" (queen
), "R" (rook
), "B" (bishop
), and "N" (knight
). 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 a8.
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 (in that order of preference). 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" (note that these are capital letter "O"s, not numeral
"0"s). Pawn promotions are notated by append
ing an "=" to the destination square, followed by the piece the pawn is promoted to. For example: "e8=Q". If the move is a checking move, the plus sign "+" is also appended; if the move is a checkmating move, the number sign
"#" is appended instead. For example: "e8=Q#".
An annotator who wishes to suggest alternative moves to those actually played in the game may insert variations enclosed in parentheses. He may also comment on the game by inserting Numeric Annotation Glyphs
(NAGs) 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.
[Event "F/S Return Match"]
[Site "Belgrade, Serbia Yugoslavia|JUG"]
[Date "1992.11.04"]
[Round "29"]
[White "Fischer, Robert J."]
[Black "Spassky, Boris V."]
[Result "1/2-1/2"]
1. e4 e5 2. Nf3 Nc6 3. Bb5 {This opening is called the Ruy Lopez.} 3... a6
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 c6 12. cxb5 axb5 13. Nc3 Bb7 14. Bg5 b4 15. Nb1 h6 16. Bh4 c5 17. dxe5
Nxe4 18. Bxe7 Qxe7 19. exd6 Qf6 20. Nbd2 Nxd6 21. Nc4 Nxc4 22. Bxc4 Nb6
23. Ne5 Rae8 24. Bxf7+ Rxf7 25. Nxf7 Rxe1+ 26. Qxe1 Kxf7 27. Qe3 Qg5 28. Qxg5
hxg5 29. b3 Ke6 30. a3 Kd6 31. axb4 cxb4 32. Ra5 Nd5 33. f3 Bc8 34. Kf2 Bf5
35. Ra7 g6 36. Ra6+ Kc5 37. Ke1 Nf4 38. g3 Nxh3 39. Kd2 Kb5 40. Rd6 Kc5 41. Ra6
Nf2 42. g4 Bd3 43. Re6 1/2-1/2
s 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
(FEN) is used to record the starting position for variants (such as Chess960
) which have initial positions other than the orthodox chess initial position.
Plycount is a chess term for the total number of moves in a game, counting each player's move as one. It is an optional part of the standard PGN description of a chess game.
Computer
A computer is a programmable machine designed to sequentially and automatically carry out a sequence of arithmetic or logical operations. The particular sequence of operations can be changed readily, allowing the computer to solve more than one kind of problem...
-processible format for recording chess
Chess
Chess is a two-player board game played on a chessboard, a square-checkered board with 64 squares arranged in an eight-by-eight grid. It is one of the world's most popular games, played by millions of people worldwide at home, in clubs, online, by correspondence, and in tournaments.Each player...
games (both the moves and related data
Data
The term data refers to qualitative or quantitative attributes of a variable or set of variables. Data are typically the results of measurements and can be the basis of graphs, images, or observations of a set of variables. Data are often viewed as the lowest level of abstraction from which...
); many chess programs recognize this extremely popular format due to its being stored in plain text
Plain text
In computing, plain text is the contents of an ordinary sequential file readable as textual material without much processing, usually opposed to formatted text....
.
History
PGN was devised around 1993, by Steven J. Edwards, and was first popularized via the UsenetUsenet
Usenet is a worldwide distributed Internet discussion system. It developed from the general purpose UUCP architecture of the same name.Duke University graduate students Tom Truscott and Jim Ellis conceived the idea in 1979 and it was established in 1980...
newsgroup rec.games.chess.
Usage
PGN is structured "for easy reading and writingWriting
Writing is the representation of language in a textual medium through the use of a set of signs or symbols . It is distinguished from illustration, such as cave drawing and painting, and non-symbolic preservation of language via non-textual media, such as magnetic tape audio.Writing most likely...
by human
Human
Humans are the only living species in the Homo genus...
users and for easy parsing
Parsing
In computer science and linguistics, parsing, or, more formally, syntactic analysis, is the process of analyzing a text, made of a sequence of tokens , to determine its grammatical structure with respect to a given formal grammar...
and generation
Generation
Generation , also known as procreation in biological sciences, is the act of producing offspring....
by computer program
Computer program
A computer program is a sequence of instructions written to perform a specified task with a computer. A computer requires programs to function, typically executing the program's instructions in a central processor. The program has an executable form that the computer can use directly to execute...
s." The chess moves themselves are given in algebraic chess notation
Algebraic chess notation
Algebraic notation is a method for recording and describing the moves in a game of chess. It is now standard among all chess organizations and most books, magazines, and newspapers...
. The usual filename extension
Filename extension
A filename extension is a suffix to the name of a computer file applied to indicate the encoding of its contents or usage....
is ".pgn".
There are two formats in the PGN specification, the "import" format and the "export" format. The import format describes data that may have been prepared by hand, and is intentionally lax; a program that can read PGN data should be able to handle the somewhat lax import format. The export format is rather strict and describes data prepared under program control, similar to a pretty printed
Prettyprint
Prettyprint is the application of any of various stylistic formatting conventions to text, source code, markup, and other similar kinds of content. These formatting conventions usually consist of changes in positioning, spacing, color, contrast, size and similar modifications intended to make the...
source program reformatted by a compiler
Compiler
A compiler is a computer program that transforms source code written in a programming language into another computer language...
. The export format representations generated by different programs on the same computer should be exactly equivalent, byte for byte.
PGN code begins with a set of "tag pairs" (a tag name and its value), followed by the "movetext" (chess moves with optional commentary).
Tag pairs
Tag pairs begin with an initial left bracket "[", followed by the name of the tag in plain text (ASCIIASCII
The American Standard Code for Information Interchange is a character-encoding scheme based on the ordering of the English alphabet. ASCII codes represent text in computers, communications equipment, and other devices that use text...
). The tag value is enclosed in double-quotes, and the tag is then terminated with a closing right bracket "]". There are no special control codes involving escape characters, or carriage returns and linefeeds to separate the fields, and superfluous embedded spaces (or SPC characters) are usually skipped when parsing.
PGN data for archival storage is required to provide seven bracketed fields, referred to as "tags" and together known as the STR (Seven Tag Roster). In export format, the STR tag pairs must appear before any other tag pairs that may appear, and in this order:
- Event: the name of the tournament or match event.
- Site: the location of the event. This is in "City, Region COUNTRY" format, where COUNTRY is the three-letter International Olympic CommitteeInternational Olympic CommitteeThe International Olympic Committee is an international corporation based in Lausanne, Switzerland, created by Pierre de Coubertin on 23 June 1894 with Demetrios Vikelas as its first president...
code for the country. An example is "New York CityNew York CityNew York is the most populous city in the United States and the center of the New York Metropolitan Area, one of the most populous metropolitan areas in the world. New York exerts a significant impact upon global commerce, finance, media, art, fashion, research, technology, education, and...
, NY USAUnited StatesThe United States of America is a federal constitutional republic comprising fifty states and a federal district...
". - Date: the starting date of the game, in YYYY.MM.DD form. "??" are used for unknown values.
- Round: the playing round ordinal of the game within the event.
- White: the player of the white pieces, in "last name, first name" format.
- Black: the player of the black pieces, same format as White.
- Result: the result of the game. This can only have four possible values: "1-0" (White won), "0-1" (Black won), "1/2-1/2" (Draw), or "*" (other, e.g., the game is ongoing).
The standard allows for supplementation in the form of other, optional, tag pairs. The more common tag pairs include:
- Annotator: The person providing notes to the game.
- PlyCount: String value denoting total number of half-moves played.
- TimeControl: "40/7200:3600" (moves per seconds: sudden death seconds)
- Time: Time the game started, in "HH:MM:SS" format, in local clock time.
- Termination: Gives more details about the termination of the game. It may be "abandoned", "adjudication" (result determined by third-party adjudication), "death", "emergency", "normal", "rules infraction", "time forfeit", or "unterminated".
- Mode: "OTB" (over-the-board) "ICS" (Internet Chess Server)
- FEN: The initial position of the chess board, in Forsyth-Edwards NotationForsyth-Edwards NotationForsyth–Edwards Notation is a standard notation for describing a particular board position of a chess game. The purpose of FEN is to provide all the necessary information to restart a game from a particular position....
. This is used to record partial games (starting at some initial position). It is also necessary for chess variants such as Fischer random chess, where the initial position is not always the same as traditional chess. If a FEN tag is used, a separate tag pair "SetUp" must also appear and have its value set to "1".
Movetext
The movetext describes the actual moves of the game. This includes move number indicators (numbers followed by either one or three periods; one if the next move is White's move, three if the next move is Black's move) and movetext Standard Algebraic Notation (SAN).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" (king
King (chess)
In chess, the king is the most important piece. The object of the game is to trap the opponent's king so that its escape is not possible . If a player's king is threatened with capture, it is said to be in check, and the player must remove the threat of capture on the next move. If this cannot be...
), "Q" (queen
Queen (chess)
The queen is the most powerful piece in the game of chess, able to move any number of squares vertically, horizontally, or diagonally. Each player starts the game with one queen, placed in the middle of the first rank next to the king. With the chessboard oriented correctly, the white queen starts...
), "R" (rook
Rook (chess)
A rook is a piece in the strategy board game of chess. Formerly the piece was called the castle, tower, marquess, rector, and comes...
), "B" (bishop
Bishop (chess)
A bishop is a piece in the board game of chess. Each player begins the game with two bishops. One starts between the king's knight and the king, the other between the queen's knight and the queen...
), and "N" (knight
Knight (chess)
The knight is a piece in the game of chess, representing a knight . It is normally represented by a horse's head and neck. Each player starts with two knights, which begin on the row closest to the player, one square from the corner...
). The pawn
Pawn (chess)
The pawn is the most numerous and weakest piece in the game of chess, historically representing infantry, or more particularly armed peasants or pikemen. Each player begins the game with eight pawns, one on each square of the rank immediately in front of the other pieces...
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
Algebraic chess notation
Algebraic notation is a method for recording and describing the moves in a game of chess. It is now standard among all chess organizations and most books, magazines, and newspapers...
; 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 a8.
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 (in that order of preference). Thus, "Nge2" specifies that the knight originally on the g-file moves to e2.
SAN kingside castling
Castling
Castling is a special move in the game of chess involving the king and either of the original rooks of the same color. It is the only move in chess in which a player moves two pieces at the same time. Castling consists of moving the king two squares towards a rook on the player's first rank, then...
is indicated by the sequence "O-O"; queenside castling is indicated by the sequence "O-O-O" (note that these are capital letter "O"s, not numeral
Numerical digit
A digit is a symbol used in combinations to represent numbers in positional numeral systems. The name "digit" comes from the fact that the 10 digits of the hands correspond to the 10 symbols of the common base 10 number system, i.e...
"0"s). Pawn promotions are notated by append
Append
In general, to append is to join or add on to the end of something. For example, an appendix is a section appended of a document....
ing an "=" to the destination square, followed by the piece the pawn is promoted to. For example: "e8=Q". If the move is a checking move, the plus sign "+" is also appended; if the move is a checkmating move, the number sign
Number sign
Number sign is a name for the symbol #, which is used for a variety of purposes including, in some countries, the designation of a number...
"#" is appended instead. For example: "e8=Q#".
An annotator who wishes to suggest alternative moves to those actually played in the game may insert variations enclosed in parentheses. He may also comment on the game by inserting Numeric Annotation Glyphs
Numeric Annotation Glyphs
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) 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 ";" (a comment that continues to the end of the line) or a "{" (which continues until a matching "}"). Comments do not nest.Example
Here is a sample game in PGN format:[Event "F/S Return Match"]
[Site "Belgrade, Serbia Yugoslavia|JUG"]
[Date "1992.11.04"]
[Round "29"]
[White "Fischer, Robert J."]
[Black "Spassky, Boris V."]
[Result "1/2-1/2"]
1. e4 e5 2. Nf3 Nc6 3. Bb5 {This opening is called the Ruy Lopez.} 3... a6
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 c6 12. cxb5 axb5 13. Nc3 Bb7 14. Bg5 b4 15. Nb1 h6 16. Bh4 c5 17. dxe5
Nxe4 18. Bxe7 Qxe7 19. exd6 Qf6 20. Nbd2 Nxd6 21. Nc4 Nxc4 22. Bxc4 Nb6
23. Ne5 Rae8 24. Bxf7+ Rxf7 25. Nxf7 Rxe1+ 26. Qxe1 Kxf7 27. Qe3 Qg5 28. Qxg5
hxg5 29. b3 Ke6 30. a3 Kd6 31. axb4 cxb4 32. Ra5 Nd5 33. f3 Bc8 34. Kf2 Bf5
35. Ra7 g6 36. Ra6+ Kc5 37. Ke1 Nf4 38. g3 Nxh3 39. Kd2 Kb5 40. Rd6 Kc5 41. Ra6
Nf2 42. g4 Bd3 43. Re6 1/2-1/2
Handling chess variants
Many chess variantChess variant
A chess variant is a game related to, derived from or inspired by chess. The difference from chess might include one or more of the following:...
s 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
Forsyth-Edwards Notation
Forsyth–Edwards Notation is a standard notation for describing a particular board position of a chess game. The purpose of FEN is to provide all the necessary information to restart a game from a particular position....
(FEN) is used to record the starting position for variants (such as Chess960
Chess960
Chess960 is a chess variant invented and advocated by former World Chess Champion Bobby Fischer, originally announced on June 19, 1996 in Buenos Aires, Argentina. It employs the same board and pieces as standard chess, but the starting position of the pieces is randomized along the players' home...
) which have initial positions other than the orthodox chess initial position.
Plycount is a chess term for the total number of moves in a game, counting each player's move as one. It is an optional part of the standard PGN description of a chess game.