Python Easy Chess GUI

A Chess GUI based from Python using FreeSimpleGUI and Python-Chess modules. Users can also load a chess engine and play with it. This program is based on a demo chess against ai from PySimpleGUI.

A. Requirements

If you want to run from the python source the following are required or see the installation section below.

• Python 3.7 and up
• Python-chess v0.28.0 and up
• FreeSimpleGUI 5.0.0 and up
• Pyperclip
• Download this repo

Or you can just download the executable file along with other files such as book and images.

B. Features

1. Save games to repertoire pgn files

2. Install uci engine of your choice

2.1 It is recommended to configure the engine setting after installation

Configure engine via Engine->Manage->Edit, select engine and press modify.

3. Need book assistance? Right-click on BOOK 2 and press show

4. Need what engine adviser will think about the position? Right-click on Adviser and press start

5. Replay game with engine analysis in Review Mode

C. Installation

1. If you want to run from the source code

• Python Easy Chess GUI
  Download the files including the Images, Engines and Book directories. You can use your favorite uci chess engine like stockfish by copying it into the engines dir.
• Python 3
  https://www.python.org/downloads/
• Python-Chess
  https://github.com/niklasf/python-chess
  pip install python-chess
• FreeSimpleGUI
  https://github.com/spyoungtech/FreeSimpleGUI
  pip install FreeSimpleGUI
• Pyperclip
  https://github.com/asweigart/pyperclip
  pip install pyperclip

1. If you want to run from the exe

• Download the exe file from the release link

Note

If you are on linux be sure to give permission to uci engine with: chmod +x uci_engine_fn.

D. How to use

This is the detailed manual. Inside the app, the Help menu gives short, task-focused versions of these topics (adapted to the current mode), and Help → Online Help opens this page.

Contents

• Modes
• Start the GUI
• Play a game
• Engine setup and management
• Review mode — replay and analyse
• Settings / Game
• Opponent book
• Show / hide info panels
• Board appearance
• Files the app writes

Modes

The GUI opens directly in Play mode, ready to play. There are two modes:

• Play — the default; play a game against the opponent engine. All setup (engine, time, book, settings, board colors) is done from the same menubar before a game starts; the setup menu items are grayed out while a game is running and come back after Game → New or when the game ends.
• Review — step through a saved game with optional engine analysis and threat. Enter with Mode → Review (before a game starts), leave with Mode → Play.

Start the GUI

• From source: python python_easy_chess_gui.py
• Or run the prebuilt .exe.

Play a game

• As white: just click the piece and the destination square (or drag the piece). Your first move starts the game and the clocks.
• As black: press Engine → Go before making a move — the engine takes White and moves first, and the board flips so Black is at the bottom. Game → New returns you to White.
• Flip the board: Board → Flip, at any time — before, during or after a game. The game is not affected.
• Force the engine to move now: Engine → Move Now.
• Start a new game: Game → New.
• Paste a position (FEN): Game → Paste FEN (before a game starts). If the side to move is not yours, press Engine → Go.
• End a game manually: Game → Resign, User Wins, or User Draws.
• Save games: every game auto-saves to pecg_auto_save_games.pgn. During a game the Game menu also offers Save to My Games and Save to White / Black Repertoire.
• Time control: Settings → Time → User (your clock) and Settings → Time → Engine (opponent clock), set before a game starts.

Engine setup and management

Only UCI engines are supported. All engine actions are available before a game starts.

• Install: Engine → Manage → Install, press Add and locate the engine executable. On Linux make it executable first: chmod +x your_engine.
• Configure options: Engine → Manage → Edit, select the engine and press Modify (set Hash, Threads, etc.). Recommended right after installing.
• Delete: Engine → Manage → Delete.
• Set the opponent: Engine → Set Engine Opponent — the engine you play against.
• Set the adviser: Engine → Set Engine Adviser. During a game, right-click the Adviser label and press Start for a suggested move and score.
• Set the analysis engine: Engine → Set Engine Analysis — used by the Analysis button in Review mode.
• Set the threat engine: Engine → Set Engine Threat — used by the Threat button in Review mode.
• Search depth: Engine → Set Depth caps the depth of the playing and adviser engines. Review analysis/threat are limited by time instead (see Settings).

Review mode — replay and analyse

• Open a game: Mode → Review, choose a PGN file (or pick one from the Recent drop-down), then select a game and press OK — or double-click it. Click a column heading (White, Black, Result, Date, Event) to sort the game list.
• Navigate: use First / Previous / Next / Last below the board, the Left / Right arrow keys (Home / End for first/last position), or click a move in the move list to jump to that position.
• Analysis: press the Analysis button to evaluate the current position (multi-line principal variations). The search stops after the analysis time (default 60s) and restarts automatically when you change position.
• Threat: press the Threat button to see what the opponent would play if the side to move passed (a null move). It is unavailable when the side to move is in check, and stops after the threat time (default 30s).
• Auto-Analyze Game: Game → Auto-Analyze Game annotates every move with the engine and time per move you choose. Each move gets an evaluation comment; bad moves are marked ?! ? ??. When the engine's move is at least 25cp better than the game move (and its own score stays within ±300cp), the better line is replayed engine-vs-engine for up to 5 plies and added as a Better is variation labeled with the evaluation after the line's last move. The annotated game is appended to pecg_analyzed_games.pgn and replaces the current review game. Game → Cancel Analysis stops early.
• Flip the board: Board → Flip within Review mode.

Both analysis and threat run their engines for at most their configured time and then go idle, so they do not keep the CPU busy after a position has been evaluated.

Settings / Game

Open with Settings → General (before a game starts). All values are saved to pecg_settings.json and restored on the next startup.

• Save time left in game notation — adds [%clk h:mm:ss] move comments, shown in the move list and saved to the PGN.
• Adjudicate game on time forfeit — ends the game when a player runs out of time.
• Review analysis time (sec) — time cap for the Review Analysis engine. Default 60, range 1–3600.
• Review threat time (sec) — time cap for the Review Threat engine. Default 30, range 1–3600.

Opponent book

• Settings → Set Book (before a game starts) sets the opponent's polyglot book. It is named pecg_book.bin and lives in the Book folder. Build your own polyglot book, name it pecg_book.bin and replace the default to change it.

Show / hide info panels

These work in Play mode by right-clicking the panel's label:

• Engine search info: right-click Opponent Search Info → Show / Hide.
• Opening books: right-click BOOK 1 or BOOK 2 → Show / Hide.

Board appearance

• Flip: Board → Flip, at any time — including while a game is running or the engine is thinking. The game is not affected.
• Size: Board → Size picks a board scale preset — Small (360), Medium (480), Large (600) or X-Large (720) pixels — at any time, like Flip. On first start the largest board that fits the screen is chosen automatically; the size is saved and restored.
• Resizable windows: the Play and Review windows can be maximized or drag-resized. The board continuously rescales to fill the available height and the side panels absorb the remaining width.
• Colors / theme: Board → Color for square colors and Board → Theme for the overall GUI theme (before a game starts).

Files the app writes

• pecg_auto_save_games.pgn — every game played.
• pecg_analyzed_games.pgn — games annotated by Review mode's Auto-Analyze.
• pecg_engines.json — installed engines and their options.
• pecg_user.json — user name(s).
• pecg_settings.json — Settings/Game values (checkboxes and review times).
• pecg_log.txt — log file.

E. Credits

• FreeSimpleGUI
  https://github.com/spyoungtech/FreeSimpleGUI
• Python-Chess
  https://github.com/niklasf/python-chess
• Pyperclip
  https://github.com/asweigart/pyperclip
• The Week in Chess
  https://theweekinchess.com/
• PyInstaller
  https://github.com/pyinstaller/pyinstaller
• pgn-extract
  https://www.cs.kent.ac.uk/people/staff/djb/pgn-extract/