PGN_Support

PGN and FEN standards support

pgn4web mostly supports the PGN (Portable Game Notation) standard for chess games notation. For more information about the PGN standard you can read the PGN entry in wikipedia.

The general design principle is for pgn4web to try as much as possible to automatically recover from minor errors in the PGN data and only stop the game replay after unrecoverable errors.

Following PGN tags are parsed and used: Event, Site, Date, Round, White, Black, Result, SetUp and FEN. The PGN tags WhiteClock and BlackClock are also used, but only for live game broadcasting. A customization function is available to parse any other header tags.

pgn4web manages common mistakes in PGN files, trying as much as possible to avoid triggering exceptions. For instance, following exceptions are tolerated:

• use of the FEN tag without SetUp tag: SetUp assumed set to 1 if FEN is present
• incomplete FEN strings where only the piece positions is assigned: all remaining parameters assigned to defaults
• missing tags from the seven mandatory tags: assumed as ?
• any string content accepted for any tag: no tag validation

Failure to load PGN data, incorrect PGN games or incorrect FEN strings generate exceptions: pgn4web signals those by flashing unintrusively the chessboard at regular intervals. Please refer to the debugging page for more information and for an example.

about ambiguous moves

Ambiguous moves are errors in the PGN data where not enough information is provided to determine the intended unique move. For example in the following sequence the move 3. Nd2 is ambiguous because both the knights from b1 and f3 could move to d2:

1. d4 d5 2. Nf3 Nf6 3. Nd2

The ambiguous move error 3. Nd2 should be replaced by either 3. Nbd2 or 3. Nfd2.

When encountering an ambiguous move pgn4web first flags the error with an alert message; rather than stopping the game replay after the error, pgn4web then guesses which of the possible moves was intended and continues the replay; if the guess was correct, the game will replay in full; if the guess was not correct, it's possible that an invalid move alert will follow later and stop the game replay; it should be noted that the game continuation after an ambiguous move alert it's never fully reliable.

about special charachters such as ½ ¿ ß â è õ

Special characters, such as symbols (such as ½ ¿ ß) and accented letters (such as â è õ ü), can appear in PGN files as comments or as part of the header values; in order for pgn4web to display those characters correctly, the PGN file should be saved in unicode UTF-8 format.

If you are forced to use PGN files encoded in a different format, you might try patching manually the pgn4web.js file, searching for "// patch: pgn encoding" and following instructions.

about entering a game fragment starting from a given position

A frequently asked question is how to enter a chess position without necessarily having the full game text. pgn4web supports the PGN tag FEN that allows modifying the starting position by providing a FEN (Forsyth-Edwards Notation) string; for example:

[Event "white to move"]
[FEN "rn2r1k1/ppq2pb1/2pp2pp/8/2PQn1b1/1PN2NP1/PB3PBP/3RR1K1 w - - 0 17"]
17.Qxg7 Kxg7 18.Nd5 Kf8 19.Nxc7

about Chess960

pgn4web supports Chess960 (a.k.a. Fischer random chess) by understanding both the X-FEN and the Shredder-FEN extensions to the FEN notation; pgn4web generates X-FEN strings when clicking the associated shortcut square.

See this example showing the 2006 rapid Chess960 World Championship.

exceptions and limitations

Notable exceptions and limitations of pgn4web PGN support:

• only pieces initials in the English language are supported, the use of alternative languages as specified by the PGN standard is not supported (pgn4web can however display chess moves text using figurine notation, so the language issue should not be much of a problem, just make sure your chess software produces PGN data with English pieces initials).

compliance to proposed supplement to the standard

pgn4web also follows a set of proposed extensions to the PGN standard, more specifically:

• understands the [%clk 1:59:58] tag in the PGN comment section as the clock time after each move
• understands the PGN tags [WhiteClock "2:00:00"] and [BlackClock "2:00:00"] as the clock times at the beginning of the game
• understands the PGN tag [Clock "W/1:59:59"] as the clock time of the running clock
• allows parsing of generic comment tags using the function customPgnCommentTag()

null moves support

pgn4web supports PGN null moves in the -- notation (used by a number of chess tools like scid and chessbase), such as in 1. e4 -- 2. d4

Note the equivalent <> nullmove notation is currently not supported by pgn4web.

continuations support

pgn4web supports PGN continuations (defined as variations where the last move played before the variation is not taken back prior to the start of the variation moves) in the (* notation, such as in 1. e4 (* 1... d5 2. exd5) 2... e5

in case you have a PGN that pgn4web fails parsing

Please email me for review any PGN file that pgn4web fails parsing correctly.