Version 3.0 User's Manual
UtilitiesCheck File". The instructions to show the analysis record of a PGN file containing analysis would be
"Right ClickShow Analysis Rec". Commands implemented by pressing certain keys on the keyboard are indicated with single quotes. For example, the instructions for going forward five moves with a keyboard command
would be to press 'Page Down'. The instructions for showing the current material and space count for the game with a keyboard command would be to press '+'. "Click" means left-click unless specified as "Right Click".
3. Getting Started/Program BasicsPGN Mentor 3.0 will only run with Windows 95 or higher on a Pentium processor.
3.2 Starting the ProgramThe install process automatically creates four subdirectories for storing your PGN files: Players, Openings, Events, and Collections. A few PGN files have been placed in each of these directories. You can store additional PGN files in these directories, and additional directories can be created as desired. A PGN file can contain up to several thousand chess games.
You can find links to masses of PGN files at this site, available for free download. ChessBase, Nic Base, Chess Assistant, and Bookup can all easily be converted to PGN format with the appropriate conversion utilities, available for free at many places on the internet. With these archives you have quick and free access to hundreds of thousands of Grandmaster games.
4. Game Viewing/NavigatingUpon starting PGN Mentor, you will be prompted to open a PGN file. You must open a PGN file to use PGN Mentor. After selecting a file, you will be placed in "Game" mode at the first game of the file. At this point you are ready to begin using the program.
4.1 Making MovesThe central area of PGN Mentor is "Game" mode, where the games of a PGN file are viewed and played through. There are many different features and options involved with "Game" mode. When in other modes, you can always return to this mode by clicking "Game" at the top of the screen.
A game is viewed by clicking certain areas on the board. The instructions here may seem complex at first but are very easy to learn.
To go forward one move, click anywhere on ranks two through four or press 'Down Arrow'.
To go backward one move, click anywhere on ranks five through seven or press 'Up Arrow'.
To go forward five moves, click on the first rank (excluding squares a1 and h1) or press 'Page Down'.
To go backward five moves, click on the eighth rank (excluding squares a8 and h8) or press 'Page Up'.
Go directly to the last position of the game by clicking on square h1 or by pressing 'End'.
Go back to the start position by clicking on square a8 or by pressing 'Home'.
You can also make moves using the "Game" buttons when the "Display Game Buttons" option has been selected in the "Options" menu.
Click anywhere above the board to go back to the immediately previous move (position) in the currently viewed game.
Clicking anywhere below the board takes you directly to the last move (position) that was displayed when you last left the current game. This is a useful function when studying several games at once and frequently switching between games, and also when frequently switching to different modes, such as "Text" mode or "Search Variation" mode. The saved positions are erased when a PGN file is exited.
You can instantly go to any position in the game by clicking on the corresponding move in the game text on the right.
After a position search, go to the first occurrence of the position by clicking on square a1 or by pressing 'Insert'.
After a variation search, go to the end of the variation by clicking on square h8 or by pressing 'Delete'.
If no variation or positional search criteria has been specified, clicking on these squares (a1 and h8) or pressing these keys ('Insert' and 'Delete') takes you to the middle of the game.
After a search has been performed, game navigation using "Next", "Prev" or "Select" only includes those games that have just been found in the search. Normal navigation to the next or previous game can be resumed by selecting "Search
To view the position from the opposite side of the board, click "Flip".
4.2 Auto PlayRight click on the board or press '+' to display the amount of material remaining and the amount of space controlled by each player.
Material and Space Count
4.3 The Game Popup MenuThe "Auto Play" function allows the user to automatically play through a game when in "Game" mode. Start "Auto Play" by pressing the space bar or by right-clicking off the board to get the "Game" popup menu and then clicking on "Auto Play". Stop "Auto Play" by pressing the space bar again or by right-clicking off the board to get the "Game" popup menu and then clicking on "Stop Auto Play". Press the space bar twice to interrupt the delay between moves and immediately go to the next move.
Use the "Options" menu to change the "Auto Play Delay" time in seconds between moves.
Right click off the board to display the "Game" popup menu. This menu contains the basic features explained above, and under special circumstances will contain a few more options (e.g. "Show Analysis Rec", when the PGN file contains analysis).
Game Popup Menu
4.4 Game TextWhen in "Game" mode, the text of the game is shown to the right of the display board. In some cases a game will be quite long and not all of the text will fit on the screen. Just click on the empty space on the side (not on the moves) in the lower half of the text to see the remaining moves. Click the top half of the text (once again, to the side, not on the moves) to page back.
Sometimes it is convenient to view the actual text, as it was written into the file, while playing through a game in "Game" mode, for example when the text contains analysis and/or comments. To view the actual PGN text of a game, right click anywhere off the board to display the "Game" popup menu and the click "Show Actual Text". To erase the actual text and return to the normal text, once again right click anywhere off the board and then click "Show Normal Text".
At anytime you can switch to "Text" mode by clicking "Text". Only the text moves will be displayed. To page down, left click in the lower half of the screen or press 'Page Down'; to page up, left click in the upper half of the screen or press 'Page Up'. Right click to display the "Text" popup menu (similar to the "Game" popup menu). Click "Next" for the next game and "Prev" for the previous game.
If you want to view the actual text, as it was written into the file, then select "Right Click
Text Mode
4.5 Board SizeWhen in "Text" mode, the "Text" popup menu has the option to display the actual text in a list box similar to the "File
When in "Text" mode and the normal text is displayed, the "Text" popup menu has the option to find the opening for the current game. If the ECO code is present in the game header, the ECO code description of that opening will automatically be displayed. However, you can override the ECO code in the header or find the opening when the header does not contain the ECO code by using the "Right Click
When in "Game" mode, the fuction accessed by selecting "Right Click4.6 Piece StyleYou can choose to display a larger size game board when the screen resolution is at least 1024 x 768. To change the size of the board, simply check the "Big Board" option in "File
You can choose from two piece styles- "Modern" and "Sharp". To change the piece style, simply select your choice in "File
Modern
Sharp
4.7 Notation4.8 Slide SpeedYou can choose from two notation formats- "English Algebraic" and "Figurine Algebraic", the increasingly popular standard for international chess literature. The notation format can also be selected in "File
Moves cannot be copied or printed in figurine notation.English Algebraic:
1.e4 e5 2.Nf3 Nc6 3.Bb5 Nf6 4.O-O Bc5 5.c3 O-O 6.d4 Bb6 7.Bg5 h6 8.Bh4 d6 9.Bxc6 bxc6 10.dxe5 dxe5 11.Qa4 Qd6 12.Rd1 Qe6 13.Nbd2 Nd7 14.b4 a5 15.Qb3 Re8 16.Qxe6 Rxe6 17.Nc4 f6 18.a3 Ba6 19.Nfd2 axb4 20.axb4 Ree8 21.Nxb6 Nxb6 22.f3 1/2-1/2
Figurine Algebraic:
1.e4 e5 2.f3 c6 3.b5
f6 4.O-O
a4
d1
4.9 Grid Lines/CoordinatesYou can vary the speed in which the pieces slide. This is also in the "Options" menu. Choose a value from 1 to 200; 200 is the fastest speed. To turn off the piece slide, enter a value of 0.
4.10 Highlight Last MoveUnder the program's default settings, PGN Mentor 3.0 displays algebraic coordinates around the board (on the top and to the left) and does not display grid lines on the board. These features can easily be changed by adjusting the settings under "File
Grid Lines and No Coordinates
Here is how the "Game" mode display appears when the options are set to display grid lines and no coordinates. Many users prefer one or both of these settings.4.11 Display OpeningYou can choose to highlight the squares involved in the last move currently displayed on the game board. The square from where the last moved piece was moved and the square the piece was moved to will have their borders highlighted. You can change the highlight color by clicking on "File
4.12 Game ButtonsYou can choose to display the ECO (Encyclopedia of Chess Openings) description for the current game position. PGN Mentor contains a database with over 5000 ECO entries. The opening will be displayed in "Game", "Analyze", "Tree", "Variation Edit", and "Add Game Edit" modes. An '*' after the opening indicates the current line is "out of ECO book".
The opening that is displayed is not based on the ECO code in the game header, even if the header contains the ECO code. Instead, PGN Mentor performs its own search taking into account any transpositions. If you want to see the ECO code that is in the game header, click on "Text" to display the game text.
When the normal text is displayed in "Text" mode, the description along with the ECO code is shown. The actual game text will just show you the ECO code.
The "Display Opening" feature can be turned on in the "File4.13 ColorsYou can choose to display the "Game" buttons to make moves in "Game" mode by selecting the "Display Game Buttons" option in the "Options" menu.
If the "Game" buttons are displayed, click on the '>' button to go forward one move, click on the '<' button to go back one move, click on the '>>' button to go forward five moves, click on the the '<<' button to go back five moves, click on the '>>>' button to go to the end of the game, and finally click on the '<<<' button to go to the start of the game.
4.14 Game NavigatingThe colors of the light and dark squares on the board as well as the color of the background can quickly and easily be changed by selecting "File
Selecting Colors5. Analysis/Study ModeTo view the next game in a file, click "Next" or press 'Right Arrow'. To view the previous game, click "Prev" or press 'Left Arrow'. You can also use the scroll bar at the right. Clicking in the middle of the scroll bar will move through 5% of the file at a time. Also, you can click and drag the bar.
Click "Return" at the top of the screen to return to the previously viewed game. This function can also be accessed by selecting "Right Click
Clicking "Select" at the top of the screen allows you to select a game from a list. A window is displayed listing all the games currently available for viewing. If a search has been performed, only search results will be included in the list. To restore all the games to the "Select" list, click on the "Reset" button or click on "Search
You can click "Current" to highlight the game you are currently viewing. The "Select Game" function can also be accessed by selecting "Right Click
Selecting a Game
Not shown is the "Alt Info" button used to display alternate game information. When the "Alt Info" button is first clicked, the select game information will include the players' ELO rating (if available), round number (if available), and short ECO code description. Normally, the description is based on the ECO code displayed in the game header. However, if there is no ECO code in the header, the program tries to determine the basic opening based on the first few moves of the game.
Click on the "Alt Info" button again to return to the normal select game information.
5.1 Indication of Analysis
5.2 Viewing and Playing AnalysisIf the current game contains comments or analysis, the PGN file name is displayed in blue. If the current move contains comments or analysis, the move (shown below the board) is displayed in blue.
5.3 Analyzing Your Own LinesIf the current move contains comments or analysis, you can right click off the board to bring up the "Game" popup menu, and select "Show Analysis Rec" to display the corresponding comments and analysis. You can play through the analysis by selecting "Play Analysis". You can also select a particular line of analysis to play through by choosing the "Select Line" function in the "Game" popup menu. This function breaks apart all the individual lines so that you can play a certain line from beginning to end, without continuously retracing back to other lines.
5.4 Searching for the Analysis LineYou can enter "Analyze" mode (while in "Game" mode, on top of the screen) to play through or search the alternate lines in the PGN text or analysis record, or you can try out some of your own lines. The moves are generated just as they are in "Edit Variation" mode (discussed later). Click on "Game" to exit "Analyze" mode and continue viewing the game from the original analysis position.
You can also play out lines from a position you have set up in "Edit Position" mode. After setting up a position, simply click "Analyze" to enter "Analyze" mode and explore your constructed position.
5.5 Study ModeA variation search can be performed while in "Analyze" mode using the analysis position as a temporary variation by selecting "Search
As an alternative, you can left click to display the "Analyze" popup menu and then copy the current game position to "Variation Edit", "Position Edit", or "Add Game Edit".
"Copy to Variation" copies the current position to "Variation Edit" and then puts you in "Variation Edit" mode with the end of the variation displayed.
"Copy to Position" copies the current position to "Position Edit" and then puts you in "Position Edit" mode with the position displayed.
"Copy to Add Game" copies the current position to "Add Game Edit" and then puts you in "Add Game Edit" mode with the start position displayed. Click on the "End" button to go to the end position.
5.6 Chess ProblemsThere is a special function in PGN Mentor which you can use to challenge yourself and try to anticipate the Grandmaster's next move. This function, "Study Mode", can be accessed by clicking "Analyze" at the top of the screen while in "Game" mode, and then (while in "Analyze" mode) selecting "Right Click
Study Mode
To try a move, simply make the move on the board. If the move is correct, the move will be played on the board. If the move is not correct, "Incorrect move!" will be displayed. Click "Ok" and the move will be retracted, and at this point you can try again. To show the next move of the game without attempting to enter the correct move, click "Show Move".
If you want a hint when trying to guess the next move, click directly below the board and PGN Mentor will tell you which type of piece is moved next but not the particular piece or the location of the piece.
You can always click "Game" at the top of the screen to exit this mode and return to "Game" mode.
Note: If you are using this function as a serious test of your skills, you should probably select "Hide Game Text" in the "Options" menu to avoid seeing too much of the game text while in "Game" mode. This function will hide all of the moves of the game (in "Game" mode) and only show each move after it is played.
6. Tree ModePGN Mentor allows the user to analyze special "chess problem" games in a PGN file which include a starting position in the PGN game header. The starting position is defined by a "FEN" tag in the game header. (Consult the PGN standard for details on the "FEN" format.)
The user can select "Hide Game Text" in the "Options" menu to hide the moves when the problem is displayed in "Game" mode. When in "Game" mode, the user can click on "Analyze" to begin analyzing the problem. While in "Analyze" mode, the user can also right click off the board to get the popup menu and then click on "Study Mode" to facilitate studying the problem.
A problem game can be created by first generating a position by clicking on "Search
Complete the process by editing the header and saving the game using the save functions under "File
Note that you cannot re-enter edit mode via "File
Another powerful function of PGN Mentor 3.0 is "Tree" mode. This function allows you to navigate through all the various lines in a given PGN file in a mapped out "tree" fashion. Basically, the program goes through the currently viewed PGN file and sorts all of the lines of play. In each given position, PGN Mentor displays all of the moves played in that position and allows the user to advance to the resulting position and the resulting move branches. When a line with a single-game occurrence is reached you are taken directly to that point in the game so you can study the rest of the game. This very useful feature of PGN Mentor will save you lots of time and energy by eliminating strenuous searching routines or, worse yet, hours of leafing through large opening manuscripts and tiny footnotes. The key is that it allows you to maximize the efficiency of your time studying chess openings.
6.1 Using Tree Mode6.2 The ECO TreeTo begin using "Tree" mode, select "Tree
Tree Mode
On the default the setting, the listed moves are sorted by frequency of occurrence. The number of games in which the move was played as well as the percentage of occurrence are also displayed. These settings can be modified by using the "Modify Settings" option (explained below).
To display the "Tree" menu, right click outside the move box. This menu gives you the options of searching the current PGN file (or the entire directory) for the line of play traversed by the user, treating the line as a temporary variation. When the search results are displayed in "Game" mode, you will automatically be placed at the end of the variation (you can always return to this point by clicking on square h8). Also given are the options to move back one level (to the previous move branch) or go back to the beginning of the tree (which can also be done by selecting "Tree
When outside "Tree" mode, you can always come back to exactly where you last were in the tree by selecting "Tree
Normally, the tree results for each position will include all transpositions. If this is not desired, however, you can turn off this option in "Modify Settings".
The "Tree
Anytime the tree was started from a game position, you can temporarily display the move text of the line leading to the position by clicking on "Display Position" in the tree popup menu. The moves will be displayed at the top of the screen above the game board.
It is important to know that the "Tree" function will use the fast file generated with "Make Fast File" if it exists. This will greatly speed up new tree navigation, especially for large PGN files.
6.3 Tree FilesPGN Mentor also allows you to navigate through all the various lines in the PGN Mentor ECO codes database. This is a powerful tool for studying the basic ECO chess openings. Turn the "Display Opening" option on in the "File
Select "Tree
Select "Tree
6.4 Modify SettingsWhen navigating through a file in "Tree" mode, PGN Mentor adds any newly explored branches to a special "Tree" file. This is done to speed up the process of navigation when going through branches that have already been traversed. The program then has no need to perform its "Tree" search routine when not necessary.
Separate tree files are created for normal navigation and "exact search" navigation, depending on which option is currently set.
If a tree file exists for a given PGN file, the program will start at the beginning of that tree file. Otherwise, a new tree file will be created.
Select "Tree
6.5 Tree Merge FilesThe "Modify Settings" option can be accessed by selecting "Tree
Modify (Tree) Settings
You can specify the number of consecutive single nodes that are detected before terminating the current branch and taking you to the currently viewed position in "Game" mode. The default setting is 10 nodes (equal to 10 ply or 5 full moves).
When the option "Automatically display game when end of branch detected" is selected, PGN Mentor will take you to the current position in "Game" mode when the end of a branch is reached (in other words, you are taken to what is determined as the only game in the file that has followed the line of play to the traversed point). If this option is not selected, a confirmation message is simply displayed informing the user that the end of the branch has been reached.
Normally, the tree will include move choices that occur in games that have reached the given position via a different order of moves (i.e. transpositions are taken into account). This option can be turned off by selecting the option "Navigate tree searching for exact variations".
You can specify any of three ways for sorting the moves displayed in the box. The first option is "No sorting- display moves in order of appearance" which when selected will cause the moves in the box to be displayed in order of their appearance in the PGN file. The second option is "Sort moves by frequency of occurrence". This option will result in the moves in the box being displayed in order of their frequency of occurrence in the file with the percentage of occurrence or score displayed directly to the right. A complimentary option is provided, giving the choice to show the percentage of occurrence of each move played. The third option is to simply sort the moves in the box by type of move- the move order is pawn, knight, bishop, rook, queen, king, and castle.
7. Search CommandsThis set of functions allows you to merge several PGN files into a large "tree merge" file that can be used for tree mode navigation. The tree merge files are "fast" files which allow for efficient tree navigation.
An example for the tree merge function might be to combine several PGN opening files to generate an openings database. You could then use tree mode for the tree merge file containing the combined openings.
The "New Merge File" function generates a new tree merge file from the current PGN file. The "Append to Merge File" function appends the current PGN file to the selected tree merge file.
Click on "Open File" to open a tree merge file. Click on "Start Tree" to start the tree for the current tree merge file. Click on "Return to Tree" to return to the last tree position you were in for the current tree merge file.
Click on "Go to Position" to skip to the current game position in the tree for the current tree merge file. Left click anywhere on the screen to abort the position tree.
Click on "Duplicate Games" to check the tree merge file for duplicate games and to optionally delete any duplicate games that are found.
PGN Mentor has a large selection of search commands and search options. You can search for games based on any of the following criteria:Other search commands allow you to display all the possible moves made next from a given position, to copy the games found in a search to another PGN file, or to display the scores, openings, or cross table for a PGN file.
- Opening Variation
- Player (specifying a particular color if desired)
- Position
- Pawn Structure
- Piece Development
- Material Amount
- Endgame Situation
- Event, Location, Date, and Round
- ELO Rating of Each Player
- Win/Loss/Draw Statistics
- Number of Moves
- Specific Move
- Any combination of the above!
7.1 Variation SearchSearching for a particular opening variation is quite easy. To enter a variation just select "Search
Edit Variation7.2 Position SearchAn opening variation can also be selected by ECO (Encyclopedia of Chess Openings) code by selecting "Search
Select Opening
After you have finished entering the variation, select "Search
After a variation (or any other) search, normal navigation to the next or previous game can be resumed by clicking on "Search
Games that reach the same position of the variation entered by transposition are also included in the results of the search. If you want to turn off this feature, select "SearchExact Variation".
For a lengthy variation, you may find it useful to use the "Search
The series of games that results from a variation search (or any other possible search) can be copied and appended as a group to a different file by selecting "Search
It is also possible to have PGN Mentor identify a particular opening line. To do this, enter "Edit Variation" mode, enter a variation, and select "Search
To have PGN Mentor identify the opening line of the game you are currently viewing, enter "Text" mode (by clicking "Text" at the top of the screen), make sure you are in "Normal Text" mode, and select "Right Click
It is important to know that the "Variation Search" function will use the fast file generated with "Make Fast File" if it exists. This will greatly speed up variation searches, especially for large PGN files.The position search option is also easy to use. To enter "Position Edit" mode, select "Search
Edit Position7.3 Header SearchSelect a piece by clicking on it. An "*" will appear over the selected piece. Click on an empty square to position the selected piece. Click on a positioned piece to remove it.
The position search allows you to specify the piece count with or without specifying the position of the pieces. To specify a particular piece count for a piece, first specify the relational operator (=, <=, or >=) by clicking on the two buttons under the board. Then click on the button under the appropriate piece (excluding the king) to set the piece count.
If an "*" is specified for a black piece count, PGN Mentor will search for positions with that specific piece count for either color. So, you can specify that you want to find positions in which one side has, for example, five pawns and two rooks, without specifying a color.
To remove the piece count, just click on the button under the piece.
To clear the board, click "Clear".
After you have finished entering the position criteria, you can conduct the search for games that match the position in the same way as above. Select "Search
You can use the "Save Position" option to preserve the position criteria for future searches. Load a saved position by choosing "Load Position".
After setting up a position, you can click "Analyze" to enter "Analyze" mode and explore different lines that can occur from your constructed position.
It is important to know that the "Position Search" function will use the fast file generated with "Make Fast File" if it exists. This will greatly speed up position searches, especially for large PGN files.In the "Header" search option you can search for things like particular players, events, dates, locations, results, etc. Click on "Search
Edit Header7.4 Combination SearchA special search feature is supported for finding games played by a player as either white or black. If the "White" field contains an entry and the "Black" field contains an "*", then PGN Mentor will find games played by that player with either color. If the "*" in the Black field is followed immediately by a player name (no space between the "*' and the player name), then PGN Mentor will find all the games the two players played against each other regardless of color.
You can specify a search criterion based on the number of moves in a game by setting an entry in the "Number of Moves" field. The relational operators =, >, >=, <=, and < can be specified as well as a numerical value. The relational operators also apply to the date, white ELO and black ELO fields.
When using the "Specific Move" field, specify moves such as 12.Be3 or 12...Qe2.
Conduct the search and view the games in the same manner as described above.
You can also save and load your header criteria with "Save Header" and "Load Header".
It is important to know that the "Header Search" function will use the fast file generated with "Make Fast File" if it exists. This will greatly speed up header searches, especially for large PGN files.You can search for any combination of the above features with the "Search Combination" option.
Search Combination7.5 Directory SearchThis search option is an extremely powerful tool. Now you can find out, for example, how Gary Kasparov played the black side of the Grünfeld defense, examine what Mikhail Botvinnik's win/loss statistics were in the French Defense, or study the nature of games of a particular pawn structure.
7.6 Copy GamesYou can broaden your search with the "Directory Search" option. For any of the search options described above, just select "Search Directory" instead "Search File". PGN Mentor will search throughout the entire current directory for games that match the given criteria.
Display the search results for each file by selecting "Display Directory Search". All of the files that contain at least one match will be presented. Double click on a file to view the games in that file that matched the search criteria.
You can also save the results of a directory search with the "Save Directory Search" feature. Load a saved directory search result by selecting "Load Directory Search".7.7 Show Next MovesThe current game from the search list can be copied to another PGN file. The "Copy Game To" function copies the current game to a new or existing user specified PGN file. This function is the same as the "File
The "Copy All Games To
The "Copy All Games To
The "Copy All Games" function can also be used to copy all the games from a file or directory search to a new or existing tree merge file.
If you perform a variation search with no variation specified, then the search will "find" all the games in the current PGN file. Then you can use the "Copy All Games" function to copy all the games from one PGN file to another. Note that this also works for position or header searches when no position or header criteria is specified.7.8 Show Next ManeuversThe "Show Next Moves" function displays all the possible moves that were made next from the current position based on all the games in the current PGN file or ECO codes database or a tree merge file. The listed moves are sorted by frequency of occurrence, and the number of games in which the move was played as well as the percentage of occurrence are also displayed.
Left click on a move in the "next moves" list box to advance to the next level. Left click directly below the box to move back one level.
This function is designed to work especially well while in "Analyze" mode as the board position will be automatically updated while moving through the list of "next moves".
Note that this function is only available in "Game", "Analyze" and "Variation Edit" modes.7.9 Display Scores/PlayersThe "Show Maneuvers" function displays all the moves (up to 1000) made after the current position looking ahead for the number of moves specified in the "maneuvers look ahead count". For example, if the look ahead count is set to 10 and the move "c5" occurrs anytime in the next 10 moves, then the "c5" move will be included in the maneuvers list.
Set the maneuvers look ahead count by clicking on "Search
This function is also only available in "Game", "Analyze" and "Variation Edit" modes.7.10 Display Cross TableThe "Display Scores" function displays the scores for all the players in the current PGN file. This is especially useful for event files.
The players and scores can be sorted alphabetically by player, by score/player from highest score to lowest score, or by rating. Click on the "Re-Sort" button to switch the sort order.
The "Display Players" function displays the scores always sorted by player. This is a convenient way to show all the players in a file.
Normally, PGN Mentor attempts to resolve minor differences that may occur in player names for the same player. You can turn this option off by clicking on the "Exact" button to search for an exact player match. In this case, all distinct names will be displayed. When "Exact Player Match" mode is currently on, click on "Exact" again to turn the mode off and display the player names normally.
Only the games that are displayed in the "Select Game" list (after a possible search) are included in the "Player Scores" list. Click on the "Reset" button or "Search
Note that this function may take several seconds to complete for very large files with many different players. Left click anywhere in the main window to abort generation of the score list.
When in "Display Scores" or "Display Players", you can click on the "Select" button to select a player name in preparation for a header search.
First click on a player in the scores/players list and then click on the "Select" button. A window will be displayed showing the "White" and "Black" player fields from the "Search
Click on the radio buttons to set the "White" and "Black" fields as desired. Only the player's last name is brought in unless you are currently in "Exact Player Match" mode. You can also edit the name fields if required.
Then click on the "OK" button to return to the scores/players list to select another player, or click on the "Search" button to display the "Edit Header" screen. Both the "OK" and "Search" buttons copy the "White" and "Black" fields to the corresponding fields in the "Edit Header" screen.
Finally, you can search the file or directory from the "Edit Header" screen after setting any other search fields if desired.7.11 Display OpeningsThe "Display Cross Table" function attempts to display the cross table of the current PGN file, if the file has information as to which round the games were played in. This is especially useful for event files.
Each entry in the cross table is of the form "oocs.s" where "oo" is the number of opponent, "c" is the color of the player, and "s.s" is the score of the player after the round.
The cross table is sorted based on the sorting used the last time the "Display Scores" function was used. The "Exact Player Match" option from the "Display Scores" function is also used.
Note that you can left click anywhere in the main window to abort generation of the cross table.8. Other Important FeaturesThe "Display Openings" function displays the openings played in the current PGN file and the number of times they were played. The program searches for some basic openings such as the Ruy Lopez, Sicilian defense, French defense, etc.
The openings and count can be sorted alphabetically by openings, or sorted by count/opening from highest count to lowest count. Click on the "Re-Sort" button to switch the sort order. Click on "Select" to select an opening for a variation search.
Only the games that are displayed in the "Select Game" list (after a possible search) are included in the "Openings" list. Click on the "Reset" button or "Search
8.1 Copy Moves8.2 Printing GamesWhen viewing a game, the "Copy Moves" function (in the "File" menu) copies the moves of the currently viewed game to the clipboard. When in "Edit Variation" or "Analysis" mode, this function copies the moves of the current variation or line of analysis.
8.3 Creating and Managing a New Game/FilePGN Mentor allows you to print games. To print a game, first click "Print" and then select "Normal Text" or "Actual Text" (the difference between these two options is explained in "Game Text" above). This adds the game to the print list. To print out all the games in the print list, select "File
8.4 UtilitiesTo create a new game in the current file, select "File
Next, click "Edit Header" and fill in the necessary information. Be sure to include the result in standard form (1-0, 1/2-1/2, or 0-1).
Then click "Append Game" to add the game to the end of the current file, "Insert Game" to insert the game immediately before the currently viewed game, or "Overwrite Game" to replace the last game. To make the game the first game of a new file, select "New File".
You can also save an incomplete game as a temporary file by choosing "Save Game". Load a saved incomplete game by choosing "Load Game".
At any time you can copy and append the currently viewed game to any file by selecting "File
Another function designed to facilitate moving or copying a game from one PGN file into another PGN file or to move games within the current file is the "Move Game" function under the "File" menu. The first step in using this option is to copy the current game into a temporary game buffer by selecting "Move Game8.4.1 Modify GameThe "Utilities" option allows you to make changes to a PGN file or check the integrity of a PGN file.
Select "File
The changes to a game made in "Modify Text" mode cannot be saved if the game has records (lines) consisting of more than 255 characters. If there are lines of more than 255 characters, either insert the necessary carriage returns or have PGN Mentor do this for you by selecting "File
When finished using "Modify Text" mode, select "File
Modify Text8.4.2 Delete GameSelect "File
While in "Modify Moves" mode, click on "Edit Header" to modify the game header or click on "Flip" to switch sides of the board.
When finished using "Modify Moves" mode, select "File8.4.3 Copy Game To...Select "Delete Game" to remove the current game from the current PGN file.
8.4.4 Reload FileSelect "Copy Game To" to copy the current game to a new or existing PGN file.
8.4.5 Check FileA PGN file may need to be reloaded when the PGN file is modified outside the program, for example by overwriting with a new version or after editing in a text editor.
This is not required normally because PGN Mentor will automatically perform a reload when it detects a change in the size of the PGN file.8.4.6 Duplicate GamesSelect "Check File" to perform a complete file examination. This feature checks for errors in the text of the games, including illegal moves and possible file corruption.
8.4.7 Adjust FileThe "Duplicate Games
The program looks ahead for the user specified number of games when searching for a duplicate. Typically, duplicate games will be found "near" each other. The default look ahead count is 100 games.
Also, duplicate games often do not have the exact same number of moves. You can specify the maximum difference in number of moves (default 2) and still designate a game as a duplicate.
You can also specify that the entire file should be searched when looking for a duplicate game and in that case, the look ahead count is not used.
The "Duplicate Games
It is important to know that the "Duplicate Games" function will use the fast file generated with "Make Fast File" if it exists. This will greatly speed up the search for duplicate games, especially for large PGN files.8.4.8 Fast FileSelect "Adjust File" to adjust the size and format of the records (lines) in the currently opened PGN file. This function can used for the purpose of shortening the lines of all the games in the file (similar to the "Adjust" function in "Modify Game" mode", explained above). It can also be used to change the move text format to standard algebraic format from non-standard or long-algebraic format. For example, the game text 1. e2-e4 e7-e5 2. Ng1-f3 Nb8-c6 3. Bf1-b5 a7-a6 is not in standard form and can be changed to standard form: 1. e4 e5 2. Nf3 Nc6 3. Bb5 a6. Many conversion programs, especially ChessBase to PGN, generate PGN files with the game text in this long-algebraic format.
Note that this function strips all comments, analysis, and variations from the current PGN file. You will be prompted with a warning if any such comments or analysis exist in the PGN file.8.4.9 Split FileSelect "Make Fast File" to generate a special "fast" file that, if it exists, is used to speed up tree mode, variation, position and header searches, and the duplicate games function (they all use the same fast file). The fast file is not necessary, but is recommended for very large PGN files.
If a PGN file is modifed, you should rerun "Make Fast File". PGN Mentor will check for a change in the number of games in a PGN file versus its fast file, but it won't check for changes in the individual moves.
Run the "Check Fast File" function to check if a fast file exists for the current PGN file, and also to check if the number of games in the fast file is the same as in the PGN file.
Run the "Delete Fast File" function to delete the fast file for the current PGN file.8.5 The Options MenuThis function allows you to split up large PGN files that may be too big for PGN Mentor to handle.
The names for the new split files will be the original filename concatenated with either the numbers 1,2,3, etc or the letters a,b,c, etc.
If the original filename ends in a numeral, the split filenames will be concatenated with a letter. Otherwise, the split filenames will be concatenated with a number.8.6 Generating Chess DocumentsThe "Options" menu (under "File") allows you to make basic modifications to the current program settings. This is where you can change the piece animation speed, the piece style, the notation format, the font size of the print, etc.
Options Menu
With the "Actual Text" option, you can specify that "Text" mode will default to display the actual text in which the file was written, rather than the concise format that PGN Mentor normally displays.
Select the edit style, "Click and Click" or "Drag and Drop", to use when editing a position or variation or adding a new game. To make a move with the "Click and Click" option, first click on the square you want to move from and then click on the square you want to move to. With the "Drag and Drop" method, click on the piece you want to move, hold it, and drag the mouse to the square you want to move the piece to.
If the "Auto Page Game Text" option is set, then when in "Game" mode the game text to the right of the board will automatically page up or down according to the current move number.
If the "Auto Display Analysis Comments" option is set, then when in "Play Analysis" mode, the comments associated with the current move will automatically be displayed. Also, when in "Game" mode, the comments and analysis associated with the current move will automatically be displayed on the right (instead of the normal game text); when there is no analysis for a move, the normal game text will return. If "Actual Text" is set to be displayed on the right, the analysis for moves is not displayed.
When the "Auto Display Game" option is set, the first game will automatically be displayed when a new file is opened (this option should almost always be on).
The "Hide Game Text" option will, while in "Game" mode, hide all of the moves of the game and only show each move on the right after it is played (this function should be used in conjunction with "Study Mode", explained above).
There is also an option that allows you to turn off the logo display at the program startup.
The "Slide Speed", "Piece Style", "Notation Style", "Highlight Last Move", "Big Board", "Display Opening" and "Display Game Buttons" options, as well as the "Display Grid Lines", "Coordinates", and "Auto Play Delay" settings are explained in detail under section 4, Game Viewing/Navigating.
You can adjust the font size of printed games by changing the "Max Print Lines" value.8.7 The Help MenuPGN Mentor allows easy construction of chess documents with games, comments, analysis, and diagrams in HTML- the language used to produce pages on the World Wide Web.
To produce a chess annotation file, select "File
You can also generate the code for an HTML diagram without creating any annotation file. To generate a diagram, simply attain the desired position on the board in any mode (position search, variation search, game viewing, etc.) and click "Html" (also in "File
The HTML diagrams that PGN Mentor 3.0 generates follow the popular standard of most modern chess books and look like this:
Position after 9. h3
If you just want to create a normal document with a program like Microsoft Publisher or Microsoft Word, you can easily save and insert Windows Bitmap images of your diagrams. To product a bitmap image file of the currently viewed position, simply select "File9. The PGN StandardFor a quick reference during program use, there is a help menu that contains a brief explanation of each of the features of PGN Mentor.
This document is the official set of guidelines that is recognized all over the world as the standard for all aspects of PGN import and export, coding, and formatting. This is in the public domain, can be found at many places throughout the internet, and is generally followed by PGN users in most places. This document is of relatively little importance to most users of PGN Mentor 3.0, and only very advanced users should be interested in reviewing it.
TABLE OF CONTENTS
0: Preface
1: Introduction
2: Chess data representation
2.1: Data interchange incompatibility
2.2: Specification goals
2.3: A sample PGN game
3: Formats: import and export
3.1: Import format allows for manually prepared data
3.2: Export format used for program generated output
3.2.1: Byte equivalence
3.2.2: Archival storage and the newline character
3.2.3: Speed of processing
3.2.4: Reduced export format
4: Lexicographical issues
4.1: Character codes
4.2: Tab characters
4.3: Line lengths
5: Commentary
6: Escape mechanism
7: Tokens
8: Parsing games
8.1: Tag pair section
8.1.1: Seven Tag Roster
8.1.1.1: The Event tag
8.1.1.2: The Site tag
8.1.1.3: The Date tag
8.1.1.4: The Round tag
8.1.1.5: The White tag
8.1.1.6: The Black tag
8.1.1.7: The Result tag
8.2: Movetext section
8.2.1: Movetext line justification
8.2.2: Movetext move number indications
8.2.2.1: Import format move number indications
8.2.2.2: Export format move number indications
8.2.3: Movetext SAN (Standard Algebraic Notation)
8.2.3.1: Square identification
8.2.3.2: Piece identification
8.2.3.3: Basic SAN move construction
8.2.3.4: Disambiguation
8.2.3.5: Check and checkmate indication characters
8.2.3.6: SAN move length
8.2.3.7: Import and export SAN
8.2.3.8: SAN move suffix annotations
8.2.4: Movetext NAG (Numeric Annotation Glyph)
8.2.5: Movetext RAV (Recursive Annotation Variation)
8.2.6: Game Termination Markers
9: Supplemental tag names
9.1: Player related information
9.1.1: Tags: WhiteTitle, BlackTitle
9.1.2: Tags: WhiteElo, BlackElo
9.1.3: Tags: WhiteUSCF, BlackUSCF
9.1.4: Tags: WhiteNA, BlackNA
9.1.5: Tags: WhiteType, BlackType
9.2: Event related information
9.2.1: Tag: EventDate
9.2.2: Tag: EventSponsor
9.2.3: Tag: Section
9.2.4: Tag: Stage
9.2.5: Tag: Board
9.3: Opening information (locale specific)
9.3.1: Tag: Opening
9.3.2: Tag: Variation
9.3.3: Tag: SubVariation
9.4: Opening information (third party vendors)
9.4.1: Tag: ECO
9.4.2: Tag: NIC
9.5: Time and date related information
9.5.1: Tag: Time
9.5.2: Tag: UTCTime
9.5.3: Tag: UTCDate
9.6: Time control
9.6.1: Tag: TimeControl
9.7: Alternative starting positions
9.7.1: Tag: SetUp
9.7.2: Tag: FEN
9.8: Game conclusion
9.8.1: Tag: Termination
9.9: Miscellaneous
9.9.1: Tag: Annotator
9.9.2: Tag: Mode
9.9.3: Tag: PlyCount
10: Numeric Annotation Glyphs
11: File names and directories
11.1: File name suffix for PGN data
11.2: File name formation for PGN data for a specific player
11.3: File name formation for PGN data for a specific event
11.4: File name formation for PGN data for chronologically ordered games
11.5: Suggested directory tree organization
12: PGN collating sequence
13: PGN software
13.1: The SAN Kit
13.2: pgnRead
13.3: mail2pgn/GIICS
13.4: XBoard
13.5: cupgn
13.6: Zarkov
13.7: Chess Assistant
13.8: BOOKUP
13.9: HIARCS
13.10: Deja Vu
13.11: MV2PGN
13.12: The Hansen utilities (cb2pgn, nic2pgn, pgn2cb, pgn2nic)
13.13: Slappy the Database
13.14: CBASCII
13.15: ZZZZZZ
13.16: icsconv
13.17: CHESSOP (CHESSOPN/CHESSOPG)
13.18: CAT2PGN
13.19: pgn2opg
14: PGN data archives
15: International Olympic Committee country codes
16: Additional chess data standards
16.1: FEN
16.1.1: History
16.1.2: Uses for a position notation
16.1.3: Data fields
16.1.3.1: Piece placement data
16.1.3.2: Active color
16.1.3.3: Castling availability
16.1.3.4: En passant target square
16.1.3.5: Halfmove clock
16.1.3.6: Fullmove number
16.1.4: Examples
16.2: EPD
16.2.1: History
16.2.2: Uses for an extended position notation
16.2.3: Data fields
16.2.3.1: Piece placement data
16.2.3.2: Active color
16.2.3.3: Castling availability
16.2.3.4: En passant target square
16.2.4: Operations
16.2.4.1: General format
16.2.4.2: Opcode mnemonics
16.2.5: Opcode list
16.2.5.1: Opcode "acn": analysis count: nodes
16.2.5.2: Opcode "acs": analysis count: seconds
16.2.5.3: Opcode "am": avoid move(s)
16.2.5.4: Opcode "bm": best move(s)
16.2.5.5: Opcode "c0": comment (primary, also "c1" though "c9")
16.2.5.6: Opcode "ce": centipawn evaluation
16.2.5.7: Opcode "dm": direct mate fullmove count
16.2.5.8: Opcode "draw_accept": accept a draw offer
16.2.5.9: Opcode "draw_claim": claim a draw
16.2.5.10: Opcode "draw_offer": offer a draw
16.2.5.11: Opcode "draw_reject": reject a draw offer
16.2.5.12: Opcode "eco": _Encyclopedia of Chess Openings_ opening code
16.2.5.13: Opcode "fmvn": fullmove number
16.2.5.14: Opcode "hmvc": halfmove clock
16.2.5.15: Opcode "id": position identification
16.2.5.16: Opcode "nic": _New In Chess_ opening code
16.2.5.17: Opcode "noop": no operation
16.2.5.18: Opcode "pm": predicted move
16.2.5.19: Opcode "pv": predicted variation
16.2.5.20: Opcode "rc": repetition count
16.2.5.21: Opcode "resign": game resignation
16.2.5.22: Opcode "sm": supplied move
16.2.5.23: Opcode "tcgs": telecommunication: game selector
16.2.5.24: Opcode "tcri": telecommunication: receiver identification
16.2.5.25: Opcode "tcsi": telecommunication: sender identification
16.2.5.26: Opcode "v0": variation name (primary, also "v1" though "v9")
17: Alternative chesspiece identifier letters
18: Formal syntax
19: Canonical chess position hash coding
20: Binary representation (PGC)
20.1: Bytes, words, and doublewords
20.2: Move ordinals
20.3: String data
20.4: Marker codes
20.4.1: Marker 0x01: reduced export format single game
20.4.2: Marker 0x02: tag pair
20.4.3: Marker 0x03: short move sequence
20.4.4: Marker 0x04: long move sequence
20.4.5: Marker 0x05: general game data begin
20.4.6: Marker 0x06: general game data end
20.4.7: Marker 0x07: simple-nag
20.4.8: Marker 0x08: rav-begin
20.4.9: Marker 0x09: rav-end
20.4.10: Marker 0x0a: escape-string
21: E-mail correspondence usage
======================================================================
Standard: Portable Game Notation Specification and Implementation Guide
Revised: 1994.03.12
Authors: Interested readers of the Internet newsgroup rec.games.chess
Coordinator: Steven J. Edwards (send comments to sje@world.std.com)
0: Preface
>From the Tower of Babel story:
"If now, while they are one people, all speaking the same language, they have started to do this, nothing will later stop them from doing whatever they propose to do."
Genesis XI, v.6, _New American Bible_
1: Introduction
PGN is "Portable Game Notation", a standard designed for the representation of chess game data using ASCII text files. PGN is structured for easy reading and writing by human users and for easy parsing and generation by computer programs. The intent of the definition and propagation of PGN is to facilitate the sharing of public domain chess game data among chessplayers (both organic and otherwise), publishers, and computer chess researchers throughout the world.
PGN is not intended to be a general purpose standard that is suitable for every possible use; no such standard could fill all conceivable requirements. Instead, PGN is proposed as a universal portable representation for data interchange. The idea is to allow the construction of a family of chess applications that can quickly and easily process chess game data using PGN for import and export among themselves.
2: Chess data representation
Computer usage among chessplayers has become quite common in recent years and a variety of different programs, both commercial and public domain, are used to generate, access, and propagate chess game data. Some of these programs are rather impressive; most are now well behaved in that they correctly follow the Laws of Chess and handle users' data with reasonable care. Unfortunately, many programs have had serious problems with several aspects of the external representation of chess game data. Sometimes these problems become more visible when a user attempts to move significant quantities of data from one program to another; if there has been no real effort to ensure portability of data, then the chances for a successful transfer are small at best.
2.1: Data interchange incompatibility
The reasons for format incompatibility are easy to understand. In fact, most of them are correlated with the same problems that have already been seen with commercial software offerings for other domains such as word processing, spreadsheets, fonts, and graphics. Sometimes a manufacturer deliberately designs a data format using encryption or some other secret, proprietary technique to "lock in" a customer. Sometimes a designer may produce a format that can be deciphered without too much difficulty, but at the same time publicly discourage third party software by claiming trade secret protection. Another software producer may develop a non-proprietary system, but it may work well only within the scope of a single program or application because it is not easily expandable. Finally, some other software may work very well for many purposes, but it uses symbols and language not easily understood by people or computers available to those outside the country of its development.
2.2: Specification goals
A specification for a portable game notation must observe the lessons of history and be able to handle probable needs of the future. The design criteria for PGN were selected to meet these needs. These criteria include:
1) The details of the system must be publicly available and free of unnecessary complexity. Ideally, if the documentation is not available for some reason, typical chess software developers and users should be able to understand most of the data without the need for third party assistance.
2) The details of the system must be non-proprietary so that users and software developers are unrestricted by concerns about infringing on intellectual property rights. The idea is to let chess programmers compete in a free market where customers may choose software based on their real needs and not based on artificial requirements created by a secret data format.
3) The system must work for a variety of programs. The format should be such that it can be used by chess database programs, chess publishing programs, chess server programs, and chessplaying programs without being unnecessarily specific to any particular application class.
4) The system must be easily expandable and scalable. The expansion ability must include handling data items that may not exist currently but could be expected to emerge in the future. (Examples: new opening classifications and new country names.) The system should be scalable in that it must not have any arbitrary restrictions concerning the quantity of stored data. Also, planned modes of expansion should either preserve earlier databases or at least allow for their automatic conversion.
5) The system must be international. Chess software users are found in many countries and the system should be free of difficulties caused by conventions local to a given region.
6) Finally, the system should handle the same kinds and amounts of data that are already handled by existing chess software and by print media.
2.3: A sample PGN game
Although its description may seem rather lengthy, PGN is actually fairly simple. A sample PGN game follows; it has most of the important features described in later sections of this document.
[Event "F/S Return Match"]
[Site "Belgrade, Serbia 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 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
3: Formats: import and export
There are two formats in the PGN specification. These are the "import" format and the "export" format. These are the two different ways of formatting the same PGN data according to its source. The details of the two formats are described throughout the following sections of this document.
Other than formats, there is the additional topic of PGN presentation. While both PGN import and export formats are designed to be readable by humans, there is no recommendation that either of these be an ultimate mode of chess data presentation. Rather, software developers are urged to consider all of the various techniques at their disposal to enhance the display of chess data at the presentation level (i.e., highest level) of their programs. This means that the use of different fonts, character sizes, color, and other tools of computer aided interaction and publishing should be explored to provide a high quality presentation appropriate to the function of the particular program.
3.1: Import format allows for manually prepared data
The import format is rather flexible and is used to describe data that may have been prepared by hand, much like a source file for a high level programming language. A program that can read PGN data should be able to handle the somewhat lax import format.
3.2: Export format used for program generated output
The export format is rather strict and is used to describe data that is usually prepared under program control, something like a pretty printed source program reformatted by a compiler.
3.2.1: Byte equivalence
For a given PGN data file, export format representations generated by different PGN programs on the same computing system should be exactly equivalent, byte for byte.
3.2.2: Archival storage and the newline character
Export format should also be used for archival storage. Here, "archival" storage is defined as storage that may be accessed by a variety of computing systems. The only extra requirement for archival storage is that the newline character have a specific representation that is independent of its value for a particular computing system's text file usage. The archival representation of a newline is the ASCII control character LF (line feed, decimal value 10, hexadecimal value 0x0a).
Sadly, there are some accidents of history that survive to this day that have baroque representations for a newline: multicharacter sequences, end-of-line record markers, start-of-line byte counts, fixed length records, and so forth. It is well beyond the scope of the PGN project to reconcile all of these to the unified world of ANSI C and the those enjoying the bliss of a single '\n' convention. Some systems may just not be able to handle an archival PGN text file with native text editors. In these cases, an indulgence of sorts is granted to use the local newline convention in non-archival PGN files for those text editors.
3.2.3: Speed of processing
Several parts of the export format deal with exact descriptions of line and field justification that are absent from the import format details. The main reason for these restrictions on the export format are to allow the construction of simple data translation programs that can easily scan PGN data without having to have a full chess engine or other complex parsing routines. The idea is to encourage chess software authors to always allow for at least a limited PGN reading capability. Even when a full chess engine parsing capability is available, it is likely to be at least two orders of magnitude slower than a simple text scanner.
3.2.4: Reduced export format
A PGN game represented using export format is said to be in "reduced export format" if all of the following hold: 1) it has no commentary, 2) it has only the standard seven tag roster identification information ("STR", see below), 3) it has no recursive annotation variations ("RAV", see below), and 4) it has no numeric annotation glyphs ("NAG", see below). Reduced export format is used for bulk storage of unannotated games. It represents a minimum level of standard conformance for a PGN exporting application.
4: Lexicographical issues
PGN data is composed of characters; non-overlapping contiguous sequences of characters form lexical tokens.
4.1: Character codes
PGN data is represented using a subset of the eight bit ISO 8859/1 (Latin 1) character set. ("ISO" is an acronym for the International Standards Organization.) This set is also known as ECMA-94 and is similar to other ISO Latin character sets. ISO 8859/1 includes the standard seven bit ASCII character set for the 32 control character code values from zero to 31. The 95 printing character code values from 32 to 126 are also equivalent to seven bit ASCII usage. (Code value 127, the ASCII DEL control character, is a graphic character in ISO 8859/1; it is not used for PGN data representation.)
The 32 ISO 8859/1 code values from 128 to 159 are non-printing control characters. They are not used for PGN data representation. The 32 code values from 160 to 191 are mostly non-alphabetic printing characters and their use for PGN data is discouraged as their graphic representation varies considerably among other ISO Latin sets. Finally, the 64 code values from 192 to 255 are mostly alphabetic printing characters with various diacritical marks; their use is encouraged for those languages that require such characters. The graphic representations of this last set of 64 characters is fairly constant for the ISO Latin family.
Printing character codes outside of the seven bit ASCII range may only appear in string data and in commentary. They are not permitted for use in symbol construction.
Because some PGN users' environments may not support presentation of non-ASCII characters, PGN game authors should refrain from using such characters in critical commentary or string values in game data that may be referenced in such environments. PGN software authors should have their programs handle such environments by displaying a question mark ("?") for non-ASCII character codes. This is an important point because there are many computing systems that can display eight bit character data, but the display graphics may differ among machines and operating systems from different manufacturers.
Only four of the ASCII control characters are permitted in PGN import format; these are the horizontal and vertical tabs along with the linefeed and carriage return codes.
The external representation of the newline character may differ among platforms; this is an acceptable variation as long as the details of the implementation are hidden from software implementors and users. When a choice is practical, the Unix "newline is linefeed" convention is preferred.
4.2: Tab characters
Tab characters, both horizontal and vertical, are not permitted in the export format. This is because the treatment of tab characters is highly dependent upon the particular software in use on the host computing system. Also, tab characters may not appear inside of string data.
4.3: Line lengths
PGN data are organized as simple text lines without any special bytes or markers for secondary record structure imposed by specific operating systems. Import format PGN text lines are limited to having a maximum of 255 characters per line including the newline character. Lines with 80 or more printing characters are strongly discouraged because of the difficulties experienced by common text editors with long lines.
In some cases, very long tag values will require 80 or more columns, but these are relatively rare. An example of this is the "FEN" tag pair; it may have a long tag value, but this particular tag pair is only used to represent a game that doesn't start from the usual initial position.
5: Commentary
Comment text may appear in PGN data. There are two kinds of comments. The first kind is the "rest of line" comment; this comment type starts with a semicolon character and continues to the end of the line. The second kind starts with a left brace character and continues to the next right brace character. Comments cannot appear inside any token.
Brace comments do not nest; a left brace character appearing in a brace comment loses its special meaning and is ignored. A semicolon appearing inside of a brace comment loses its special meaning and is ignored. Braces appearing inside of a semicolon comments lose their special meaning and are ignored.
*** Export format representation of comments needs definition work.
6: Escape mechanism
There is a special escape mechanism for PGN data. This mechanism is triggered by a percent sign character ("%") appearing in the first column of a line; the data on the rest of the line is ignored by publicly available PGN scanning software. This escape convention is intended for the private use of software developers and researchers to embed non-PGN commands and data in PGN streams.
A percent sign appearing in any other place other than the first position in a line does not trigger the escape mechanism.
7: Tokens
PGN character data is organized as tokens. A token is a contiguous sequence of characters that represents a basic semantic unit. Tokens may be separated from adjacent tokens by white space characters. (White space characters include space, newline, and tab characters.) Some tokens are self delimiting and do not require white space characters.
A string token is a sequence of zero or more printing characters delimited by a pair of quote characters (ASCII decimal value 34, hexadecimal value 0x22). An empty string is represented by two adjacent quotes. (Note: an apostrophe is not a quote.) A quote inside a string is represented by the backslash immediately followed by a quote. A backslash inside a string is represented by two adjacent backslashes. Strings are commonly used as tag pair values (see below). Non-printing characters like newline and tab are not permitted inside of strings. A string token is terminated by its closing quote. Currently, a string is limited to a maximum of 255 characters of data.
An integer token is a sequence of one or more decimal digit characters. It is a special case of the more general "symbol" token class described below. Integer tokens are used to help represent move number indications (see below). An integer token is terminated just prior to the first non-symbol character following the integer digit sequence.
A period character (".") is a token by itself. It is used for move number indications (see below). It is self terminating.
An asterisk character ("*") is a token by itself. It is used as one of the possible game termination markers (see below); it indicates an incomplete game or a game with an unknown or otherwise unavailable result. It is self terminating.
The left and right bracket characters ("[" and "]") are tokens. They are used to delimit tag pairs (see below). Both are self terminating.
The left and right parenthesis characters ("(" and ")") are tokens. They are used to delimit Recursive Annotation Variations (see below). Both are self terminating.
The left and right angle bracket characters ("<" and ">") are tokens. They are reserved for future expansion. Both are self terminating.
A Numeric Annotation Glyph ("NAG", see below) is a token; it is composed of a dollar sign character ("$") immediately followed by one or more digit characters. It is terminated just prior to the first non-digit character following the digit sequence.
A symbol token starts with a letter or digit character and is immediately followed by a sequence of zero or more symbol continuation characters. These continuation characters are letter characters ("A-Za-z"), digit characters ("0-9"), the underscore ("_"), the plus sign ("+"), the octothorpe sign ("#"), the equal sign ("="), the colon (":"), and the hyphen ("-"). Symbols are used for a variety of purposes. All characters in a symbol are significant. A symbol token is terminated just prior to the first non-symbol character following the symbol character sequence. Currently, a symbol is limited to a maximum of 255 characters in length.
8: Parsing games
A PGN database file is a sequential collection of zero or more PGN games. An empty file is a valid, although somewhat uninformative, PGN database.
A PGN game is composed of two sections. The first is the tag pair section and the second is the movetext section. The tag pair section provides information that identifies the game by defining the values associated with a set of standard parameters. The movetext section gives the usually enumerated and possibly annotated moves of the game along with the concluding game termination marker. The chess moves themselves are represented using SAN (Standard Algebraic Notation), also described later in this document.
8.1: Tag pair section
The tag pair section is composed of a series of zero or more tag pairs.
A tag pair is composed of four consecutive tokens: a left bracket token, a symbol token, a string token, and a right bracket token. The symbol token is the tag name and the string token is the tag value associated with the tag name. (There is a standard set of tag names and semantics described below.) The same tag name should not appear more than once in a tag pair section.
A further restriction on tag names is that they are composed exclusively of letters, digits, and the underscore character. This is done to facilitate mapping of tag names into key and attribute names for use with general purpose database programs.
For PGN import format, there may be zero or more white space characters between any adjacent pair of tokens in a tag pair.
For PGN export format, there are no white space characters between the left bracket and the tag name, there are no white space characters between the tag value and the right bracket, and there is a single space character between the tag name and the tag value.
Tag names, like all symbols, are case sensitive. All tag names used for archival storage begin with an upper case letter.
PGN import format may have multiple tag pairs on the same line and may even have a tag pair spanning more than a single line. Export format requires each tag pair to appear left justified on a line by itself; a single empty line follows the last tag pair.
Some tag values may be composed of a sequence of items. For example, a consultation game may have more than one player for a given side. When this occurs, the single character ":" (colon) appears between adjacent items. Because of this use as an internal separator in strings, the colon should not otherwise appear in a string.
The tag pair format is designed for expansion; initially only strings are allowed as tag pair values. Tag value formats associated with the STR (Seven Tag Roster, see below) will not change; they will always be string values. However, there are long term plans to allow general list structures as tag values for non-STR tag pairs. Use of these expanded tag values will likely be restricted to special research programs. In all events, the top level structure of a tag pair remains the same: left bracket, tag name, tag value, and right bracket.
8.1.1: Seven Tag Roster
There is a set of tags defined for mandatory use for archival storage of PGN data. This is the STR (Seven Tag Roster). The interpretation of these tags is fixed as is the order in which they appear. Although the definition and use of additional tag names and semantics is permitted and encouraged when needed, the STR is the common ground that all programs should follow for public data interchange.
For import format, the order of tag pairs is not important. For export format, the STR tag pairs appear before any other tag pairs. (The STR tag pairs must also appear in order; this order is described below). Also for export format, any additional tag pairs appear in ASCII order by tag name.
The seven tag names of the STR are (in order):
1) Event (the name of the tournament or match event)
2) Site (the location of the event)
3) Date (the starting date of the game)
4) Round (the playing round ordinal of the game)
5) White (the player of the white pieces)
6) Black (the player of the black pieces)
7) Result (the result of the game)
A set of supplemental tag names is given later in this document.
For PGN export format, a single blank line appears after the last of the tag pairs to conclude the tag pair section. This helps simple scanning programs to quickly determine the end of the tag pair section and the beginning of the movetext section.
8.1.1.1: The Event tag
The Event tag value should be reasonably descriptive. Abbreviations are to be avoided unless absolutely necessary. A consistent event naming should be used to help facilitate database scanning. If the name of the event is unknown, a single question mark should appear as the tag value.
Examples:
[Event "FIDE World Championship"]
[Event "Moscow City Championship"]
[Event "ACM North American Computer Championship"]
[Event "Casual Game"]
8.1.1.2: The Site tag
The Site tag value should include city and region names along with a standard name for the country. The use of the IOC (International Olympic Committee) three letter names is suggested for those countries where such codes are available. If the site of the event is unknown, a single question mark should appear as the tag value. A comma may be used to separate a city from a region. No comma is needed to separate a city or region from the IOC country code. A later section of this document gives a list of three letter nation codes along with a few additions for "locations" not covered by the IOC.
Examples:
[Site "New York City, NY USA"]
[Site "St. Petersburg RUS"]
[Site "Riga LAT"]
8.1.1.3: The Date tag
The Date tag value gives the starting date for the game. (Note: this is not necessarily the same as the starting date for the event.) The date is given with respect to the local time of the site given in the Event tag. The Date tag value field always uses a standard ten character format: "YYYY.MM.DD". The first four characters are digits that give the year, the next character is a period, the next two characters are digits that give the month, the next character is a period, and the final two characters are digits that give the day of the month. If the any of the digit fields are not known, then question marks are used in place of the digits.
Examples:
[Date "1992.08.31"]
[Date "1993.??.??"]
[Date "2001.01.01"]
8.1.1.4: The Round tag
The Round tag value gives the playing round for the game. In a match competition, this value is the number of the game played. If the use of a round number is inappropriate, then the field should be a single hyphen character. If the round is unknown, a single question mark should appear as the tag value.
Some organizers employ unusual round designations and have multipart playing rounds and sometimes even have conditional rounds. In these cases, a multipart round identifier can be made from a sequence of integer round numbers separated by periods. The leftmost integer represents the most significant round and succeeding integers represent round numbers in descending hierarchical order.
Examples:
[Round "1"]
[Round "3.1"]
[Round "4.1.2"]
8.1.1.5: The White tag
The White tag value is the name of the player or players of the white pieces. The names are given as they would appear in a telephone directory. The family or last name appears first. If a first name or first initial is available, it is separated from the family name by a comma and a space. Finally, one or more middle initials may appear. (Wherever a comma appears, the very next character should be a space. Wherever an initial appears, the very next character should be a period.) If the name is unknown, a single question mark should appear as the tag value.
The intent is to allow meaningful ASCII sorting of the tag value that is independent of regional name formation customs. If more than one person is playing the white pieces, the names are listed in alphabetical order and are separated by the colon character between adjacent entries. A player who is also a computer program should have appropriate version information listed after the name of the program.
The format used in the FIDE Rating Lists is appropriate for use for player name tags.
Examples:
[White "Tal, Mikhail N."]
[White "van der Wiel, Johan"]
[White "Acme Pawngrabber v.3.2"]
[White "Fine, R."]
8.1.1.6: The Black tag
The Black tag value is the name of the player or players of the black pieces. The names are given here as they are for the White tag value.
Examples:
[Black "Lasker, Emmanuel"]
[Black "Smyslov, Vasily V."]
[Black "Smith, John Q.:Woodpusher 2000"]
[Black "Morphy"]
8.1.1.7: The Result tag
The Result field value is the result of the game. It is always exactly the same as the game termination marker that concludes the associated movetext. It is always one of four possible values: "1-0" (White wins), "0-1" (Black wins), "1/2-1/2" (drawn game), and "*" (game still in progress, game abandoned, or result otherwise unknown). Note that the digit zero is used in both of the first two cases; not the letter "O".
All possible examples:
[Result "0-1"]
[Result "1-0"]
[Result "1/2-1/2"]
[Result "*"]
8.2: Movetext section
The movetext section is composed of chess moves, move number indications, optional annotations, and a single concluding game termination marker.
Because illegal moves are not real chess moves, they are not permitted in PGN movetext. They may appear in commentary, however. One would hope that illegal moves are relatively rare in games worthy of recording.
8.2.1: Movetext line justification
In PGN import format, tokens in the movetext do not require any specific line justification.
In PGN export format, tokens in the movetext are placed left justified on successive text lines each of which has less than 80 printing characters. As many tokens as possible are placed on a line with the remainder appearing on successive lines. A single space character appears between any two adjacent symbol tokens on the same line in the movetext. As with the tag pair section, a single empty line follows the last line of data to conclude the movetext section.
Neither the first or the last character on an export format PGN line is a space. (This may change in the case of commentary; this area is currently under development.)
8.2.2: Movetext move number indications
A move number indication is composed of one or more adjacent digits (an integer token) followed by zero or more periods. The integer portion of the indication gives the move number of the immediately following white move (if present) and also the immediately following black move (if present).
8.2.2.1: Import format move number indications
PGN import format does not require move number indications. It does not prohibit superfluous move number indications anywhere in the movetext as long as the move numbers are correct.
PGN import format move number indications may have zero or more period characters following the digit sequence that gives the move number; one or more white space characters may appear between the digit sequence and the period(s).
8.2.2.2: Export format move number indications
There are two export format move number indication formats, one for use appearing immediately before a white move element and one for use appearing immediately before a black move element. A white move number indication is formed from the integer giving the fullmove number with a single period character appended. A black move number indication is formed from the integer giving the fullmove number with three period characters appended.
All white move elements have a preceding move number indication. A black move element has a preceding move number indication only in two cases: first, if there is intervening annotation or commentary between the black move and the previous white move; and second, if there is no previous white move in the special case where a game starts from a position where Black is the active player.
There are no other cases where move number indications appear in PGN export format.
8.2.3: Movetext SAN (Standard Algebraic Notation)
SAN (Standard Algebraic Notation) is a representation standard for chess moves using the ASCII Latin alphabet.
Examples of SAN recorded games are found throughout most modern chess publications. SAN as presented in this document uses English language single character abbreviations for chess pieces, although this is easily changed in the source. English is chosen over other languages because it appears to be the most widely recognized.
An alternative to SAN is FAN (Figurine Algebraic Notation). FAN uses miniature piece icons instead of single letter piece abbreviations. The two notations are otherwise identical.
8.2.3.1: Square identification
SAN identifies each of the sixty four squares on the chessboard with a unique two character name. The first character of a square identifier is the file of the square; a file is a column of eight squares designated by a single lower case letter from "a" (leftmost or queenside) up to and including "h" (rightmost or kingside). The second character of a square identifier is the rank of the square; a rank is a row of eight squares designated by a single digit from "1" (bottom side [White's first rank]) up to and including "8" (top side [Black's first rank]). The initial squares of some pieces are: white queen rook at a1, white king at e1, black queen knight pawn at b7, and black king rook at h8.
8.2.3.2: Piece identification
SAN identifies each piece by a single upper case letter. The standard English values: pawn = "P", knight = "N", bishop = "B", rook = "R", queen = "Q", and king = "K".
The letter code for a pawn is not used for SAN moves in PGN export format movetext. However, some PGN import software disambiguation code may allow for the appearance of pawn letter codes. Also, pawn and other piece letter codes are needed for use in some tag pair and annotation constructs.
It is admittedly a bit chauvinistic to select English piece letters over those from other languages. There is a slight justification in that English is a de facto universal second language among most chessplayers and program users. It is probably the best that can be done for now. A later section of this document gives alternative piece letters, but these should be used only for local presentation software and not for archival storage or for dynamic interchange among programs.
8.2.3.3: Basic SAN move construction
A basic SAN move is given by listing the moving piece letter (omitted for pawns) followed by the destination square. Capture moves are denoted by the lower case letter "x" immediately prior to the destination square; pawn captures include the file letter of the originating square of the capturing pawn immediately prior to the "x" character.
SAN kingside castling is indicated by the sequence "O-O"; queenside castling is indicated by the sequence "O-O-O". Note that the upper case letter "O" is used, not the digit zero. The use of a zero character is not only incompatible with traditional text practices, but it can also confuse parsing algorithms which also have to understand about move numbers and game termination markers. Also note that the use of the letter "O" is consistent with the practice of having all chess move symbols start with a letter; also, it follows the convention that all non-pwn move symbols start with an upper case letter.
En passant captures do not have any special notation; they are formed as if the captured pawn were on the capturing pawn's destination square. Pawn promotions are denoted by the equal sign "=" immediately following the destination square with a promoted piece letter (indicating one of knight, bishop, rook, or queen) immediately following the equal sign. As above, the piece letter is in upper case.
8.2.3.4: Disambiguation
In the case of ambiguities (multiple pieces of the same type moving to the same square), the first appropriate disambiguating step of the three following steps is taken:
First, if the moving pieces can be distinguished by their originating files, the originating file letter of the moving piece is inserted immediately after the moving piece letter.
Second (when the first step fails), if the moving pieces can be distinguished by their originating ranks, the originating rank digit of the moving piece is inserted immediately after the moving piece letter.
Third (when both the first and the second steps fail), the two character square coordinate of the originating square of the moving piece is inserted immediately after the moving piece letter.
Note that the above disambiguation is needed only to distinguish among moves of the same piece type to the same square; it is not used to distinguish among attacks of the same piece type to the same square. An example of this would be a position with two white knights, one on square c3 and one on square g1 and a vacant square e2 with White to move. Both knights attack square e2, and if both could legally move there, then a file disambiguation is needed; the (nonchecking) knight moves would be "Nce2" and "Nge2". However, if the white king were at square e1 and a black bishop were at square b4 with a vacant square d2 (thus an absolute pin of the white knight at square c3), then only one white knight (the one at square g1) could move to square e2: "Ne2".
8.2.3.5: Check and checkmate indication characters
If the move is a checking move, the plus sign "+" is appended as a suffix to the basic SAN move notation; if the move is a checkmating move, the octothorpe sign "#" is appended instead.
Neither the appearance nor the absence of either a check or checkmating indicator is used for disambiguation purposes. This means that if two (or more) pieces of the same type can move to the same square the differences in checking status of the moves does not allieviate the need for the standard rank and file disabiguation described above. (Note that a difference in checking status for the above may occur only in the case of a discovered check.)
Neither the checking or checkmating indicators are considered annotation as they do not communicate subjective information. Therefore, they are qualitatively different from move suffix annotations like "!" and "?". Subjective move annotations are handled using Numeric Annotation Glyphs as described in a later section of this document.
There are no special markings used for double checks or discovered checks.
There are no special markings used for drawing moves.
8.2.3.6: SAN move length
SAN moves can be as short as two characters (e.g., "d4"), or as long as seven characters (e.g., "Qa6xb7#", "fxg1=Q+"). The average SAN move length seen in realistic games is probably just fractionally longer than three characters. If the SAN rules seem complicated, be assured that the earlier notation systems of LEN (Long English Notation) and EDN (English Descriptive Notation) are much more complex, and that LAN (Long Algebraic Notation, the predecessor of SAN) is unnecessarily bulky.
8.2.3.7: Import and export SAN
PGN export format always uses the above canonical SAN to represent moves in the movetext section of a PGN game. Import format is somewhat more relaxed and it makes allowances for moves that do not conform exactly to the canonical format. However, these allowances may differ among different PGN reader programs. Only data appearing in export format is in all cases guaranteed to be importable into all PGN readers.
There are a number of suggested guidelines for use with implementing PGN reader software for permitting non-canonical SAN move representation. The idea is to have a PGN reader apply various transformations to attempt to discover the move that is represented by non-canonical input. Some suggested transformations include: letter case remapping, capture indicator insertion, check indicator insertion, and checkmate indicator insertion.
8.2.3.8: SAN move suffix annotations
Import format PGN allows for the use of traditional suffix annotations for moves. There are exactly six such annotations available: "!", "?", "!!", "!?", "?!", and "??". At most one such suffix annotation may appear per move, and if present, it is always the last part of the move symbol.
When exported, a move suffix annotation is translated into the corresponding Numeric Annotation Glyph as described in a later section of this document. For example, if the single move symbol "Qxa8?" appears in an import format PGN movetext, it would be replaced with the two adjacent symbols "Qxa8 $2".
8.2.4: Movetext NAG (Numeric Annotation Glyph)
An NAG (Numeric Annotation Glyph) is a movetext element that is used to indicate a simple annotation in a language independent manner. An NAG is formed from a dollar sign ("$") with a non-negative decimal integer suffix. The non-negative integer must be from zero to 255 in value.
8.2.5: Movetext RAV (Recursive Annotation Variation)
An RAV (Recursive Annotation Variation) is a sequence of movetext containing one or more moves enclosed in parentheses. An RAV is used to represent an alternative variation. The alternate move sequence given by an RAV is one that may be legally played by first unplaying the move that appears immediately prior to the RAV. Because the RAV is a recursive construct, it may be nested.
*** The specification for import/export representation of RAV elements needs further development.
8.2.6: Game Termination Markers
Each movetext section has exactly one game termination marker; the marker always occurs as the last element in the movetext. The game termination marker is a symbol that is one of the following four values: "1-0" (White wins), "0-1" (Black wins), "1/2-1/2" (drawn game), and "*" (game in progress, result unknown, or game abandoned). Note that the digit zero is used in the above; not the upper case letter "O". The game termination marker appearing in the movetext of a game must match the value of the game's Result tag pair. (While the marker appears as a string in the Result tag, it appears as a symbol without quotes in the movetext.)
9: Supplemental tag names
The following tag names and their associated semantics are recommended for use for information not contained in the Seven Tag Roster.
9.1: Player related information
Note that if there is more than one player field in an instance of a player (White or Black) tag, then there will be corresponding multiple fields in any of the following tags. For example, if the White tag has the three field value "Jones:Smith:Zacharias" (a consultation game), then the WhiteTitle tag could have a value of "IM:-:GM" if Jones was an International Master, Smith was untitled, and Zacharias was a Grandmaster.
9.1.1: Tags: WhiteTitle, BlackTitle
These use string values such as "FM", "IM", and "GM"; these tags are used only for the standard abbreviations for FIDE titles. A value of "-" is used for an untitled player.
9.1.2: Tags: WhiteElo, BlackElo
These tags use integer values; these are used for FIDE Elo ratings. A value of "-" is used for an unrated player.
9.1.3: Tags: WhiteUSCF, BlackUSCF
These tags use integer values; these are used for USCF (United States Chess Federation) ratings. Similar tag names can be constructed for other rating agencies.
9.1.4: Tags: WhiteNA, BlackNA
These tags use string values; these are the e-mail or network addresses of the players. A value of "-" is used for a player without an electronic address.
9.1.5: Tags: WhiteType, BlackType
These tags use string values; these describe the player types. The value "human" should be used for a person while the value "program" should be used for algorithmic (computer) players.
9.2: Event related information
The following tags are used for providing additional information about the event.
9.2.1: Tag: EventDate
This uses a date value, similar to the Date tag field, that gives the starting date of the Event.
9.2.2: Tag: EventSponsor
This uses a string value giving the name of the sponsor of the event.
9.2.3: Tag: Section
This uses a string; this is used for the playing section of a tournament (e.g., "Open" or "Reserve").
9.2.4: Tag: Stage
This uses a string; this is used for the stage of a multistage event (e.g., "Preliminary" or "Semifinal").
9.2.5: Tag: Board
This uses an integer; this identifies the board number in a team event and also in a simultaneous exhibition.
9.3: Opening information (locale specific)
The following tag pairs are used for traditional opening names. The associated tag values will vary according to the local language in use.
9.3.1: Tag: Opening
This uses a string; this is used for the traditional opening name. This will vary by locale. This tag pair is associated with the use of the EPD opcode "v0" described in a later section of this document.
9.3.2: Tag: Variation
This uses a string; this is used to further refine the Opening tag. This will vary by locale. This tag pair is associated with the use of the EPD opcode "v1" described in a later section of this document.
9.3.3: Tag: SubVariation
This uses a string; this is used to further refine the Variation tag. This will vary by locale. This tag pair is associated with the use of the EPD opcode "v2" described in a later section of this document.
9.4: Opening information (third party vendors)
The following tag pairs are used for representing opening identification according to various third party vendors and organizations. References to these organizations does not imply any endorsement of them or any endorsement by them.
9.4.1: Tag: ECO
This uses a string of either the form "XDD" or the form "XDD/DD" where the "X" is a letter from "A" to "E" and the "D" positions are digits; this is used for an opening designation from the five volume _Encyclopedia of Chess Openings_. This tag pair is associated with the use of the EPD opcode "eco" described in a later section of this document.
9.4.2: Tag: NIC
This uses a string; this is used for an opening designation from the _New in Chess_ database. This tag pair is associated with the use of the EPD opcode "nic" described in a later section of this document.
9.5: Time and date related information
The following tags assist with further refinement of the time and data information associated with a game.
9.5.1: Tag: Time
This uses a time-of-day value in the form "HH:MM:SS"; similar to the Date tag except that it denotes the local clock time (hours, minutes, and seconds) of the start of the game. Note that colons, not periods, are used for field separators for the Time tag value. The value is taken from the local time corresponding to the location given in the Site tag pair.
9.5.2: Tag: UTCTime
This tag is similar to the Time tag except that the time is given according to the Universal Coordinated Time standard.
9.5.3: Tag:; UTCDate
This tag is similar to the Date tag except that the date is given according to the Universal Coordinated Time standard.
9.6: Time control
The follwing tag is used to help describe the time control used with the game.
9.6.1: Tag: TimeControl
This uses a list of one or more time control fields. Each field contains a descriptor for each time control period; if more than one descriptor is present then they are separated by the colon character (":"). The descriptors appear in the order in which they are used in the game. The last field appearing is considered to be implicitly repeated for further control periods as needed.
There are six kinds of TimeControl fields.
The first kind is a single question mark ("?") which means that the time control mode is unknown. When used, it is usually the only descriptor present.
The second kind is a single hyphen ("-") which means that there was no time control mode in use. When used, it is usually the only descriptor present.
The third Time control field kind is formed as two positive integers separated by a solidus ("/") character. The first integer is the number of moves in the period and the second is the number of seconds in the period. Thus, a time control period of 40 moves in 2 1/2 hours would be represented as "40/9000".
The fourth TimeControl field kind is used for a "sudden death" control period. It should only be used for the last descriptor in a TimeControl tag value. It is sometimes the only descriptor present. The format consists of a single integer that gives the number of seconds in the period. Thus, a blitz game would be represented with a TimeControl tag value of "300".
The fifth TimeControl field kind is used for an "incremental" control period. It should only be used for the last descriptor in a TimeControl tag value and is usually the only descriptor in the value. The format consists of two positive integers separated by a plus sign ("+") character. The first integer gives the minimum number of seconds allocated for the period and the second integer gives the number of extra seconds added after each move is made. So, an incremental time control of 90 minutes plus one extra minute per move would be given by "4500+60" in the TimeControl tag value.
The sixth TimeControl field kind is used for a "sandclock" or "hourglass" control period. It should only be used for the last descriptor in a TimeControl tag value and is usually the only descriptor in the value. The format consists of an asterisk ("*") immediately followed by a positive integer. The integer gives the total number of seconds in the sandclock period. The time control is implemented as if a sandclock were set at the start of the period with an equal amount of sand in each of the two chambers and the players invert the sandclock after each move with a time forfeit indicated by an empty upper chamber. Electronic implementation of a physical sandclock may be used. An example sandclock specification for a common three minute egg timer sandclock would have a tag value of "*180".
Additional TimeControl field kinds will be defined as necessary.
9.7: Alternative starting positions
There are two tags defined for assistance with describing games that did not start from the usual initial array.
9.7.1: Tag: SetUp
This tag takes an integer that denotes the "set-up" status of the game. A value of "0" indicates that the game has started from the usual initial array. A value of "1" indicates that the game started from a set-up position; this position is given in the "FEN" tag pair. This tag must appear for a game starting with a set-up position. If it appears with a tag value of "1", a FEN tag pair must also appear.
9.7.2: Tag: FEN
This tag uses a string that gives the Forsyth-Edwards Notation for the starting position used in the game. FEN is described in a later section of this document. If a SetUp tag appears with a tag value of "1", the FEN tag pair is also required.
9.8: Game conclusion
There is a single tag that discusses the conclusion of the game.
9.8.1: Tag: Termination
This takes a string that describes the reason for the conclusion of the game. While the Result tag gives the result of the game, it does not provide any extra information and so the Termination tag is defined for this purpose.
Strings that may appear as Termination tag values:
* "abandoned": abandoned game.
* "adjudication": result due to third party adjudication process.
* "death": losing player called to greater things, one hopes.
* "emergency": game concluded due to unforeseen circumstances.
* "normal": game terminated in a normal fashion.
* "rules infraction": administrative forfeit due to losing player's failure to observe either the Laws of Chess or the event regulations.
* "time forfeit": loss due to losing player's failure to meet time control requirements.
* "unterminated": game not terminated.
9.9: Miscellaneous
These are tags that can be briefly described and that doon't fit well inother sections.
9.9.1: Tag: Annotator
This tag uses a name or names in the format of the player name tags; this identifies the annotator or annotators of the game.
9.9.2: Tag: Mode
This uses a string that gives the playing mode of the game. Examples: "OTB" (over the board), "PM" (paper mail), "EM" (electronic mail), "ICS" (Internet Chess Server), and "TC" (general telecommunication).
9.9.3: Tag: PlyCount
This tag takes a single integer that gives the number of ply (moves) in the game.
10: Numeric Annotation Glyphs
NAG zero is used for a null annotation; it is provided for the convenience of software designers as a placeholder value and should probably not be used in external PGN data.
NAGs with values from 1 to 9 annotate the move just played.
NAGs with values from 10 to 135 modify the current position.
NAGs with values from 136 to 139 describe time pressure.
Other NAG values are reserved for future definition.
Note: the number assignments listed below should be considered preliminary in nature; they are likely to be changed as a result of reviewer feedback.
NAG Interpretation
--- --------------
0 null annotation
1 good move (traditional "!")
2 poor move (traditional "?")
3 very good move (traditional "!!")
4 very poor move (traditional "??")
5 speculative move (traditional "!?")
6 questionable move (traditional "?!")
7 forced move (all others lose quickly)
8 singular move (no reasonable alternatives)
9 worst move
10 drawish position
11 equal chances, quiet position
12 equal chances, active position
13 unclear position
14 White has a slight advantage
15 Black has a slight advantage
16 White has a moderate advantage
17 Black has a moderate advantage
18 White has a decisive advantage
19 Black has a decisive advantage
20 White has a crushing advantage (Black should resign)
21 Black has a crushing advantage (White should resign)
22 White is in zugzwang
23 Black is in zugzwang
24 White has a slight space advantage
25 Black has a slight space advantage
26 White has a moderate space advantage
27 Black has a moderate space advantage
28 White has a decisive space advantage
29 Black has a decisive space advantage
30 White has a slight time (development) advantage
31 Black has a slight time (development) advantage
32 White has a moderate time (development) advantage
33 Black has a moderate time (development) advantage
34 White has a decisive time (development) advantage
35 Black has a decisive time (development) advantage
36 White has the initiative
37 Black has the initiative
38 White has a lasting initiative
39 Black has a lasting initiative
40 White has the attack
41 Black has the attack
42 White has insufficient compensation for material deficit
43 Black has insufficient compensation for material deficit
44 White has sufficient compensation for material deficit
45 Black has sufficient compensation for material deficit
46 White has more than adequate compensation for material deficit
47 Black has more than adequate compensation for material deficit
48 White has a slight center control advantage
49 Black has a slight center control advantage
50 White has a moderate center control advantage
51 Black has a moderate center control advantage
52 White has a decisive center control advantage
53 Black has a decisive center control advantage
54 White has a slight kingside control advantage
55 Black has a slight kingside control advantage
56 White has a moderate kingside control advantage
57 Black has a moderate kingside control advantage
58 White has a decisive kingside control advantage
59 Black has a decisive kingside control advantage
60 White has a slight queenside control advantage
61 Black has a slight queenside control advantage
62 White has a moderate queenside control advantage
63 Black has a moderate queenside control advantage
64 White has a decisive queenside control advantage
65 Black has a decisive queenside control advantage
66 White has a vulnerable first rank
67 Black has a vulnerable first rank
68 White has a well protected first rank
69 Black has a well protected first rank
70 White has a poorly protected king
71 Black has a poorly protected king
72 White has a well protected king
73 Black has a well protected king
74 White has a poorly placed king
75 Black has a poorly placed king
76 White has a well placed king
77 Black has a well placed king
78 White has a very weak pawn structure
79 Black has a very weak pawn structure
80 White has a moderately weak pawn structure
81 Black has a moderately weak pawn structure
82 White has a moderately strong pawn structure
83 Black has a moderately strong pawn structure
84 White has a very strong pawn structure
85 Black has a very strong pawn structure
86 White has poor knight placement
87 Black has poor knight placement
88 White has good knight placement
89 Black has good knight placement
90 White has poor bishop placement
91 Black has poor bishop placement
92 White has good bishop placement
93 Black has good bishop placement
84 White has poor rook placement
85 Black has poor rook placement
86 White has good rook placement
87 Black has good rook placement
98 White has poor queen placement
99 Black has poor queen placement
100 White has good queen placement
101 Black has good queen placement
102 White has poor piece coordination
103 Black has poor piece coordination
104 White has good piece coordination
105 Black has good piece coordination
106 White has played the opening very poorly
107 Black has played the opening very poorly
108 White has played the opening poorly
109 Black has played the opening poorly
110 White has played the opening well
111 Black has played the opening well
112 White has played the opening very well
113 Black has played the opening very well
114 White has played the middlegame very poorly
115 Black has played the middlegame very poorly
116 White has played the middlegame poorly
117 Black has played the middlegame poorly
118 White has played the middlegame well
119 Black has played the middlegame well
120 White has played the middlegame very well
121 Black has played the middlegame very well
122 White has played the ending very poorly
123 Black has played the ending very poorly
124 White has played the ending poorly
125 Black has played the ending poorly
126 White has played the ending well
127 Black has played the ending well
128 White has played the ending very well
129 Black has played the ending very well
130 White has slight counterplay
131 Black has slight counterplay
132 White has moderate counterplay
133 Black has moderate counterplay
134 White has decisive counterplay
135 Black has decisive counterplay
136 White has moderate time control pressure
137 Black has moderate time control pressure
138 White has severe time control pressure
139 Black has severe time control pressure
11: File names and directories
File names chosen for PGN data should be both informative and portable. The directory names and arrangements should also be chosen for the same reasons and also for ease of navigation.
Some of suggested file and directory names may be difficult or impossible to represent on certain computing systems. Use of appropriate conversion customs is encouraged.
11.1: File name suffix for PGN data
The use of the file suffix ".pgn" is encouraged for ASCII text files containing PGN data.
11.2: File name formation for PGN data for a specific player
PGN games for a specific player should have a file name consisting of the player's last name followed by the ".pgn" suffix.
11.3: File name formation for PGN data for a specific event
PGN games for a specific event should have a file name consisting of the event's name followed by the ".pgn" suffix.
11.4: File name formation for PGN data for chronologically ordered games
PGN data files used for chronologically ordered (oldest first) archives use date information as file name root strings. A file containing all the PGN games for a given year would have an eight character name in the format "YYYY.pgn". A file containing PGN data for a given month would have a ten character name in the format "YYYYMM.pgn". Finally, a file for PGN games for a single day would have a twelve character name in the format "YYYYMMDD.pgn". Large files are split into smaller files as needed.
As game files are commonly arranged by chronological order, games with missing or incomplete Date tag pair data are to be avoided. Any question mark characters in a Date tag value will be treated as zero digits for collation within a file and also for file naming.
Large quantities of PGN data arranged by chronological order should be organized into hierarchical directories. A directory containing all PGN data for a given year would have a four character name in the format "YYYY"; directories containing PGN files for a given month would have a six character name in the format "YYYYMM".
11.5: Suggested directory tree organization
A suggested directory arrangement for ftp sites and CD-ROM distributions:
* PGN: master directory of the PGN subtree (pub/chess/Game-Databases/PGN)
* PGN/Events: directory of PGN files, each for a specific event
* PGN/Events/News: news and status of the event collection
* PGN/Events/ReadMe: brief description of the local directory contents
* PGN/MGR: directory of the Master Games Repository subtree
* PGN/MGR/News: news and status of the entire PGN/MGR subtree
* PGN/MGR/ReadMe: brief description of the local directory contents
* PGN/MGR/YYYY: directory of games or subtrees for the year YYYY
* PGN/MGR/YYYY/ReadMe: description of local directory for year YYYY
* PGN/MGR/YYYY/News: news and status for year YYYY data
* PGN/News: news and status of the entire PGN subtree
* PGN/Players: directory of PGN files, each for a specific player
* PGN/Players/News: news and status of the player collection
* PGN/Players/ReadMe: brief description of the local directory contents
* PGN/ReadMe: brief description of the local directory contents
* PGN/Standard: the PGN standard (this document)
* PGN/Tools: software utilities that access PGN data
12: PGN collating sequence
There is a standard sorting order for PGN games within a file. This collation is based on eight keys; these are the seven tag values of the STR and also the movetext itself.
The first (most important, primary key) is the Date tag. Earlier dated games appear prior to games played at a later date. This field is sorted by ascending numeric value first with the year, then the month, and finally the day of the month. Query characters used for unknown date digit values will be treated as zero digit characters for ordering comparison.
The second key is the Event tag. This is sorted in ascending ASCII order.
The third key is the Site tag. This is sorted in ascending ASCII order.
The fourth key is the Round tag. This is sorted in ascending numeric order based on the value of the integer used to denote the playing round. A query or hyphen used for the round is ordered before any integer value. A query character is ordered before a hyphen character.
The fifth key is the White tag. This is sorted in ascending ASCII order.
The sixth key is the Black tag. This is sorted in ascending ASCII order.
The seventh key is the Result tag. This is sorted in ascending ASCII order.
The eighth key is the movetext itself. This is sorted in ascending ASCII order with the entire text including spaces and newline characters.
13: PGN software
This section describes some PGN software that is either currently available or expected to be available in the near future. The entries are presented in rough chronological order of their being made known to the PGN standard coordinator. Authors of PGN capable software are encouraged to contact the coordinator (e-mail address listed near the start of this document) so that the information may be included here in this section.
In addition to the PGN standard, there are two more chess standards of interest to the chess software community. These are the FEN standard (Forsyth-Edwards Notation) for position notation and the EPD standard (Extended Position Description) for comprehensive position description for automated interprogram processing. These are described in a later section of this document.
Some PGN software is freeware and can be gotten from ftp sites and other sources. Other PGN software is payware and appears as part of commercial chessplaying programs and chess database managers. Those who are interested in the propagation of the PGN standard are encouraged to support manufacturers of chess software that use the standard. If a particular vendor does not offer PGN compatibility, it is likely that a few letters to them along with a copy of this specification may help them decide to include PGN support in their next release.
The staff at the University of Oklahoma at Norman (USA) have graciously provided an ftp site (chess.uoknor.edu) for the storage of chess related data and programs. Because file names change over time, those accessing the site are encouraged to first retrieve the file "pub/chess/ls-lR.gz" for a current listing. A scan of this listing will also help locate versions of PGN programs for machine types and operating systems other than those listed below. Further information about this archive can be gotten from its administrator, Chris Petroff (chris@uoknor.edu).
For European users, the kind staff at the University of Hamburg (Germany) have provided the ftp site ftp.math.uni-hamburg.de; this carries a daily mirror of the pub/chess directory at the chess.uoknor.edu site.
13.1: The SAN Kit
The "SAN Kit" is an ANSI C source chess programming toolkit available for free from the ftp site chess.uoknor.edu in the directory pub/chess/Unix as the file "SAN.tar.gz" (a gzip tar archive). This kit contains code for PGN import and export and can be used to "regularize" PGN data into reduced export format by use of its "tfgg" command. The SAN Kit also supports FEN I/O. Code from this kit is freely redistributable for anyone as long as future distribution is unhindered for everyone. The SAN Kit is undergoing continuous development, although dates of future deliveries are quite difficult to predict and releases sometimes appear months apart. Suggestions and comments should be directed to its author, Steven J. Edwards (sje@world.std.com).
13.2: pgnRead
The program "pgnRead" runs under MS Windows 3.1 and provides an interactive graphical user interface for scanning PGN data files. This program includes a colorful figurine chessboard display and scrolling controls for game and game text selection. It is available from the chess.uoknor.edu ftp site in the pub/chess/DOS directory; several versions are available with names of the form "pgnrd**.exe"; the latest at this writing is "PGNRD130.EXE". Suggestions and comments should be directed to its author, Keith Fuller (keithfx@aol.com).
13.3: mail2pgn/GIICS
The program "mail2pgn" produces a PGN version of chess game data generated by the ICS (Internet Chess Server). It can be found at the chess.uoknor.edu ftp site in the pub/chess/DOS directory as the file "mail2pgn.zip" A C language version is in the directory pub/chess/Unix as the file "mail2pgn.c". Suggestions and comments should be directed to its author, John Aronson (aronson@helios.ece.arizona.edu). This code has been reportedly incorporated into the GIICS (Graphical Interface for the ICS); suggestions and comments should be directed to its author, Tony Acero (ace3@midway.uchicago.edu).
There is a report that mail2pgn has been superseded by the newer program "MV2PGN" described below.
13.4: XBoard
"XBoard" is a comprehensive chess utility running under the X Window System that provides a graphical user interface in a portable manner. A new version now handles PGN data. It is available from the chess.uoknor.edu ftp site in the pub/chess/X directory as the file "xboard-3.0.pl9.tar.gz". Suggestions and comments should be directed to its author, Tim Mann (mann@src.dec.com).
13.5: cupgn
The program "cupgn" converts game data stored in the ChessBase format into PGN. It is available from the chess.uoknor.edu ftp site in the pub/chess/Game-Databases/CBUFF directory as the file "cupgn.tar.gz". Another version is in the directory pub/chess/DOS as the file "cupgn120.exe". Suggestions and comments should be directed to its author, Anjo Anjewierden (anjo@swi.psy.uva.nl).
13.6: Zarkov
The current version (3.0) of the commercial chessplaying program "Zarkov" can read and write games using PGN. This program can also use the EPD standard for communication with other EPD capable programs. Historically, Zarkov is the very first program to use EPD. Suggestions and comments should be directed to its author, John Stanback (jhs@icbdfcs1.fc.hp.com).
A vendor for North America is:
International Chess Enterprises
P.O. Box 19457
Seattle, WA 98109
USA
(800) 262-4277
A vendor for Europe is:
Gambit-Soft
Feckenhauser Strasse 27
D-78628 Rottweil
GERMANY
49-741-21573
13.7: Chess Assistant
The upcoming version of the multifunction commercial database program "Chess Assistant" will be able to use the PGN standard as an import and export option. There is a report of a freeware program, "PGN2CA", that will convert PGN databases into Chess Assistant format. For more information, the contact is Victor Zakharov, one of the members of the Chess Assistant development team (VICTOR@ldis.cs.msu.su).
A vendor for North America is:
International Chess Enterprises
P.O. Box 19457
Seattle, WA 98109
USA
(800) 262-4277
13.8: BOOKUP
The MS-DOS edition of the multifunction commercial program BOOKUP, version 8.1, is able to use the EPD standard for communication with other EPD capable programs. It may also be PGN capable as well.
The BOOKUP 8.1.1 Addenda notes dated 1993.12.17 provide comprehensive information on how to use EPD in conjunction with "analyst" programs such as Zarkov and HIARCS. Specifically, the search and evaluation abilities of an analyst program are combined with the information organization abilities of the BOOKUP database program to provide position scoring. This is done by first having BOOKUP export a database in EPD format, then having an analyst program annotate each EPD record with a numeric score, and then having BOOKUP import the changed EPD file. BOOKUP can then apply minimaxing to the imported database; this results in scores from terminal positions being propagated back to earlier positions and even back to moves from the starting array.
For some reason, BOOKUP calls this process "backsolving", but it's really just standard minimaxing. In any case, it's a good example of how different programs from different authors performing different types of tasks can be integrated by use of a common, non-proprietary standard. This allows for a new set of powerful features that are beyond the capabilities of any one of the individual component programs.
BOOKUP allows for some customizing of EPD actions. One such customization is to require the positional evaluations to follow the EPD standard; this means that the score is always given from the viewpoint of the active player. This is explained more fully in the section on the "ce" (centipawn evaluation) opcode in the EPD description in a later section of this document. To ensure that BOOKUP handles the centipawn evaluations in the "right" way, the EPD setting "Positive for White" must be set to "N". This makes BOOKUP work correctly with Zarkov and with all other programs that use the "right" centipawn evaluation convention. There is an apparent problem with HIARCS that requires this option to be set to "Y"; but this really means that, if true, HIARCS needs to be adjusted to use the "right" centipawn evaluation convention.
A vendor in North America is:
BOOKUP
2763 Kensington Place West
Columbus, OH 43202
USA
(800) 949-5445
(614) 263-7219
13.9: HIARCS
The current version (2.1) of the commercial chessplaying program "HIARCS" is able to use the EPD standard for communication with other EPD capable programs. It may also be PGN capable as well. More details will appear here as they become available.
A vendor in North America is:
HIARCS
c/o BOOKUP
2763 Kensington Place West
Columbus, OH 43202
USA
(800) 949-5445
(614) 263-7219
13.10: Deja Vu
The chess database "Deja Vu" from ChessWorks is a PGN compatible collection of over 300,000 games. It is available only on CD-ROM and is scheduled for release in 1994.05 with periodic revisions thereafter. The introductory price is US$329. For further information, the authors are John Crayton and Eric Schiller and they can be contacted via e-mail (chesswks@netcom.com).
13.11: MV2PGN
The program "MV2PGN" can be used to convert game data generated by both current and older versions of the GIICS (Graphical Interface - Internet Chess Server). The program is included in the self extracting archive available from chess.uoknor.edu in the directory pub/chess/DOS as the file "ics2pgn.exe". Source code is also included. This program is reported to supersede the older "mail2pgn" and was needed due to a change in ICS recording format in late 1993. For further information about MV2PGN, the contact person is Gary Bastin (gbastin@x102a.ess.harris.com).
13.12: The Hansen utilities (cb2pgn, nic2pgn, pgn2cb, pgn2nic)
The Hansen utilities are used to convert among various chess data representation formats. The PGN related programs include: "cb2pgn.exe" (convert ChessBase to PGN), "nic2pgn.exe" (convert NIC to PGN), "pgn2cb.exe" (convert PGN to ChessBase), and "pgn2nic.exe" (convert PGN to NIC).
The ChessBase related utilities (cb2pgn/pgn2cb) are found at chess.uoknor.edu in the pub/chess/Game-Databases/ChessBase directory.
The NIC related utilities (nic2pgn/pgn2nic) are found at chess.uoknor.edu in the pub/chess/Game-Databases/NIC directory.
For further information about the Hansen utilities, the contact person is the author, Carsten Hansen (ch0506@hdc.hha.dk).
13.13: Slappy the Database
"Slappy the Database" is a commercial chess database and translation program scheduled for release no sooner than late 1994. It is a low cost utility with a simple character interface intended for those who want a supported product but who do not need (or cannot afford) a comprehensive, feature-laden program with a graphical user interface. Slappy's two most important features are its batch processing ability and its full implementation of each and every standard described in this document. Versions of Slappy the Database will be provided for various platforms including: Intel 386/486 Unix, Apple Macintosh, and MS-DOS.
Slappy may also be useful to those who have a full feature program who also need to run time consuming chess database tasks on a spare computer.
Suggestions and comments should be directed to its author, Steven J. Edwards (sje@world.std.com). More details will appear here as they become available.
13.14: CBASCII
"CBASCII" is a general utility for converting chess data between ChessBase format and ASCII representations. It has PGN capability, and it is available from the chess.uoknor.edu ftp site in the pub/chess/DOS directory as the file "cba1_2.zip". The contact person is the program's author, Andy Duplain (duplain@btcs.bt.co.uk).
13.15: ZZZZZZ
"ZZZZZZ" is a chessplaying program, complete with source, that also includes some database functions. A recent version is reported to have both PGN and EPD capabilities. It is available from the chess.uoknor.edu ftp site in the pub/chess/Unix directory as the file "zzzzzz-3.2b1.tar.gz". The contact person is its author, Gijsbert Wiesenecker (wiesenecker@sara.nl).
13.16: icsconv
The program "icsconv" can be used to convert Internet Chess Server games, both old and new format, to PGN. It is available from the chess.uoknor.edu site in the pub/chess/Game-Databases/PGN/Tools directory as the file "icsconv.exe". The contact person is the author, Kevin Nomura (chow@netcom.com).
13.17: CHESSOP (CHESSOPN/CHESSOPG)
CHESSOP is an openings database and viewing tool with support for reading PGN games. It runs under MS-DOS and displays positions rather than games. For each position, both good and bad moves are listed with appropriate annotation. Transpositions are handled as well. The distributed database contains over 100,000 positions covering all the common openings. Users can feed in their own PGN data as well. CHESSOP takes 3 Mbyte of hard disk, costs US$39 and can be obtained from:
CHESSX Software
12 Bluebell Close
Glenmore Park
AUSTRALIA 2745.
The ideas behind CHESSOP can be seen in CHESSOPN (alias CHESSOPG), a free version on the ICS server which has a reduced openings database (25,000 positions) and no PGN or transposition support but is otherwise the same as CHESSOP. (These are the files "chessopg.zip" in the directory pub/chess/DOS at the chess.uoknor.edu ftp site.)
13.18: CAT2PGN
The program "CAT2PGN" is a utility that translates data from the format used by Chess Assistant into PGN. It is available from the chess.uoknor.edu ftp site. The contact person for CAT2PGN is its author, David Myers (myers@frodo.biochem.duke.edu).
13.19: pgn2opg
The utility "pgn2opg" can be used to convert PGN files into a text format used by the "CHESSOPG" program mentioned above. Although it does not perform any semantic analysis on PGN input, it has been demonstrated to handle known correct PGN input properly. The file can be found in the pub/chess/PGN/Tools directory at the chess.uoknor.edu ftp site. For more information, the author is David Barnes (djb@ukc.ac.uk).
14: PGN data archives
The primary PGN data archive repository is located at the ftp site chess.uoknor.edu as the directory "pub/chess/Game-Databases/PGN". It is organized according to the description given in section C.5 of this document. The European site ftp.math.uni-hamburg.de is also reported to carry a regularly updated copy of the repository.
15: International Olympic Committee country codes
International Olympic Committee country codes are employed for Site nation information because of their traditional use with the reporting of international sporting events. Due to changes in geography and linguistic custom, some of the following may be incorrect or outdated. Corrections and extensions should be sent via e-mail to the PGN coordinator whose address listed near the start of this document.
AFG: Afghanistan
AIR: Aboard aircraft
ALB: Albania
ALG: Algeria
AND: Andorra
ANG: Angola
ANT: Antigua
ARG: Argentina
ARM: Armenia
ATA: Antarctica
AUS: Australia
AZB: Azerbaijan
BAN: Bangladesh
BAR: Bahrain
BHM: Bahamas
BEL: Belgium
BER: Bermuda
BIH: Bosnia and Herzegovina
BLA: Belarus
BLG: Bulgaria
BLZ: Belize
BOL: Bolivia
BRB: Barbados
BRS: Brazil
BRU: Brunei
BSW: Botswana
CAN: Canada
CHI: Chile
COL: Columbia
CRA: Costa Rica
CRO: Croatia
CSR: Czechoslovakia
CUB: Cuba
CYP: Cyprus
DEN: Denmark
DOM: Dominican Republic
ECU: Ecuador
EGY: Egypt
ENG: England
ESP: Spain
EST: Estonia
FAI: Faroe Islands
FIJ: Fiji
FIN: Finland
FRA: France
GAM: Gambia
GCI: Guernsey-Jersey
GEO: Georgia
GER: Germany
GHA: Ghana
GRC: Greece
GUA: Guatemala
GUY: Guyana
HAI: Haiti
HKG: Hong Kong
HON: Honduras
HUN: Hungary
IND: India
IRL: Ireland
IRN: Iran
IRQ: Iraq
ISD: Iceland
ISR: Israel
ITA: Italy
IVO: Ivory Coast
JAM: Jamaica
JAP: Japan
JRD: Jordan
JUG: Yugoslavia
KAZ: Kazakhstan
KEN: Kenya
KIR: Kyrgyzstan
KUW: Kuwait
LAT: Latvia
LEB: Lebanon
LIB: Libya
LIC: Liechtenstein
LTU: Lithuania
LUX: Luxembourg
MAL: Malaysia
MAU: Mauritania
MEX: Mexico
MLI: Mali
MLT: Malta
MNC: Monaco
MOL: Moldova
MON: Mongolia
MOZ: Mozambique
MRC: Morocco
MRT: Mauritius
MYN: Myanmar
NCG: Nicaragua
NET: The Internet
NIG: Nigeria
NLA: Netherlands Antilles
NLD: Netherlands
NOR: Norway
NZD: New Zealand
OST: Austria
PAK: Pakistan
PAL: Palestine
PAN: Panama
PAR: Paraguay
PER: Peru
PHI: Philippines
PNG: Papua New Guinea
POL: Poland
POR: Portugal
PRC: People's Republic of China
PRO: Puerto Rico
QTR: Qatar
RIN: Indonesia
ROM: Romania
RUS: Russia
SAF: South Africa
SAL: El Salvador
SCO: Scotland
SEA: At Sea
SEN: Senegal
SEY: Seychelles
SIP: Singapore
SLV: Slovenia
SMA: San Marino
SPC: Aboard spacecraft
SRI: Sri Lanka
SUD: Sudan
SUR: Surinam
SVE: Sweden
SWZ: Switzerland
SYR: Syria
TAI: Thailand
TMT: Turkmenistan
TRK: Turkey
TTO: Trinidad and Tobago
TUN: Tunisia
UAE: United Arab Emirates
UGA: Uganda
UKR: Ukraine
UNK: Unknown
URU: Uruguay
USA: United States of America
UZB: Uzbekistan
VEN: Venezuela
VGB: British Virgin Islands
VIE: Vietnam
VUS: U.S. Virgin Islands
WLS: Wales
YEM: Yemen
YUG: Yugoslavia
ZAM: Zambia
ZIM: Zimbabwe
ZRE: Zaire
16: Additional chess data standards
While PGN is used for game storage, there are other data representation standards for other chess related purposes. Two important standards are FEN and EPD, both described in this section.
16.1: FEN
FEN is "Forsyth-Edwards Notation"; it is a standard for describing chess positions using the ASCII character set.
A single FEN record uses one text line of variable length composed of six data fields. The first four fields of the FEN specification are the same as the first four fields of the EPD specification.
A text file composed exclusively of FEN data records should have a file name with the suffix ".fen".
16.1.1: History
FEN is based on a 19th century standard for position recording designed by the Scotsman David Forsyth, a newspaper journalist. The original Forsyth standard has been slightly extended for use with chess software by Steven Edwards with assistance from commentators on the Internet. This new standard, FEN, was first implemented in Edwards' SAN Kit.
16.1.2: Uses for a position notation
Having a standard position notation is particularly important for chess programmers as it allows them to share position databases. For example, there exist standard position notation databases with many of the classical benchmark tests for chessplaying programs, and by using a common position notation format many hours of tedious data entry can be saved. Additionally, a position notation can be useful for page layout programs and for confirming position status for e-mail competition.
Many interesting chess problem sets represented using FEN can be found at the chess.uoknor.edu ftp site in the directory pub/chess/SAN_testsuites.
16.1.3: Data fields
FEN specifies the piece placement, the active color, the castling availability, the en passant target square, the halfmove clock, and the fullmove number. These can all fit on a single text line in an easily read format. The length of a FEN position description varies somewhat according to the position. In some cases, the description could be eighty or more characters in length and so may not fit conveniently on some displays. However, these positions aren't too common.
A FEN description has six fields. Each field is composed only of non-blank printing ASCII characters. Adjacent fields are separated by a single ASCII space character.
16.1.3.1: Piece placement data
The first field represents the placement of the pieces on the board. The board contents are specified starting with the eighth rank and ending with the first rank. For each rank, the squares are specified from file a to file h. White pieces are identified by uppercase SAN piece letters ("PNBRQK") and black pieces are identified by lowercase SAN piece letters ("pnbrqk"). Empty squares are represented by the digits one through eight; the digit used represents the count of contiguous empty squares along a rank. A solidus character "/" is used to separate data of adjacent ranks.
16.1.3.2: Active color
The second field represents the active color. A lower case "w" is used if White is to move; a lower case "b" is used if Black is the active player.
16.1.3.3: Castling availability
The third field represents castling availability. This indicates potential future castling that may of may not be possible at the moment due to blocking pieces or enemy attacks. If there is no castling availability for either side, the single character symbol "-" is used. Otherwise, a combination of from one to four characters are present. If White has kingside castling availability, the uppercase letter "K" appears. If White has queenside castling availability, the uppercase letter "Q" appears. If Black has kingside castling availability, the lowercase letter "k" appears. If Black has queenside castling availability, then the lowercase letter "q" appears. Those letters which appear will be ordered first uppercase before lowercase and second kingside before queenside. There is no white space between the letters.
16.1.3.4: En passant target square
The fourth field is the en passant target square. If there is no en passant target square then the single character symbol "-" appears. If there is an en passant target square then is represented by a lowercase file character immediately followed by a rank digit. Obviously, the rank digit will be "3" following a white pawn double advance (Black is the active color) or else be the digit "6" after a black pawn double advance (White being the active color).
An en passant target square is given if and only if the last move was a pawn advance of two squares. Therefore, an en passant target square field may have a square name even if there is no pawn of the opposing side that may immediately execute the en passant capture.
16.1.3.5: Halfmove clock
The fifth field is a nonnegative integer representing the halfmove clock. This number is the count of halfmoves (or ply) since the last pawn advance or capturing move. This value is used for the fifty move draw rule.
16.1.3.6: Fullmove number
The sixth and last field is a positive integer that gives the fullmove number. This will have the value "1" for the first move of a game for both White and Black. It is incremented by one immediately after each move by Black.
16.1.4: Examples
Here's the FEN for the starting position:
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
And after the move 1. e4:
rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1
And then after 1. ... c5:
rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2
And then after 2. Nf3:
rnbqkbnr/pp1ppppp/8/2p5/4P3/5N2/PPPP1PPP/RNBQKB1R b KQkq - 1 2
For two kings on their home squares and a white pawn on e2 (White to move) with thirty eight full moves played with five halfmoves since the last pawn move or capture:
4k3/8/8/8/8/8/4P3/4K3 w - - 5 39
16.2: EPD
EPD is "Extended Position Description"; it is a standard for describing chess positions along with an extended set of structured attribute values using the ASCII character set. It is intended for data and command interchange among chessplaying programs. It is also intended for the representation of portable opening library repositories.
A single EPD uses one text line of variable length composed of four data field followed by zero or more operations. The four fields of the EPD specification are the same as the first four fields of the FEN specification.
A text file composed exclusively of EPD data records should have a file name with the suffix ".epd".
16.2.1: History
EPD is based in part on the earlier FEN standard; it has added extensions for use with opening library preparation and also for general data and command interchange among advanced chess programs. EPD was developed by John Stanback and Steven Edwards; its first implementation is in Stanback's master strength chessplaying program Zarkov.
16.2.2: Uses for an extended position notation
Like FEN, EPD can also be used for general position description. However, unlike FEN, EPD is designed to be expandable by the addition of new operations that provide new functionality as needs arise.
Many interesting chess problem sets represented using EPD can be found at the chess.uoknor.edu ftp site in the directory pub/chess/SAN_testsuites.
16.2.3: Data fields
EPD specifies the piece placement, the active color, the castling availability, and the en passant target square of a position. These can all fit on a single text line in an easily read format. The length of an EPD position description varies somewhat according to the position and any associated operations. In some cases, the description could be eighty or more characters in length and so may not fit conveniently on some displays. However, most EPD descriptions pass among programs only and these are not usually seen by program users.
(Note: due to the likelihood of future expansion of EPD, implementors are encouraged to have their programs handle EPD text lines of up to 1024 characters long.)
Each EPD data field is composed only of non-blank printing ASCII characters. Adjacent data fields are separated by a single ASCII space character.
16.2.3.1: Piece placement data
The first field represents the placement of the pieces on the board. The board contents are specified starting with the eighth rank and ending with the first rank. For each rank, the squares are specified from file a to file h. White pieces are identified by uppercase SAN piece letters ("PNBRQK") and black pieces are identified by lowercase SAN piece letters ("pnbrqk"). Empty squares are represented by the digits one through eight; the digit used represents the count of contiguous empty squares along a rank. A solidus character "/" is used to separate data of adjacent ranks.
16.2.3.2: Active color
The second field represents the active color. A lower case "w" is used if White is to move; a lower case "b" is used if Black is the active player.
16.2.3.3: Castling availability
The third field represents castling availability. This indicates potential future castling that may or may not be possible at the moment due to blocking pieces or enemy attacks. If there is no castling availability for either side, the single character symbol "-" is used. Otherwise, a combination of from one to four characters are present. If White has kingside castling availability, the uppercase letter "K" appears. If White has queenside castling availability, the uppercase letter "Q" appears. If Black has kingside castling availability, the lowercase letter "k" appears. If Black has queenside castling availability, then the lowercase letter "q" appears. Those letters which appear will be ordered first uppercase before lowercase and second kingside before queenside. There is no white space between the letters.
16.2.3.4: En passant target square
The fourth field is the en passant target square. If there is no en passant target square then the single character symbol "-" appears. If there is an en passant target square then is represented by a lowercase file character immediately followed by a rank digit. Obviously, the rank digit will be "3" following a white pawn double advance (Black is the active color) or else be the digit "6" after a black pawn double advance (White being the active color).
An en passant target square is given if and only if the last move was a pawn advance of two squares. Therefore, an en passant target square field may have a square name even if there is no pawn of the opposing side that may immediately execute the en passant capture.
16.2.4: Operations
An EPD operation is composed of an opcode followed by zero or more operands and is concluded by a semicolon.
Multiple operations are separated by a single space character. If there is at least one operation present in an EPD line, it is separated from the last (fourth) data field by a single space character.
16.2.4.1: General format
An opcode is an identifier that starts with a letter character and may be followed by up to fourteen more characters. Each additional character may be a letter or a digit or the underscore character.
An operand is either a set of contiguous non-white space printing characters or a string. A string is a set of contiguous printing characters delimited by a quote character at each end. A string value must have less than 256 bytes of data.
If at least one operand is present in an operation, there is a single space between the opcode and the first operand. If more than one operand is present in an operation, there is a single blank character between every two adjacent operands. If there are no operands, a semicolon character is appended to the opcode to mark the end of the operation. If any operands appear, the last operand has an appended semicolon that marks the end of the operation.
Any given opcode appears at most once per EPD record. Multiple operations in a single EPD record should appear in ASCII order of their opcode names (mnemonics). However, a program reading EPD records may allow for operations not in ASCII order by opcode mnemonics; the semantics are the same in either case.
Some opcodes that allow for more than one operand may have special ordering requirements for the operands. For example, the "pv" (predicted variation) opcode requires its operands (moves) to appear in the order in which they would be played. All other opcodes that allow for more than one operand should have operands appearing in ASCII order. An example of the latter set is the "bm" (best move[s]) opcode; its operands are moves that are all immediately playable from the current position.
Some opcodes require one or more operands that are chess moves. These moves should be represented using SAN. If a different representation is used, there is no guarantee that the EPD will be read correctly during subsequent processing.
Some opcodes require one or more operands that are integers. Some opcodes may require that an integer operand must be within a given range; the details are described in the opcode list given below. A negative integer is formed with a hyphen (minus sign) preceding the integer digit sequence. An optional plus sign may be used for indicating a non-negative value, but such use is not required and is indeed discouraged.
Some opcodes require one or more operands that are floating point numbers. Some opcodes may require that a floating point operand must be within a given range; the details are described in the opcode list given below. A floating point operand is constructed from an optional sign character ("+" or "-"), a digit sequence (with at least one digit), a radix point (always "."), and a final digit sequence (with at least one digit).
16.2.4.2: Opcode mnemonics
An opcode mnemonic used for archival storage and for interprogram communication starts with a lower case letter and is composed of only lower case letters, digits, and the underscore character (i.e., no upper case letters). These mnemonics will also all be at least two characters in length.
Opcode mnemonics used only by a single program or an experimental suite of programs should start with an upper case letter. This is so they may be easily distinguished should they be inadvertently be encountered by other programs. When a such a "private" opcode be demonstrated to be widely useful, it should be brought into the official list (appearing below) in a lower case form.
If a given program does not recognize a particular opcode, that operation is simply ignored; it is not signaled as an error.
16.2.5: Opcode list
The opcodes are listed here in ASCII order of their mnemonics. Suggestions for new opcodes should be sent to the PGN standard coordinator listed near the start of this document.
16.2.5.1: Opcode "acn": analysis count: nodes
The opcode "acn" takes a single non-negative integer operand. It is used to represent the number of nodes examined in an analysis. Note that the value may be quite large for some extended searches and so use of (at least) a long (four byte) representation is suggested.
16.2.5.2: Opcode "acs": analysis count: seconds
The opcode "acs" takes a single non-negative integer operand. It is used to represent the number of seconds used for an analysis. Note that the value may be quite large for some extended searches and so use of (at least) a long (four byte) representation is suggested.
16.2.5.3: Opcode "am": avoid move(s)
The opcode "am" indicates a set of zero or more moves, all immediately playable from the current position, that are to be avoided in the opinion of the EPD writer. Each operand is a SAN move; they appear in ASCII order.
16.2.5.4: Opcode "bm": best move(s)
The opcode "bm" indicates a set of zero or more moves, all immediately playable from the current position, that are judged to the best available by the EPD writer. Each operand is a SAN move; they appear in ASCII order.
16.2.5.5: Opcode "c0": comment (primary, also "c1" though "c9")
The opcode "c0" (lower case letter "c", digit character zero) indicates a top level comment that applies to the given position. It is the first of ten ranked comments, each of which has a mnemonic formed from the lower case letter "c" followed by a single decimal digit. Each of these opcodes takes either a single string operand or no operand at all.
This ten member comment family of opcodes is intended for use as descriptive commentary for a complete game or game fragment. The usual processing of these opcodes are as follows:
1) At the beginning of a game (or game fragment), a move sequence scanning program initializes each element of its set of ten comment string registers to be null.
2) As the EPD record for each position in the game is processed, the comment operations are interpreted from left to right. (Actually, all operations in n EPD record are interpreted from left to right.) Because operations appear in ASCII order according to their opcode mnemonics, opcode "c0" (if present) will be handled prior to all other opcodes, then opcode "c1" (if present), and so forth until opcode "c9" (if present).
3) The processing of opcode "cN" (0 <= N <= 9) involves two steps. First, all comment string registers with an index equal to or greater than N are set to null. (This is the set "cN" though "c9".) Second, and only if a string operand is present, the value of the corresponding comment string register is set equal to the string operand.
16.2.5.6: Opcode "ce": centipawn evaluation
The opcode "ce" indicates the evaluation of the indicated position in centipawn units. It takes a single operand, an optionally signed integer that gives an evaluation of the position from the viewpoint of the active player; i.e., the player with the move. Positive values indicate a position favorable to the moving player while negative values indicate a position favorable to the passive player; i.e., the player without the move. A centipawn evaluation value close to zero indicates a neutral positional evaluation.
Values are restricted to integers that are equal to or greater than -32767 and are less than or equal to 32766.
A value greater than 32000 indicates the availability of a forced mate to the active player. The number of plies until mate is given by subtracting the evaluation from the value 32767. Thus, a winning mate in N fullmoves is a mate in ((2 * N) - 1) halfmoves (or ply) and has a corresponding centipawn evaluation of (32767 - ((2 * N) - 1)). For example, a mate on the move (mate in one) has a centipawn evaluation of 32766 while a mate in five has a centipawn evaluation of 32758.
A value less than -32000 indicates the availability of a forced mate to the passive player. The number of plies until mate is given by subtracting the evaluation from the value -32767 and then negating the result. Thus, a losing mate in N fullmoves is a mate in (2 * N) halfmoves (or ply) and has a corresponding centipawn evaluation of (-32767 + (2 * N)). For example, a mate after the move (losing mate in one) has a centipawn evaluation of -32765 while a losing mate in five has a centipawn evaluation of -32757.
A value of -32767 indicates an illegal position. A stalemate position has a centipawn evaluation of zero as does a position drawn due to insufficient mating material. Any other position known to be a certain forced draw also has a centipawn evaluation of zero.
16.2.5.7: Opcode "dm": direct mate fullmove count
The "dm" opcode is used to indicate the number of fullmoves until checkmate is to be delivered by the active color for the indicated position. It always takes a single operand which is a positive integer giving the fullmove count. For example, a position known to be a "mate in three" would have an operation of "dm 3;" to indicate this.
This opcode is intended for use with problem sets composed of positions requiring direct mate answers as solutions.
16.2.5.8: Opcode "draw_accept": accept a draw offer
The opcode "draw_accept" is used to indicate that a draw offer made after the move that lead to the indicated position is accepted by the active player. This opcode takes no operands.
16.2.5.9: Opcode "draw_claim": claim a draw
The opcode "draw_claim" is used to indicate claim by the active player that a draw exists. The draw is claimed because of a third time repetition or because of the fifty move rule or because of insufficient mating material. A supplied move (see the opcode "sm") is also required to appear as part of the same EPD record. The draw_claim opcode takes no operands.
16.2.5.10: Opcode "draw_offer": offer a draw
The opcode "draw_offer" is used to indicate that a draw is offered by the active player. A supplied move (see the opcode "sm") is also required to appear as part of the same EPD record; this move is considered played from the indicated position. The draw_offer opcode takes no operands.
16.2.5.11: Opcode "draw_reject": reject a draw offer
The opcode "draw_reject" is used to indicate that a draw offer made after the move that lead to the indicated position is rejected by the active player. This opcode takes no operands.
16.2.5.12: Opcode "eco": _Encyclopedia of Chess Openings_ opening code
The opcode "eco" is used to associate an opening designation from the _Encyclopedia of Chess Openings_ taxonomy with the indicated position. The opcode takes either a single string operand (the ECO opening name) or no operand at all. If an operand is present, its value is associated with an "ECO" string register of the scanning program. If there is no operand, the ECO string register of the scanning program is set to null.
The usage is similar to that of the "ECO" tag pair of the PGN standard.
16.2.5.13: Opcode "fmvn": fullmove number
The opcode "fmvn" represents the fullmove n umber associated with the position. It always takes a single operand that is the positive integer value of the move number.
This opcode is used to explicitly represent the fullmove number in EPD that is present by default in FEN as the sixth field. Fullmove number information is usually omitted from EPD because it does not affect move generation (commonly needed for EPD-using tasks) but it does affect game notation (commonly needed for FEN-using tasks). Because of the desire for space optimization for large EPD files, fullmove numbers were dropped from EPD's parent FEN. The halfmove clock information was similarly dropped.
16.2.5.14: Opcode "hmvc": halfmove clock
The opcode "hmvc" represents the halfmove clock associated with the position. The halfmove clock of a position is equal to the number of plies since the last pawn move or capture. This information is used to implement the fifty move draw rule. It always takes a single operand that is the non-negative integer value of the halfmove clock.
This opcode is used to explicitly represent the halfmove clock in EPD that is present by default in FEN as the fifth field. Halfmove clock information is usually omitted from EPD because it does not affect move generation (commonly needed for EPD-using tasks) but it does affect game termination issues (commonly needed for FEN-using tasks). Because of the desire for space optimization for large EPD files, halfmove clock values were dropped from EPD's parent FEN. The fullmove number information was similarly dropped.
16.2.5.15: Opcode "id": position identification
The opcode "id" is used to provide a simple identifying label for the indicated position. It takes a single string operand.
This opcode is intended for use with test suites used for measuring chessplaying program strength. An example "id" operand for the seven hundred fifty seventh position of the one thousand one problems in Reinfeld's _1001 Winning Chess Sacrifices and Combinations_ would be "WCSAC.0757" while the fifteenth position in the twenty four problem Bratko-Kopec test suite would have an "id" operand of "BK.15".
16.2.5.16: Opcode "nic": _New In Chess_ opening code
The opcode "nic" is used to associate an opening designation from the _New In Chess_ taxonomy with the indicated position. The opcode takes either a single string operand (the NIC opening name) or no operand at all. If an operand is present, its value is associated with an "NIC" string register of the scanning program. If there is no operand, the NIC string register of the scanning program is set to null.
The usage is similar to that of the "NIC" tag pair of the PGN standard.
16.2.5.17: Opcode "noop": no operation
The "noop" opcode is used to indicate no operation. It takes zero or more operands, each of which may be of any type. The operation involves no processing. It is intended for use by developers for program testing purposes.
16.2.5.18: Opcode "pm": predicted move
The "pm" opcode is used to provide a single predicted move for the indicated position. It has exactly one operand, a move playable from the position. This move is judged by the EPD writer to represent the best move available to the active player.
If a non-empty "pv" (predicted variation) line of play is also present in the same EPD record, the first move of the predicted variation is the same as the predicted move.
The "pm" opcode is intended for use as a general "display hint" mechanism.
16.2.5.19: Opcode "pv": predicted variation
The "pv" opcode is used to provide a predicted variation for the indicated position. It has zero or more operands which represent a sequence of moves playable from the position. This sequence is judged by the EPD writer to represent the best play available.
If a "pm" (predicted move) operation is also present in the same EPD record, the predicted move is the same as the first move of the predicted variation.
16.2.5.20: Opcode "rc": repetition count
The "rc" opcode is used to indicate the number of occurrences of the indicated position. It takes a single, positive integer operand. Any position, including the initial starting position, is considered to have an "rc" value of at least one. A value of three indicates a candidate for a draw claim by the position repetition rule.
16.2.5.21: Opcode "resign": game resignation
The opcode "resign" is used to indicate that the active player has resigned the game. This opcode takes no operands.
16.2.5.22: Opcode "sm": supplied move
The "sm" opcode is used to provide a single supplied move for the indicated position. It has exactly one operand, a move playable from the position. This move is the move to be played from the position.
The "sm" opcode is intended for use to communicate the most recent played move in an active game. It is used to communicate moves between programs in automatic play via a network. This includes correspondence play using e-mail and also programs acting as network front ends to human players.
16.2.5.23: Opcode "tcgs": telecommunication: game selector
The "tcgs" opcode is one of the telecommunication family of opcodes used for games conducted via e-mail and similar means. This opcode takes a single operand that is a positive integer. It is used to select among various games in progress between the same sender and receiver.
16.2.5.24: Opcode "tcri": telecommunication: receiver identification
The "tcri" opcode is one of the telecommunication family of opcodes used for games conducted via e-mail and similar means. This opcode takes two order dependent string operands. The first operand is the e-mail address of the receiver of the EPD record. The second operand is the name of the player (program or human) at the address who is the actual receiver of the EPD record.
16.2.5.25: Opcode "tcsi": telecommunication: sender identification
The "tcsi" opcode is one of the telecommunication family of opcodes used for games conducted via e-mail and similar means. This opcode takes two order dependent string operands. The first operand is the e-mail address of the sender of the EPD record. The second operand is the name of the player (program or human) at the address who is the actual sender of the EPD record.
16.2.5.26: Opcode "v0": variation name (primary, also "v1" though "v9")
The opcode "v0" (lower case letter "v", digit character zero) indicates a top level variation name that applies to the given position. It is the first of ten ranked variation names, each of which has a mnemonic formed from the lower case letter "v" followed by a single decimal digit. Each of these opcodes takes either a single string operand or no operand at all.
This ten member variation name family of opcodes is intended for use as traditional variation names for a complete game or game fragment. The usual processing of these opcodes are as follows:
1) At the beginning of a game (or game fragment), a move sequence scanning program initializes each element of its set of ten variation name string registers to be null.
2) As the EPD record for each position in the game is processed, the variation name operations are interpreted from left to right. (Actually, all operations in n EPD record are interpreted from left to right.) Because operations appear in ASCII order according to their opcode mnemonics, opcode "v0" (if present) will be handled prior to all other opcodes, then opcode "v1" (if present), and so forth until opcode "v9" (if present).
3) The processing of opcode "cN" (0 <= N <= 9) involves two steps. First, all variation name string registers with an index equal to or greater than N are set to null. (This is the set "vN" though "v9".) Second, and only if a string operand is present, the value of the corresponding variation name string register is set equal to the string operand.
17: Alternative chesspiece identifier letters
English language piece names are used to define the letter set for identifying chesspieces in PGN movetext. However, authors of programs which are used only for local presentation or scanning of chess move data may find it convenient to use piece letter codes common in their locales. This is not a problem as long as PGN data that resides in archival storage or that is exchanged among programs still uses the SAN (English) piece letter codes: "PNBRQK".
For the above authors only, a list of alternative piece letter codes are provided:
Language Piece letters (pawn knight bishop rook queen king)
---------- --------------------------------------------------
Czech P J S V D K
Danish B S L T D K
Dutch O P L T D K
English P N B R Q K
Estonian P R O V L K
Finnish P R L T D K
French P C F T D R
German B S L T D K
Hungarian G H F B V K
Icelandic P R B H D K
Italian P C A T D R
Norwegian B S L T D K
Polish P S G W H K
Portuguese P C B T D R
Romanian P C N T D R
Spanish P C A T D R
Swedish B S L T D K
---------- --------------------------------------------------
18: Formal syntax
<PGN-database> ::= <PGN-game> <PGN-database>
<empty>
<PGN-game> ::= <tag-section> <movetext-section>
<tag-section> ::= <tag-pair> <tag-section>
<empty>
<tag-pair> ::= [ <tag-name> <tag-value> ]
<tag-name> ::= <identifier>
<tag-value> ::= <string>
<movetext-section> ::= <element-sequence> <game-termination>
<element-sequence> ::= <element> <element-sequence>
<recursive-variation> <element-sequence>
<empty>
::= <move-number-indication>
<SAN-move>
<numeric-annotation-glyph>
<recursive-variation> ::= ( <element-sequence> )
<game-termination> ::= 1-0
0-1
1/2-1/2
*
<empty> ::=
19: Canonical chess position hash coding
*** This section is under development.
20: Binary representation (PGC)
*** This section is under development.
The binary coded version of PGN is PGC (PGN Game Coding). PGC is a binary representation standard of PGN data designed for the dual goals of storage efficiency and program I/O. A file containing PGC data should have a name with a suffix of ".pgc".
Unlike PGN text files that may have locale dependent representations for newlines, PGC files have data that does not vary due to local processing environment. This means that PGC files may be transferred among systems using general binary file methods.
PGC files should be used only when the use of PGN is impractical due to time and space resource constraints. As the general level of processing capabilities increases, the need for PGC over PGN will decrease. Therefore, implementors are encouraged not to use PGC as the default representation because it is much more difficult (than PGN) to understand without proper software.
PGC data is composed of a sequence of PGC records. Each record is composed of a sequence of one or more bytes. The first byte is the PGN record marker and it specifies the interpretation of the remaining portion of the record. This remaining portion is composed of zero or more PGN record items. Item types include move sequences, move sets, and character strings.
20.1: Bytes, words, and doublewords
At the lowest level, PGC binary data is organized as bytes, words (two contiguous bytes), and doublewords (four contiguous bytes). All eight bits of a byte are used. Longwords (eight contiguous bytes) are not used. Integer values are stored using two's complement representation. Integers may be signed or unsigned depending on context. Multibyte integers are stored in low-endian format with the least significant byte appearing first.
A one byte integer item is called "int-1". A two byte integer item is called "int-2". A four byte integer item is called "int-4".
Characters are stored as bytes using the ISO 8859/1 Latin-1 (ECMA-94) code set. There is no provision for other characters sets or representations.
20.2: Move ordinals
A chess move is represented using a move ordinal. This is a single unsigned byte quantity with values from zero to 255. A move ordinal is interpreted as an index into the list of legal moves from the current position. This list is constructed by generating the legal moves from the current position, assigning SAN ASCII strings to each move, and then sorting these strings in ascending order. Note that a seven bit ordinal, as used by some inferior representation systems, is insufficient as there are some positions that have more than 128 moves available.
Examples: From the initial position, there are twenty moves. Move ordinal 0 corresponds to the SAN move string "Na3"; move ordinal 1 corresponds to "Nc3", move ordinal 4 corresponds to "a3", and move ordinal 19 corresponds to "h4".
Moves can be organized into sequences and sets. A move sequence is an ordered list of moves that are played, one after another from first to last. A move set is a list of moves that are all playable from the current position.
Move sequence data is represented using a length header followed by move ordinal data. The length header is an unsigned integer that may be a byte or a word. The integer gives the number, possibly zero, of following move ordinal bytes. Most move sequences can be represented using just a byte header; these are called "mvseq-1" items. Move sequence data using a word header are called "mvseq-2" items.
Move set data is represented using a length header followed by move ordinal data. The length header is an unsigned integer that is a byte. The integer gives the number, possibly zero, of following move ordinal bytes. All move sets are be represented using just a byte header; these are called "mvset-1" items. (Note the implied restriction that a move set can only have a maximum of 255 of the possible 256 ordinals present at one time.)
20.3: String data
PGC string data is represented using a length header followed by bytes of character data. The length header is an unsigned integer that may be a byte, a word, or a doubleword. The integer gives the number, possibly zero, of following character bytes. Most strings can be represented using just a byte header; these are called "string-1" items. String data using a word header are called "string-2" items and string data using a doubleword header are called "string-4" items. No special ASCII NUL termination byte is required for PGC storage of a string as the length is explicitly given in the item header.
20.4: Marker codes
PGC marker codes are given in hexadecimal format. PGC marker code zero (marker 0x00) is the "noop" marker and carries no meaning. Each additional marker code defined appears in its own subsection below.
20.4.1: Marker 0x01: reduced export format single game
Marker 0x01 is used to indicate a single complete game in reduced export format. This refers to a game that has only the Seven Tag Roster data, played moves, and no annotations or comments. This record type is used as an alternative to the general game data begin/end record pairs described below. The general marker pair (0x05/0x06) is used to help represent game data that can't be adequately represented in reduced export format. There are eight items that follow marker 0x01 to form the "reduced export format single game" record. In order, these are:
1) string-1 (Event tag value)
2) string-1 (Site tag value)
3) string-1 (Date tag value)
4) string-1 (Round tag value)
5) string-1 (White tag value)
6) string-1 (Black tag value)
7) string-1 (Result tag value)
8) mvseq-2 (played moves)
20.4.2: Marker 0x02: tag pair
Marker 0x02 is used to indicate a single tag pair. There are two items that follow marker 0x02 to form the "tag pair" record; in order these are:
1) string-1 (tag pair name)
2) string-1 (tag pair value)
20.4.3: Marker 0x03: short move sequence
Marker 0x03 is used to indicate a short move sequence. There is one item that follows marker 0x03 to form the "short move sequence" record; this is:
1) mvseq-1 (played moves)
20.4.4: Marker 0x04: long move sequence
Marker 0x04 is used to indicate a long move sequence. There is one item that follows marker 0x04 to form the "long move sequence" record; this is:
1) mvseq-2 (played moves)
20.4.5: Marker 0x05: general game data begin
Marker 0x05 is used to indicate the beginning of data for a game. It has no associated items; it is a complete record by itself. Instead, it marks the beginning of PGC records used to describe a game. All records up to the corresponding "general game data end" record are considered to be part of the same game. (PGC record type 0x01, "reduced export format single game", is not permitted to appear within a general game begin/end record pair. The general game construct is to be used as an alternative to record type 0x01 in those cases where the latter is too restrictive to contain the data for a game.)
20.4.6: Marker 0x06: general game data end
Marker 0x06 is used to indicate the end of data for a game. It has no associated items; it is a complete record by itself. Instead, it marks the end of PGC records used to describe a game. All records after the corresponding (and earlier appearing) "general game data begin" record are considered to be part of the same game.
20.4.7: Marker 0x07: simple-nag
Marker 0x07 is used to indicate the presence of a simple NAG (Numeric Annotation Glyph). This is an annotation marker that has only a short type identification and no operands. There is one item that follows marker 0x07 to form the "simple-nag" record; this is:
1) int-1 (unsigned NAG value, from 0 to 255)
20.4.8: Marker 0x08: rav-begin
Marker 0x08 is used to indicate the beginning of an RAV (Recursive Annotation Variation). It has no associated items; it is a complete record by itself. Instead, it marks the beginning of PGC records used to describe a recursive annotation. It is considered an opening bracket for a later rav-end record; the recursive annotation is completely described between the bracket pair. The rav-begin/data/rav-end structures can be nested.
20.4.9: Marker 0x09: rav-end
Marker 0x09 is used to indicate the end of an RAV (Recursive Annotation Variation). It has no associated items; it is a complete record by itself. Instead, it marks the end of PGC records used to describe a recursive annotation. It is considered a closing bracket for an earlier rav-begin record; the recursive annotation is completely described between the bracket pair. The rav-begin/data/rav-end structures can be nested.
20.4.10: Marker 0x0a: escape-string
Marker 0x0a is used to indicate the presence of an escape string. This is a string represented by the use of the percent sign ("%") escape mechanism in PGN. The data that is escaped is the sequence of characters immediately follwoing the percent sign up to but not including the terminating newline. As is the case with the PGN percent sign escape, the use of a PGC escape-string record is limited to use for non-archival data. There is one item that follows marker 0x0a to form the "escape-string" record; this is the string data being escaped:
1) string-2 (escaped string data)
21: E-mail correspondence usage
Standard: EOF
Back to Top
Order Now! PGN Files Contact Us PGN Mentor Home
Copyright © 2000 64 Squares. All rights reserved.
