ChessLab

Play, learn, explore chess
Home | Source

ChessLab is a desktop application for chess players and chess enthusiasts.

It can help you:

browse through game collections and replay games;
keep a record of your own games;
maintain an opening repertoire;
evaluate and analyse positions;
play chess against the computer;
solve puzzles;
look at a (virtual) 3D chessboard.

ChessLab is written in Common Lisp and uses the Barium toolkit for its GUI. As such, it should run on any UNIX-like Free/Libre/Open Source operating system, including Linux and members of the BSD family.

ChessLab is released to the public under the terms of the GNU General Public License v3.

Features

Open, display and edit PGN game collections
Standard algebraic chess notation
- Maintained by the program. Just make moves on the board.
Move table (tree view), useful for openings study
Board editor for setting up arbitrary initial positions
Graphical annotations:
- Mark squares with circles
- Draw arrows
- Choose from four different colors
Notes/annotations for each move
UCI engine integration:
- Analyse and evaluate positions
- Play against the engine
- Have two different engines play against each other
- Tested with Stockfish and Fairy-Stockfish
Visual indication of last move and check
Maintain and display material difference
Selectable board surface and piece set
3D chessboard view

ChessLab is, at its core, a PGN viewer and editor with UCI integration. It should work fine for studying individual games or handling limited-size game collections.

However, the database aspects of ChessLab are currently undeveloped, which make it unsuitable for managing huge databases of games. There is no facility for querying games based on e.g., player, opening, etc. Such features might or might not get added in the future.

Getting ChessLab

To run ChessLab, you need to have a Common Lisp implementation installed. The recommended choices are SBCL and CCL. ChessLab will possibly also work, but is not tested, with other implementations.

To manage Common Lisp software packages, we recommend using the QuickLisp library manager. Set it up on your CL implementation according to the linked instructions.
Clone the source repository of Barium (the GUI library) and Chesslab to a location of your choice. For example:
```
~$ cd src
~/src$ git clone https://git.hq.sig7.se/barium.git
~/src$ git clone https://git.hq.sig7.se/chesslab.git
```
Stick to the master branch (the default) unless you know what you are doing.

Create symlinks to them from ~/quicklisp/local-projects:

~/src$ cd ~/quicklisp/local-projects/
~/quicklisp/local-projects$ ln -s ~/src/barium .
~/quicklisp/local-projects$ ln -s ~/src/chesslab .

Now you can load ChessLab in the Lisp REPL, and run it:
```
$ sbcl
* (ql:quickload :chesslab)
```
First time you do this, you might find yourself in the Lisp debugger invoked by QUICKLISP-CLIENT:SYSTEM-NOT-FOUND. Note the restart called REGISTER-LOCAL-PROJECTS. Select it and you should be fine.

Now you can start the application:
```
* (chesslab:gui)
```
For a more convenient installation, build an executable Lisp image using the script build-sbcl.sh (for SBCL) or build-ccl.sh (for CCL). The resulting executable chesslab.sbcl (or chesslab.ccl) can be renamed to chesslab and copied to a system-wide location, e.g., /usr/local/bin/. For example:
```
~/src$ cd chesslab
~/src/chesslab$ ./build-sbcl.sh
~/src/chesslab$ doas cp chesslab.sbcl /usr/local/bin/chesslab
```
The executable accepts a PGN pathname as its first argument. So, after the executable is installed as above, you can open your PGN game collection directly:
```
~/doc/chess$ chesslab my-games.pgn
```

Usage tips

Discovering features and hotkeys

ChessLab is mostly menu-driven: most of its features are present in one of the menus. Do click around and try them out! Many of the available operations can also be invoked via hotkeys. This is indicated in the menu item. For example, the board can be flipped via Control+f, notated as C-f.

Moving back and forth through the moves of a game is done with the left and right arrow keys as well as the mousewheel; both methods work unless locally bound to something else within a widget.

Even complicated recursive variations can be navigated fairly efficiently via hotkeys. You can also click on any move in the notation to jump to the corresponding position.

Entering moves

Entering new moves is possible in any position (unless it's a mate): just click on the piece with the left mouse button. All possible (legal) target squares will be indicated with a dot in them.

Click on the desired target to complete the move. For pawn promotion, a popup will appear after the target square is selected so you can choose the promotion piece to complete the move. The notation and move table will be updated with the newly added move.

Graphical marks

In any position, graphical marks can be added to the board with the right mouse button. A single click will put a circle on the square; clicking and dragging the mouse to a different square will draw an arrow. A different color can be selected by holding one of the modifiers Shift, Control or Alt while creating the mark. The object can be deleted by repeating the same action that created it. A single left click on the board or moving the game to a different position will erase all marks.

3D View

The 3D board view opens in a separate window so you can move and resize it freely. To change the view perspective, click and drag with the left button. This will allow you to rotate the view along the X and Y axes in a (hopefully) intuitive manner. Zooming in and out is possible with the mouse scrollwheel.

Arbitrary initial position

In an empty game with no moves added yet, you can edit the initial position via opening the position editor (select Board → Edit position… in the menu, or bring it up via the associated hotkey).

The position editor is primarily keyboard-driven, augmented by the controls on the right. It is recommended to begin with the position on the board, and then adjust the parameters as needed.

Board editing is based on the FEN notation - keying in the piece placement part of a FEN will set it up on the board. However, the editor can also be used in a more flexible manner. The below functions can be freely exercised in any order:

Move the current square by clicking on the board or using the arrow keys.
Insert a piece by clicking its button, or pressing the corresponding key. The current square is advanced to the right.
Number keys 1-8 erase that many squares and move right, within a single rank.
Backspace erases and moves backward; delete erases in place.
The slash key ('/') moves to the start of the next rank.

A separate help window with the above usage summary can be opened via clicking on the '?' button.

The position editor gives human-readable feedback whenever it contains an invalid position (such as a missing king, inactive side in check, bogus castling rights, etc). Such positions can be entered into ChessLab, but you won't be able to analyse them via the engine.

After clicking Apply, you should see the correct position on the main chessboard as well. Close the position editor and you can start analysing, adding moves, notes and board marks:

Getting PGNs

Apart from creating your own PGNs by hand (for example, working on your opening repertoire) you can download PGN files from various sources.

Complete game collections of high-level chess players can be downloaded from:
https://www.pgnmentor.com/files.html
Opening a large PGN (containing several thousands of games) may take a few seconds, so please be patient.
If you play chess online, your platform most likely offers an option to download (a selection of) your own games as a PGN file. For example, Lichess has an Export games option in the user profile. The downloaded PGN works nicely with ChessLab.

Feedback

You are welcome to contact the author with feedback, questions or comments regarding ChessLab. Please note, however, that the program comes with ABSOLUTELY NO WARRANTY and the fact that you are able to send email to its author does not constitute a support contract.