Welcome to the Chess project repo, it is my implementation of a terminal based Chess game written in Ruby, with user experience set as the primary focus.

Gameplay footage for v0.9.0

A classic fool's mate (Terminal: Warp)

Legal's mate is another classic (Terminal: iTerm)

In this chess project, my primary goals are to validate my working knowledge in Ruby, effective use of OOP, system design, and refine my software development workflow such as project management & scope estimations.

This project is also presented as my final learning outcome for the Ruby course in the Full Stack Ruby on Rails path developed by The Odin Project.

I had a lot of fun working on this project, and have discovered many new things about Ruby. While the journey is far from over, completing this project is a major milestone to cross.

Without further ado, read on below to learn more about my chess project.

Complete Chess Experience

• Legal moves only
• Pawn specific: En passant and Promotion
• King specific: Castling
• Check and Checkmate detection
• Draw detection based on the following rules:
  • Stalemate
  • Fifty-move rule
  • Threefold repetition
  • Insufficient Material

Game mode options

1. Player vs. Player (PvP) - Locally play with two players
2. Player vs. Computer (PvE) - Difficulty: Easy

Session load options

1. New Game
2. Load Game
3. Import Game via FEN record

Save & Resume

• Session is automatically saved at the end of each turn
• Load and resume any session without having to restart the program

Input mode options

• Smith Notation (Default) - Coordinate-based system (e2e3 to move directly or enter e2 to preview, enter e4 to complete the move)

• Algebraic Notation - The official standard for chess notation (e4, Nc3, bxc8=Q)

Export capabilities

• View the FEN record of the current turn via the --info command
• PGN Export - Save your session as a .pgn file and import it to your preferred online chess engine

User Profile Management

• A mini console system - Ruby Arcade is purpose built for this project to offer support for multiple user profiles

Preview mode on Smith Notation

In addition to direct move such as e2e4, this input mode also supports a preview feature where players have the ability see all the possible movements of a given chess piece.

To use it, select a chess piece such as e2 and hit enter, the board will display all movements with distinctive highlights. In the following prompt, confirm your move such as e4 to complete your turn.

Note: This mode respects the Touch-move rule, meaning once a chess piece is selected, you must play it this turn.

Input hot-swapping

• Notation input preference is interchangeable throughout the program

Session hot-swapping

• Load or start a new chess without having to restart the program

Chessboard customisations

• Two chessboard sizes can be swap via the --board size command
• Chessboard flip settings can be enabled/disabled via the --board flip command
• The default chessboard design is inspired by Lichess.org

Contextual highlights

• Meaningful text highlights are used throughout the program to act as a visual aid
• The input prompt prefix is inspired by GitHub CLI

Follow the simple steps below to get started:

Ensure that Ruby 3.4.x and Bundler are correctly installed on your device (This project is developed using Ruby version 3.4.2)

1. Install the gem to your local environment:

gem install chess_cli

2. Run the game!

chess_cli

3. To uninstall the game:

gem uninstall chess_cli

1. Clone the repo or download the project from Releases v0.9.x

2. In your terminal, open the directory:

cd rb-chess/

4. Build the gem locally:

gem build chess_cli.gemspec

5. Install the gem to your local environment:

gem install chess_cli

6. Run the game!

chess_cli

7. To uninstall the game:

gem uninstall chess_cli

See the example below on how to launch chess as a new player:

1. A boot screen is printed, adjust your terminal window size if needed (Recommended size: 80x35)
2. You will be prompted to create or load a user profile
   • Enter 1 to create a new profile
3. Give your profile a username such as Ruby Chess Tester
4. Your profile will be created automatically and can be found at the /rb-chess/user_data/ directory.
5. You have successfully entered the lobby, enter --help to see a list of commands.

1. To launch chess, simply type the following:

--play chess

2. A boot screen is printed, the instructions shall hopefully get you orientated with the program easier.
3. You will be prompted to select a load mode
   • Enter 1 to create a new game
4. You will be prompted to select a game mode
   • Enter 1 to play locally with a friend (or by yourself) or 2 to play with a computer player
   • In this example, I will enter 1 to create a Player vs. Player session
5. You will be given the option to rename both players (mode 1 only), you can skip this by pressing enter.
6. Next, indicate which side would you like to play.
   • Enter 1 to play as White
7. You have successfully created a Player vs. Player chess session

Note: This game opted to use Smith notation as a default input option as it has a simpler learning curve.

1. Type the --help smith command will print a simple user guide while in-game

Direct move

• To select a piece and move with a single prompt:

e2e4

Promote a pawn

• To promote a pawn to a queen and move with a single prompt:

e7e8q

Preview then move

• To use preview mode, first select a piece:

e2

• After previewing, enter the desire location to move:

e4

Promote a pawn

• To promote a pawn to a bishop, first select a pawn at h7:

h7

• After previewing, enter the desire location to move:

h8

• You will be prompted to promote the pawn, in this case b is entered to represent bishop:

b

Note: Preview mode is not available for Algebraic notation due to usage consideration.

1. To use Algebraic Notation as an input option. First type the --alg command and press enter to confirm the selection

2. Type the --help alg command will print a simple user guide while in-game

Move a chess piece

• Move a pawn to e4

e4

• Move a queen to a1

Qa1

Capture a chess piece

• Pawn captures e4 from d file

dxe4

• Bishop captures c5 from f file

Bxc5 / Bfxc5

Castling

• Kingside castling

O-O

• Queenside castling

O-O-O

Promote a pawn

• Move and promote to a queen

e8=Q

• Capture and promote to a rook

bxc1=R

• In the event where you have forgotten to enter promote option, an additional prompt will appear as fallback

# First prompt (Move pawn to c8)
c8
# Second prompt (Promote to queen)
q

• Print session details and FEN record for the current turn:

--info

• Load or create another session in game:

--load

• Toggle between standard or large chessboard:

--board size

• Toggle chessboard flip settings (when play as black the board file index starts from h to a):

--board flip

• Export current session as a .pgn file
• The exported file can be found at the /rb-chess/user_data/pgn_export/ directory.

--export

• Terminal based
• Colourful chessboard within unicode and terminal environment constrains
• Full Chess rules
• Game mode 1: Local Player vs Player
• Game mode 2: Local Player vs AI (Difficulty: Easy)
• Flexible yet butterfingers-proof user input system
• Persistence data serialisation
• FEN I/O
• Turn-based FEN Generation
• PGN Export
• Implement command pattern interface

• Adjust computer’s response rate
• Custom board theme

I would like to briefly highlight some of the key characteristics of the user serialisation structure for this project. The core objectives are to preserve game state optimally, provide multi-sessions and multi-user support.

When designing the data structure for the chess game, I referenced the metadata field used by PGN as a starting point, this ensures that it is compliance from the start and allow easy data conversion. As the development progresses, I realised that it is easier to rebuild game state using FEN data string, hence fens field is added to the serialisation structure.

Since all the data related to chess is grouped under the chess field, this user profile should be robust enough to handle other games or services without corrupting chess specific data.

Lastly, all data values are saved with primitive types to ensure maximum compatibly across different platforms. Therefore, it is language agnostic.

{
  "uuid": "bdfe89d5-d9eb-4397-b203-5f1a7eccd639",
  "username": "Nimbus",
  "saved_date": "2025-08-05 16:55:53 +0100",
  "appdata": {
    "chess": {
      "1": {
        "event": "Nimbus vs Spock Status Checkmate",
        "site": "Ruby Arcade Terminal Chess by Ancient Nimbus",
        "date": "08/05/2025 04:55 PM",
        "round": null,
        "white": "Nimbus",
        "black": "Spock",
        "result": null,
        "mode": 1,
        "moves": {
          "1": ["f4", "e5"],
          "2": ["g4", "Qh4#"]
        },
        "white_moves": ["f4", "g4"],
        "black_moves": ["e5", "Qh4"],
        "fens": [
          "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
          "rnbqkbnr/pppppppp/8/8/5P2/8/PPPPP1PP/RNBQKBNR b KQkq - 0 1",
          "rnbqkbnr/pppp1ppp/8/4p3/5P2/8/PPPPP1PP/RNBQKBNR w KQkq - 0 2",
          "rnbqkbnr/pppp1ppp/8/4p3/5PP1/8/PPPPP2P/RNBQKBNR b KQkq - 0 2",
          "rnb1kbnr/pppp1ppp/8/4p3/5PPq/8/PPPPP2P/RNBQKBNR w KQkq - 1 3"
        ]
      }
    }
  },
  "stats": {
    "launch_count": 1
  }
}

Test Coverage Summary

• Codebase documentation
• Code coverage report

For more details regarding the development of this project, feel free to checkout the Wiki page (New article coming soon).

• Paint
• Whirly
• RSpec
• Rubocop
• Yard
• SimpleCov

The chessboard design is published as a gist, feel free to adapt it to your own project.