Awesome

uchess

♛♔ Play chess in your terminal.

uchess screenshot

Introduction

uchess is an interactive terminal chess client designed to allow gameplay and move analysis in conjunction with UCI chess engines.

uchess is highly configurable, fully themeable, and capable of supporting a variety of play scenarios including human vs. human, human vs. cpu, and cpu vs. cpu.

Games may be initialized via FEN notation and exported to PGN notation for further analysis in third-party engines. Additionally, board snapshots may be saved to SVG image format for the purpose of sharing or archiving board state.

A hint engine is provided to assist players in discovering the best move in a given scenario and game state may be walked backward on an as-needed basis to facilitate game tree exploration.

Game moves are input as algebraic notation via an interactive command shell, and a variety of auxillary commands are supported.

An example of a board snapshot:

uchess board snapshot

Installation

The easiest way to get uchess is via an official release.

uchess can also be installed using "go get". A valid GOPATH is required to use the go get command. If $GOPATH is not specified, $HOME/go will be used by default. Make sure $GOPATH/bin is in your $PATH so your shell can find the binary.

$ go get github.com/tmountain/uchess/cmd/uchess

Build

uchess includes a Makefile which will build a binary for your native architecture.

$ make build
$ cmd/uchess/uchess

You can also cross compile via make release_test.

$ make release_test
$ tree dist
dist
├── uchess_darwin_amd64
│   └── uchess
├── uchess_linux_amd64
│   └── uchess
├── uchess_linux_arm_5
│   └── uchess
└── uchess_windows_amd64
    └── uchess.exe

Usage

The easy way: zero configuration

With no arguments specified, uchess will attempt to locate stockfish in your path and run it with difficulty level 3.

If stockfish cannot be found, uchess provides for an automated installation on Linux and Windows. Automated install for Mac is a work in progress.

The manual way: generate a uchess config and edit it accordingly

Mac and Linux

$ uchess -tmpl > uchess.json

Windows

# Avoid BOM in config file
> .\uchess.exe -tmpl | set-content uchess.json -Encoding Ascii

Run uchess on the config.

Mac and Linux

$ uchess -cfg uchess.json

Windows

> .\uchess.exe -cfg uchess.json

Commands

uchess accepts commands via an interactive shell. The following commands are supported.

  back           Walk the game state back one turn.
  save           Save the PGN for the current game in the CWD.
  image          Save an SVG snapshot of the current game in the CWD.
  fen            Display the FEN string for the current game.
  reset          Reset the board to the default FEN.
  resign         The current player resigns.
  hint           Highlight the recommended move using the hint engine.
  quit           Shutdown uchess immediately without saving game state.

If none of the previous commands are recognized, the input is assumed to be a move specified in algebraic notation.

  Examples:
      e4         Pawn to e4.
      exd5       Pawn on the e-file captures the piece on d5.
      O-O        King castles on kingside.
      O-O-O      King castles on queenside.
      e8=Q       Pawn promotion to queen.

Config Example

{
  "uciWhite": "stockfish",
  "uciBlack": "stockfish",
  "uciHint": "stockfish",
  "uciEngines": [
    {
      "name": "stockfish",
      "engine": "/usr/games/stockfish",
      "hash": 128,
      "ponder": false,
      "ownBook": false,
      "multiPV": 4,
      "depth": 0,
      "searchMoves": "",
      "moveTime": 3000,
      "options": [
        {
          "name": "skill level",
          "value": "20"
        }
      ]
    }
  ],
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "activeTheme": "basic",
  "theme": [
    {
      "name": "basic",
      "moveLabelBg": "#d0d0d0",
      "moveLabelFg": "#000000",
      "squareDark": "#d78700",
      "squareLight": "#ffaf5f",
      "squareHigh": "#5fffaf",
      "squareHint": "#af87ff",
      "squareCheck": "#ff87d7",
      "white": "#eeeeee",
      "black": "#080808",
      "msg": "#d70000",
      "rank": "#9e9e9e",
      "file": "#9e9e9e",
      "prompt": "#d70000",
      "meterBase": "#585858",
      "meterMid": "#0",
      "meterNeutral": "#00d7ff",
      "meterWin": "#87ffd7",
      "meterLose": "#d75f5f",
      "playerNames": "#0",
      "score": "#9e9e9e",
      "moveBox": "#0",
      "emoji": "#0",
      "input": "#0",
      "advantage": "#9e9e9e"
    }
  ],
  "whitePiece": "human",
  "blackPiece": "cpu",
  "whiteName": "",
  "blackName": ""
}

Base Config Format

When invoked with the -tmpl argument, uchess will generate a config with a reasonable set of defaults. The config file is a JSON document with the following top-level keys.

  uciWhite       Name of the UCI engine controlling white pieces.
  uciBlack       Name of the UCI engine controlling black pieces.
  uciHint        Name of the UCI engine providing hints.
  uciEngines     A list of available UCI engines (see UCI CONFIG FORMAT).
  fen            FEN notation specifying starting positions.
  activeTheme    The currently selected theme (list available via -themes).
  theme          A list of available themes (see THEMES).
  whitePiece     Player controlling the white pieces (cpu or human).
  blackPiece     Player controlling the black pieces (cpu or human).
  whiteName      Player name for white pieces in UI.
  blackName      Player name for black pieces in UI.

UCI Config Format

The uchess config file may reference any number of UCI engines; however, each engine must by identified by a unique name parameter. The following keys are supported for UCI configuration.

  name           The unique UCI engine name.
  engine         The path to the UCI engine binary (OS dependent).
  hash           The value in MB for hash table memory.
  ponder         Allow or disallow the engine to ponder.
  ownBook        Specifies whether the engine has its own opening book.
  multiPV        The engine supports multi best line or k-best mode.
  depth          Search x plies only. A setting of 0 specifies unlimited plies.
  searchMoves    Restrict search to moves specified (i.e., "e2e4 d2d4").
  moveTime       Search exactly x mseconds.
  options        Key-value pairs for arbitrary engine commands.

Note: when depth and searchMoves are both specified, the default behavior for Stockfish seems to be using whichever limit terminates the soonest.

Themes

uchess is fully themeable, and user specified themes may be added to the uchess config file. The theme keys are named in a manner which is intended to be self-explanatory, and colors are specified by their respective hex values. It is recommended to limit colors to the spectrum supported by your terminal. xterm-256 (8-bit color) is the official standard for builtin themes.

The builtin themes are packaged into the uchess binary using Golang's embed package. New themes should be added to the themes project directory.

Pull requests for new builtin themes are welcome; however, the specified colors must fall under the xterm-256 standard. A color chart is available here.

Builtin themes should be specified on a one theme per file basis, and all themes should be specified in JSON format and reside in the themes directory.

When a name collision occurs, themes specified in the config file will override builtin themes.

Lastly, a special hex code of #0 is used to specify the terminal default color. This code should be used for any UI elements that may collide with an underlying color scheme (i.e., avoiding white fonts on white backgrounds).

Game Outcomes

uchess can effectively identify a wide variety of game outcomes, and it should account for the following end-game scenarios:

    Checkmate
    Stalemate
    Resignation (manual)
    Threefold Repetition
    Fivefold Repetition
    Fifty Move Rule
    Seventy Five Move Rule
    Insufficient Material

CPU Matches

If the uchess config specifies both whitePiece and blackPiece as cpu, the specified UCI engines will play against each other. The game will cycle forward one move each time tne enter key is pressed.

Platform Support

uchess has been tested and confirmed to work on Linux, MacOS, and Windows (Windows Terminal) platforms. It should work with a wide variety of terminals.

Project Status

uchess is currently in unstable (alpha) status, and its internal APIs are subject to change. Efforts will be made to keep the config file and theme format stable going forward to the extent that it is practical to do so.

Special Thanks

uchess depends on the notnil/chess, and gdamore/tcell modules. Many thanks to the maintainers.

Lastly, uchess is heavily inspired by nickzuber/chs.