Chess puzzle book generator

Last modification on

This was a christmas hack for fun and non-profit. I wanted to write a chess puzzle book generator. Inspired by 1001 Deadly Checkmates by John Nunn, ISBN-13: 978-1906454258 and similar puzzle books.

Example output

Terminal version:

curl -s 'https://codemadness.org/downloads/puzzles/index.vt' | less -R

I may or may not periodially update this page :)

Time flies (since Christmas), here is a valentine edition with attraction puzzles (not only checkmates) using the red "love" theme. It is optimized for his and her pleasure:

https://codemadness.org/downloads/puzzles-valentine/

Clone

git clone git://git.codemadness.org/chess-puzzles

Browse

You can browse the source-code at:

Quick overview of how it works

The generate.sh shellscript generates the output and files for the puzzles.

The puzzles used are from the lichess.org puzzle database: https://database.lichess.org/#puzzles

This database is a big CSV file containing the initial board state in the Forsyth-Edwards Notation (FEN) format and the moves in Universal Chess Interface (UCI) format. Each line contains the board state and the initial and solution moves.

The generated index page is a HTML page, it lists the puzzles. Each puzzle on this page is an SVG image. This scalable image format looks good in all resolutions.

Open puzzle data

Lichess is an open-source and gratis website to play on-line chess. There are no paid levels to unlock features. All the software hosting Lichess is open-source and anyone can register and play chess on it for free. Most of the data about the games played is also open.

However, the website depends on your donations or contributions. If you can, please do so.

generate.sh

Reads puzzles from the database and shuffle them. Do some rough sorting and categorization based on difficulty and assign score points.

The random shuffling is done using a hard-coded random seed. This means on the same machine with the same puzzle database it will regenerate the same sequence of random puzzles in a deterministic manner.

It outputs HTML, with support for CSS dark mode and does not require Javascript. It includes a plain-text listing of the solutions in PGN notation for the puzzles. It also outputs .vt files suitable for the terminal. It uses unicode symbols for the chess pieces and RGB color sequence for the board theme

fen.c

This is a program written in C to read and parse the board state in FEN format and read the UCI moves. It can output to various formats.

See the man page for detailed usage information.

fen.c supports the following output formats:

  • ascii - very simple ASCII mode.
  • fen - output FEN of the board state (from FEN and optional played moves).
  • pgn - Portable Game Notation.
  • speak - mode to output a description of the moves in words.
  • SVG - Scalable Vector Graphics image.
  • tty - Terminal output with some markup using escape codes.

fen.c can also run in CGI mode. This can be used on a HTTP server:

Position from game: Rene Letelier Martner - Robert James Fischer, 1960-10-24

Terminal output:

curl -s 'https://codemadness.org/onlyfens?moves=e2e4%20e7e5&output=tty'

Support for Dutch notated PGN and output

For pgn and "speak mode" it has an option to output Dutch notated PGN or speech too.

For example:

  • Queen = Dame (Q -> D), translated: lady.
  • Rook = Toren (R -> T), translated: tower.
  • Bishop = Loper (B -> L), translated: walker.
  • Knight = Paard (N -> P), translated: horse.

Example script to stream games from Lichess

There is an included example script that can stream Lichess games to the terminal. It uses the Lichess API. It will display the board using terminal escape codes. The games are automatically annotated with PGN notation and with text how a human would say the notation. This can also be piped to a speech synthesizer like espeak as audio.

pgn-extract is a useful tool to convert Portable Game Notation (PGN) to Universal Chess Interface (UCI) moves (or do many other useful chess related things!).

Example script to generate an animated gif from PGN

Theres also an example script included that can generate an animated gif from PGN using ffmpeg.

It creates an optimal color palette from the input images and generates an optimized animated gif. The last move (typically some checkmate) is displayed slightly longer.

References and chess related links