Standard: Portable Game Notation Specification and Implementation Guide
(Supplement)
Revised: 8 September 2001
Status: Final draft
Authors: Alan Cowderoy (Palamede), Ben Bulsink (DGT Projects), Andrew Templeton
(Palamede/Palview), Eric Bentzen (Enpassant.dk, Palamede), Mathias Feist
(Chessbase), Victor Zakharov (Chess Assistant).
Contact: alan@cowderoy.com
1. Introduction
PGNs combination of a formal specification for computer use with easy
readability and manipulation by humans has firmly established it as the data
format of choice for representing chess games. This is a major success and a
tribute to the quality of the work done by the original authors.
Steven Edwards, the author, appears unfortunately to be no longer involved with
PGN and there is now no defined means of arbitrating and implementing proposed
changes. There is also a huge body of software which implements the current
standard and would break in various ways if it were changed.
At the same time the increased use of DGT boards in major tournaments for the
retransmission of live games has rendered one of the features that was planned
for PGN but never implemented increasingly important, namely the possibility of
encoding time information relating to each move.
Without the possibility of encoding time information in PGN its usefulness in
the retransmission of live games is significantly weakened forcing developpers
either to resort to proprietary formats or to break the standard.
Computer chess program authors are also now finding that they have no accepted
way to encode such simple and recognised concepts as numeric position
evaluations or search depth.
Given this situation some have understandably set about defining wholly new XML
based definitions for encoding chess games. While this work is interesting, as
of today there is no widely accepted and supported XML schema.
It thus seems important to us to attempt an incremental improvement to PGN
intended to eliminate the functional weaknesses described above.
This document proposes an extension to PGN designed to offer an immediate 'work
around' solution to the problems outlined above.
2. Design aims
2.1 The enhancements must not break the existing standard.
This rules out new syntactical elements. Steve Edwards himself proposed a format
(BIF) that would have resolved these problems but it was never implemented and
doing so now would break large quantities of software.
2.2 The enhancements should maintain the ease of use and legibility so
characteristic of PGN.
This rules out very precise but possibly more computer readable formats in
favour of clearer human readable ones.
2.3 If new command structures are to be introduced they should be specified in
such a way that they are usable for other extensions if needed.
The intention here is to provide a generalised syntax that will enable other
extensions rather than only solving one particular problem (time handling in our
case).
3. Proposals
3.1 Introduction
The only way to extend the syntax without breaking the standard is to embed the
new command syntax into PGN comments. This is a kludge and such an obvious one
that it was already suggested when Steve Edwards proposed the BIF format in
1996. It is still the only option available.
Apart from a general command syntax we propose several specific commands
designed for the handling of time information.
We also propose the addition of a tag to the header to handle the state of the
"running clock" where the game is being transmitted live and two other optional
tags designed to handle special cases where the clock start times are needed.
These additions are not problematic as the standard concedes the possibility of
adding new tags to the header (outside the mandatory seven tag roster)
Interpreting time information for a game is either difficult or impossible if
the time controls in force are not known. PGN has a TimeControl tag for this and
it should be regarded as mandatory when time information is to be embedded into
the pgn.
3.2 A generalised format for embedding commands in comments.
3.2.1 Position
An embedded command may occur at any position in a standard PGN comment, ie
between { } .
For example:
{Optional leading comments [%clk 1:05:23] optional trailing comments} where
[%clk 1:05:23] is the embedded command string.
3.2.2 Structure
The command string is structured as follows.
A leading tag of [%
A command name consisting of one or more alphanumeric characters.
A space character.
Either a single parameter or a comma delimited list of parameter values.
A closing tag of ]
For example:
[%clk 1:05:23]
3.2.3 Opening delimiter
The characters [% are redefined to indicate the start of a command sequence when
found in between pgn comment tags.
As all ASCII characters are legal in a comment string it is not possible to rely
on any single character as an unambiguous opening delimiter. We have chosen to
use [%. While this also could technicaly occur in some other context it seems
highly unlikely.
3.2.3 Commands
Command names start immediately after the [%.
They consist of one or more alphanumeric characters
They are terminated by the first space character encountered.
We are *not* proposing any fixed canonical list of commands. The idea is to
describe a generalised command syntax, not to impose a particular set of
commands.
We *are* proposing a set of commands to deal with time handling. "clk" in the
example above is the proposed command name for recording move times. See section
4 for the detailed specification of this and other time related commands.
In general software encountering an embedded command it does not understand
should take no special action and pass the string through unchanged as part of
the comment.
For display purposes only presentation software, such as pgn readers, should by
default strip out all commands before display in order to improve legibility.
3.2.4 Parameters
This parameter syntax is based on the epd opcode syntax described at 16.2.4 of
the pgn spec.
A command is followed by a single space and then either by a single operand or
by a comma separated list of operands.
An operand is either:
i) a set containing any ascii characters except the comma and right hand square
bracket
or
ii) a double quoted string containing a set of any ascii characters except the
double quote.
For instance:
[%command 1:45:12,Nf6,"very interesting, but wrong"]
This command has four operands, a time value, a san move value and a double
quote delimitted string. Note that the quote delimitted string may contain
commas.
Commas are illegal in non quote delimitted strings because the comma serves as
the operand list separator.
Right hand square brackets are illegal in non quote delimitted strings because
they terminate both the last operand and the command.
We have thus departed from the epd opcode specification in two ways:
i) The operand list is separated using a comma rather than a space.
ii) Space characters are allowed in non quote delimited operands
So it is possible to pass a full FEN string as an unquoted operand as in the
example below.
[%command "very tense start to the
game",4r1k1/pp1b2r1/2n1pq1p/3p2pP/2pP2B1/P1P1Q3/2P2PPB/R4RK1 w - - 0 1,e4,d4]
This command has four operands, the first is a double quote delimitted string,
the second is a FEN, the third is e4 and the fourth is d4.
3.2.5 Terminator
The command is terminated by a single ] character.
3.2.6 Multiple commands.
A single comment tag may contain multiple embedded commands.
For instance:
{[%clk 0:00:07][%eval -6.05] White is toast}
4. Time handling commands.
4.1 Introduction.
We propose the following commands for time handling The first is the command
that DGT boards will be using to transmit times via pgn.
The other commands are optional and cover times that can be derived from the
clock time. They are technicaly redundant but may be usefull for highlighting
aspects of the game and the players use of time.
All these commands take one and only one parameter which is a time value in the
format h:mm:ss (except for the mct command which requires hh:mm:ss)
The comments containing the embedded commands are to be taken as referring to
the move immediately preceding them.
4.2 The clk command.
{[%clk 1:55:21]}
This is the time displayed on the players clock. It represents the time
remaining to the next time control. It is proposed that future versions of
software producing pgn from games played on DGT boards include this command
after every move.
The clk command is intended for the *automatic* recording of time values by
digital clock/board combinations. It is not normaly intended for use with
mechanical clocks which show a clock time rather than the time remaining to the
next control.
4.3 Elapsed Game Time : the egt command
{[%egt 1:25:42]}
The elapsed time that a player has used for all moves in the game up to that
point.
Takes one parameter in the format h:mm:ss
4.4 Elapsed Move Time : the emt command
{[%emt 0:05:42]}
The elapsed time that a player used for the commented move.
Takes one parameter in the format h:mm:ss
4.5 Mechanical Clock Time : the mct command
{[%mct 17:10:42]}
The time actualy displayed on a mechanical clock. Notice that here the time
format is hh:mm:ss.
5. The "Running Clock"
The syntax described above allows us to encode a move time for a *completed
move*. This is all well and good but during transmission of a live game it can
also be interesting to know the state of the clock of the player whose turn it
is to move *but who has not yet done so*.
5.1 The Clock tag
We propose that this information should be encoded in a new header tag.
[Clock "B/0:45:56"]
As only one clock is running at a time only one tag is necessary.
In the example above Blacks clock is running and is currently showing the time
indicated by the string following the /.
Clock is the name of the tag.
It is followed by a string constructed as follows:
The first character is either "W" (whites clock is running), "B" (blacks clock
is running) or "N" (the clocks are stopped).
This information is technicaly redundant as it could be calculated by looking at
which side last moved. Encoding it here avoids this calculation and also covers
the situation where a player forgets to switch the clocks. It also allows us to
cover the admittedly rare case where the clocks are stopped.
The second character is a "/" seperator.
The rest of the string is a time in the format h:mm:ss which indicates the
currently displayed clock time of the running clock. As for the clk command this
represents the remaining time to the next time control.
6. Clock Start Time.
6.1 Introduction.
Two optional tags are proposed to record the clock setting at the start of the
play.
While it may be helpfull to record normal clock start values here (as is done in
the example below) they are mainly intended to cover the case where a game is
adjourned and the displayed clock times at start of play are thus non standard.
eg.
[WhiteClock "1:07:00"]
[BlackClock "0:56:00"]
7. As explained above the existing pgn tag [TimeControl] (cf 9.6 and following
of the standard) should be regarded as mandatory when move times are supplied.
Clearly when manipulating time information about a game details of the time
controls in use are vital.
8. Example game.
[Event "?"]
[Site "Madrid"]
[Date "1995.??.??"]
[White "Beliavsky, A "]
[Black "Timman, J "]
[Result "1-0"]
[ECO "E35"]
[Round "2"]
[TimeControl "40/7200:3600"]
[WhiteClock "2:00:00"]
[BlackClock "2:00:00"]
[Clock "W/1:34:56"]
1. d4 {[%clk 1:59:01]} Nf6 {[%clk 1:59:32] Timman hesitates slightly} 2. c4
{[%clk 1:58:00]} e6 {[%clk 1:57:01]} 3. Nc3 {[%clk 1:37:00] Beliavsky clearly
suprised here takes a full [%emt 0:20:00] on this move} Bb4 {[%clk 1:54:25]}
Game notes:
8.1. The time control is specified as 40 moves in two hours and then one hour to
finish. This tag must be specified in order to permit calculation of such
information as elapsed time since start of game. It is also particularly
important that it be specified when fischer or bronstein time controls are used.
8.2. In the example we have given the White and BlackClock tags but in this case
this was redundant as the clocks were set as normal to show that two hours
remained to the first time control. If the White and BlackClock tags are absent
start times should be derived from the TimeControl tag and/or the Time tag,
where they are specified they take precedence.
8.3. The Clock tag, which is only relevant during live transmission of a game,
here shows that it is whites turn to move and that he/she has 1 hour 34 minutes
and 56 seconds remaining on their clock.
8.4. PGN generated directly from DGT boards will have a clk command like the one
following the first move after *all* subsequent moves.
8.5. In this example we imagine that the pgn has been further edited to include
additional text comments and commands (cf the %emt command after whites third
move.)
8.6. Notice that commands can appear at any point inside comments and that there
may be multiple commands in a single comment.
8.7. The Beliavsky/Timman game is real, all the rest is pure invention.
9 Authors websites:
DGT Projects: http://www.dgtprojects.com/
Chess Base: http://www.chessbase.com/
Chess Assistant: http://www.chessassistant.com/
Palview: http://www.enpassant.dk/chess/palview/
10. Thanks
Many thanks to Axel Fritz and Robert Ericsson
*additional notes:
1. Cf Steve Edwards discussion of the planned implementation of BIF format here:
http://groups.google.com/groups?hl=en&safe;=off=1&th;=1fe06718d5ec89a5,20&seekm;
=4psfnl%24i5m%40darkstar.UCSC.EDU
We ruled out the use of < > as delimiters specified in the BIF format because if
this syntax is pasted into an html document then parsers will ignore the
contents as an unrecognised tag. This is not the effect we want.
2. While the seven tag roster is very precisely specified the PGN specification
does envisage the specification of new optional tags. We have taken advantage of
this to specify several new tags.
Note also that there is already a [Time] tag - this denotes the time of the game
start (and not anything else).
3. For reference the current pgn standard is here
http://www.clark.net/pub/pribut/standard.txt