DIR <- Back
# Chess puzzle book generator
Last modification on 2025-05-03
This was a christmas hack for fun and non-profit.
I wanted to write a chess puzzle book generator.
HTML Inspired by »1001 Deadly Checkmates by John Nunn, ISBN-13: 978-1906454258«,
HTML »Steps Method workbooks« and other puzzle books.
# Example output
HTML * English version: »https://codemadness.org/downloads/puzzles/«
HTML * Dutch version: »https://hiltjo.nl/puzzles/«
Terminal version:
curl -s 'https://codemadness.org/downloads/puzzles/index.vt' | less -R
I may or may not periodially update this page :)
HTML 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:
HTML https://codemadness.org/downloads/puzzles-valentine/
## Clone
git clone git://git.codemadness.org/chess-puzzles
## Browse
You can browse the source-code at:
HTML * https://git.codemadness.org/chess-puzzles/
DIR * gopher://codemadness.org/1/git/chess-puzzles
# 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:
HTML 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
HTML 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,
HTML 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.
HTML 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.
HTML * »fen« - output FEN of the board state (from FEN and optional played moves).
HTML * »pgn« - Portable Game Notation.
* speak - mode to output a description of the moves in words.
HTML * »SVG« - Scalable Vector Graphics image.
* tty - Terminal output with some markup using escape codes.
HTML fen.c can also run in »CGI« mode. This can be used on a HTTP server:
HTML Position from game: Rene Letelier Martner - Robert James Fischer, 1960-10-24
HTML * https://codemadness.org/onlyfens
HTML * https://codemadness.org/onlyfens?fen=6k1/ppq3bp/2n2np1/5p2/2P2P2/4rBN1/PP3K1P/RQ6%20w%20-%20-%200%2023&moves=f2e3&flip=1
HTML * https://codemadness.org/onlyfens?moves=e2e4%20e7e5&flip=1&theme=green&output=svg
HTML * https://codemadness.org/onlyfens?moves=e2e4%20e7e5&output=pgn
HTML * https://codemadness.org/onlyfens?moves=e2e4%20e7e5&output=speak
HTML * https://codemadness.org/onlyfens?moves=e2e4%20e7e5&output=ascii
HTML * https://codemadness.org/onlyfens?moves=e2e4%20e7e5&output=fen
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
HTML 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
HTML 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
HTML 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
* chess-puzzles source-code:
HTML https://www.codemadness.org/git/chess-puzzles/file/README.html
* Lichess FEN puzzle database:
HTML https://database.lichess.org/#puzzles
* lichess.org:
HTML https://lichess.org/
* SVG of the individual pieces used in fen.c:
HTML https://github.com/lichess-org/lila/tree/master/public/piece/cburnett
* pgn-extract:
A great multi-purpose PGN manipulation program with many options:
HTML https://www.cs.kent.ac.uk/people/staff/djb/pgn-extract/
An example to convert PGN games to UCI moves:
`pgn-extract --notags -Wuc`
* Lichess API:
HTML https://lichess.org/api
* Stockfish:
Strong open-source chess engine and analysis tool:
HTML https://stockfishchess.org/