From 93f0d7162dae045bce0781538f0385b14f98e9e7 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 11:43:23 +0100 Subject: [PATCH 1/9] doc: Add introduction section --- README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 100 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 587bb1a..5cf55c8 100644 --- a/README.md +++ b/README.md @@ -8,25 +8,105 @@ Welcome to the Chess project repo, it is my implementation of a terminal based C --- -# Setup -> [!WARNING] -> **Notice for early testers** -> -> Main branch version: `v0.8.0` +# Introduction + +> [!NOTE] +> +> Main branch version: `v0.9.0` +> +> Development Stage: `Complete (Pre-release)` +> +> This version includes most of the features I planned for this project and it is now fully playable and ready for play-testing. Checkout **Getting Started** and **How to play** sections for guidance. +> +> There are a couple more user refinements I wish to add, but I am pretty happy with the current outcome. > -> This version includes all the core features and is fully playable. -> Several user refinements will be added as development progresses. -> Keep in mind that this is an active branch, and changes will be made frequently. +> While all the core logics have been tested, you are likely to come across some bugs and issues. Shall you encounter any problems or have any questions about the project, please feel free to open an issue. > > All feedbacks are welcomed and appreciated. -## Getting Started +## Motivations + +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](https://www.theodinproject.com/paths/full-stack-ruby-on-rails/courses/ruby). + +I had a lot of fun working on this project, and 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. + +## Core User Features + +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 modes + +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](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) + +Save & Resume + +- Session is automatically save at the end of each turn +- Load and resume any session without having to restart the program + +Input modes + +- **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 +- Export your session as a `.pgn` file and import it to your preferred online chess engine + +## Quality of Life improvements + +User Profile Management + +- A mini console system - **Ruby Arcade** is purpose built for this project to offer support for multiple user profiles + +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 + +Contextual highlights + +- Meaningful text highlights are used throughout the program to act as an aid + +# Getting Started Follow the simple steps below to get started: -1. Ensure that Ruby `3.4.x` is correctly installed on your device (This project is developed using Ruby version `3.4.2`) -2. Clone the repo to your device +1. Ensure that Ruby `3.4.x` and Bundler are correctly installed on your device (This project is developed using Ruby version `3.4.2`) +2. Clone the repo or download the project from Releases `v0.9.x` 3. In your terminal, open the directory: + ``` cd rb-chess/ ``` @@ -54,6 +134,15 @@ Follow the simple steps below to get started: - Game mode 2: Local Player vs AI (Difficulty: Basic) **Technical Documentations can be found below:** + +**Test** + +| | | +| ---- | ---- | +| | | +| | | +| | | + - [Codebase documentation](https://ancientnimbus.github.io/rb-chess/doc/) - [Code coverage report](https://ancientnimbus.github.io/rb-chess/coverage/#_AllFiles) From 5ce92030fa5ce36624ea00bfd99ee5a45035ebf3 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 14:27:04 +0100 Subject: [PATCH 2/9] style: Formatting update in Textfile --- .config/locale/en.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.config/locale/en.yml b/.config/locale/en.yml index 1b48716..edcb6d1 100644 --- a/.config/locale/en.yml +++ b/.config/locale/en.yml @@ -76,7 +76,7 @@ en: * If this is your first visit to the Arcade, enter [1] to create a new profile. * If you have already created a profile, enter [2] to load your profile. msg2: "Please specify a profile loading mode: " - msg3: "Please provide a username(Default: Arcade Player): " + msg3: "Please provide a username (Default: Arcade Player): " msg4: | * 👋 Greetings %{name}! load: @@ -227,7 +227,7 @@ en: * • '0-0-0' => 'Castle Queenside' * * Pawn Promotion: - * Pawn can be prompted to a queen(Q), rook(R), bishop(B) or a knight(N). + * Pawn can be prompted to a queen (Q), rook (R), bishop (B) or a knight (N). * • 'e8=Q' => 'Pawn promotes to queen' * • 'e8=R' => 'Pawn promotes to rook' sm_h: | @@ -247,7 +247,7 @@ en: * • 'e1c1' => 'Castle Queenside' * * Pawn Promotion: - * Pawn can be prompted to a queen(q), rook(r), bishop(b) or a knight(n). + * Pawn can be prompted to a queen (q), rook (r), bishop (b) or a knight (n). * • 'e7e8q' => 'Pawn promotes to queen' * • 'e7e8r' => 'Pawn promotes to rook' blanks: From 55a4cc8f7d97cfdc73223da0e9e197290c2e9f02 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 15:11:47 +0100 Subject: [PATCH 3/9] doc: Add how to play section --- README.md | 231 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 207 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 5cf55c8..c7b4048 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # ♟️Ruby Chess [![Rspec Test Fulltrack](https://github.com/AncientNimbus/rb-chess/actions/workflows/rspec_full_track.yml/badge.svg)](https://ancientnimbus.github.io/rb-chess/coverage/#_AllFiles) -![Status](https://img.shields.io/badge/Status-In_Development-cccc00) +![Status](https://img.shields.io/badge/Status-Pre_Release-2db84d) 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. @@ -14,13 +14,13 @@ Welcome to the Chess project repo, it is my implementation of a terminal based C > > Main branch version: `v0.9.0` > -> Development Stage: `Complete (Pre-release)` +> Release branch version: `v0.9.0` > > This version includes most of the features I planned for this project and it is now fully playable and ready for play-testing. Checkout **Getting Started** and **How to play** sections for guidance. > > There are a couple more user refinements I wish to add, but I am pretty happy with the current outcome. > -> While all the core logics have been tested, you are likely to come across some bugs and issues. Shall you encounter any problems or have any questions about the project, please feel free to open an issue. +> While all the core logics have been tested, you are likely to come across bugs and issues. Shall you encounter any problems or have any questions about the project, please feel free to open an issue. > > All feedbacks are welcomed and appreciated. @@ -30,13 +30,13 @@ In this chess project, my primary goals are to validate my working knowledge in 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](https://www.theodinproject.com/paths/full-stack-ruby-on-rails/courses/ruby). -I had a lot of fun working on this project, and discovered many new things about Ruby. While the journey is far from over, completing this project is a major milestone to cross. +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. ## Core User Features -Complete Chess Experience +**Complete Chess Experience** - Legal moves only - Pawn specific: En passant and Promotion @@ -48,56 +48,63 @@ Complete Chess Experience - Threefold repetition - Insufficient Material -Game modes +**Game mode options** 1. Player vs. Player (PvP) - Locally play with two players - 2. Player vs. Computer (PvE) - Difficulty: Easy -Session load options +**Session load options** 1. New Game 2. Load Game 3. Import Game via [FEN record](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) -Save & Resume +**Save & Resume** - Session is automatically save at the end of each turn - Load and resume any session without having to restart the program -Input modes +**Input mode options** -- **Smith Notation** (Default): Coordinate-based system (`e2e3` to move directly or enter `e2` to preview, enter `e4` to complete the move) +- **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`) +- **Algebraic Notation** - The official standard for chess notation (`e4`, `Nc3`, `bxc8=Q`) -Export capabilities +**Export capabilities** - View the FEN record of the current turn via the `--info` command -- Export your session as a `.pgn` file and import it to your preferred online chess engine +- [PGN Export](https://en.wikipedia.org/wiki/Portable_Game_Notation) - Save your session as a `.pgn` file and import it to your preferred online chess engine ## Quality of Life improvements -User Profile Management +**User Profile Management** - A mini console system - **Ruby Arcade** is purpose built for this project to offer support for multiple user profiles -Input hot-swapping +**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](https://en.wikipedia.org/wiki/Touch-move_rule) 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 +**Session hot-swapping** - Load or start a new chess without having to restart the program -Chessboard customisations +**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 -Contextual highlights +**Contextual highlights** -- Meaningful text highlights are used throughout the program to act as an aid +- Meaningful text highlights are used throughout the program to act as a visual aid # Getting Started @@ -105,6 +112,7 @@ Follow the simple steps below to get started: 1. Ensure that Ruby `3.4.x` and Bundler are correctly installed on your device (This project is developed using Ruby version `3.4.2`) 2. Clone the repo or download the project from Releases `v0.9.x` + 3. In your terminal, open the directory: ``` @@ -123,15 +131,190 @@ Follow the simple steps below to get started: # How to play > [!TIP] -> Instructions can be found throughout the program via the command `--help`, more detailed introductions will be added here shortly. +> Instructions can be found throughout the program via the command `--help`. +> +> You can exit the program at any point via the `--exit` command. +> +> The command system is context aware, so its usage availability depends on the location you are at. + +See the example below on how to launch chess as a new user: + +
+ Stage 1: Welcome to Ruby Arcade + +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 +3. Enter `1` to create a new profile +4. Give your profile a username such as `Ruby Chess Tester` +5. Your profile will be created automatically and it can be found at `/rb-chess/user_data/` directory. +6. You have successfully entered the lobby, enter `--help` to see a list of commands. +
+ +
+ Stage 2: Launching Chess + +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 quicker. +3. You will be prompted to select a load mode +4. Enter `1` to create a new game +5. You will be prompted to select a game mode +6. Enter `1` to play locally with a friend (or by yourself) or `2` to play with a computer player +7. In this example, I will enter `1` to create a Player vs. Player session +8. You will be given the option to rename both players (mode 1 only), you can skip this by pressing enter. +9. Next, indicate which side would you like to play. +10. Enter `1` to play as White +11. You have successfully created a Player vs. Player chess session +
+ +
+ Stage 3a: Play a turn using Smith Notation + + + +1. This game opted to use Smith notation as a default input option as it has a simpler learning curve. 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 +``` + +Promotion 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 +``` + +Promotion 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 +``` + +
+ +
+ Stage 3b: Play a turn using Algebraic Notation + + + +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 +``` + +Pawn Promotion + +- 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 +``` + +
# Technical Specifications **Project Scope for v1.0.0** -- Terminal based -- Game mode 1: Local Player vs Player -- Game mode 2: Local Player vs AI (Difficulty: Basic) +- [x] Terminal based +- [x] Game mode 1: Local Player vs Player +- [x] Game mode 2: Local Player vs AI (Difficulty: Easy) **Technical Documentations can be found below:** From 86fc945d67709ac875483b9d9ab20ef57613d502 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 15:19:24 +0100 Subject: [PATCH 4/9] doc: Fix formatting and typo --- README.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index c7b4048..1674f93 100644 --- a/README.md +++ b/README.md @@ -137,14 +137,14 @@ Follow the simple steps below to get started: > > The command system is context aware, so its usage availability depends on the location you are at. -See the example below on how to launch chess as a new user: +See the example below on how to launch chess as a new player:
Stage 1: Welcome to Ruby Arcade 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 -3. Enter `1` to create a new profile + - Enter `1` to create a new profile 4. Give your profile a username such as `Ruby Chess Tester` 5. Your profile will be created automatically and it can be found at `/rb-chess/user_data/` directory. 6. You have successfully entered the lobby, enter `--help` to see a list of commands. @@ -159,24 +159,26 @@ See the example below on how to launch chess as a new user: --play chess ``` -2. A boot screen is printed, the instructions shall hopefully get you orientated with the program quicker. +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 -4. Enter `1` to create a new game -5. You will be prompted to select a game mode -6. Enter `1` to play locally with a friend (or by yourself) or `2` to play with a computer player -7. In this example, I will enter `1` to create a Player vs. Player session -8. You will be given the option to rename both players (mode 1 only), you can skip this by pressing enter. -9. Next, indicate which side would you like to play. -10. Enter `1` to play as White -11. You have successfully created a Player vs. Player chess session -
+ - 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 +
Stage 3a: Play a turn using Smith Notation -1. This game opted to use Smith notation as a default input option as it has a simpler learning curve. Type the `--help smith` command will print a simple user guide while in-game +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** @@ -186,7 +188,7 @@ See the example below on how to launch chess as a new user: e2e4 ``` -Promotion a pawn +Promote a pawn - To promote a pawn to a queen and move with a single prompt: @@ -208,7 +210,7 @@ e2 e4 ``` -Promotion a pawn +Promote a pawn - To promote a pawn to a bishop, first select a pawn at h7: @@ -241,7 +243,7 @@ Note: Preview mode is not available for Algebraic notation due to usage consider 2. Type the `--help alg` command will print a simple user guide while in-game -Move a chess piece +**Move a chess piece** - Move a pawn to e4 @@ -255,7 +257,7 @@ e4 Qa1 ``` -Capture a chess piece +**Capture a chess piece** - Pawn captures e4 from d file @@ -269,7 +271,7 @@ dxe4 Bxc5 / Bfxc5 ``` -Castling +**Castling** - Kingside castling @@ -283,7 +285,7 @@ O-O O-O-O ``` -Pawn Promotion +**Promote a pawn** - Move and promote to a queen From 1d88674dd820bd21f0902db9e55e57fecba092f0 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 16:21:37 +0100 Subject: [PATCH 5/9] doc: Update technical details section --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 79 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 1674f93..02670f7 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Welcome to the Chess project repo, it is my implementation of a terminal based C > > While all the core logics have been tested, you are likely to come across bugs and issues. Shall you encounter any problems or have any questions about the project, please feel free to open an issue. > -> All feedbacks are welcomed and appreciated. +> All feedback is welcome and appreciated. ## Motivations @@ -73,9 +73,9 @@ Without further ado, read on below to learn more about my chess project. **Export capabilities** - View the FEN record of the current turn via the `--info` command -- [PGN Export](https://en.wikipedia.org/wiki/Portable_Game_Notation) - Save your session as a `.pgn` file and import it to your preferred online chess engine +- [PGN Export](https://en.wikipedia.org/wiki/Portable_Game_Notation) - Save your session as a `.pgn` file and import it to your preferred online [chess engine](https://lichess.org/paste) -## Quality of Life improvements +## Quality of Life Improvements **User Profile Management** @@ -128,7 +128,7 @@ Follow the simple steps below to get started: ``` -# How to play +# How to Play > [!TIP] > Instructions can be found throughout the program via the command `--help`. @@ -146,7 +146,7 @@ See the example below on how to launch chess as a new player: 2. You will be prompted to create or load a user profile - Enter `1` to create a new profile 4. Give your profile a username such as `Ruby Chess Tester` -5. Your profile will be created automatically and it can be found at `/rb-chess/user_data/` directory. +5. Your profile will be created automatically and can be found at the `/rb-chess/user_data/` directory. 6. You have successfully entered the lobby, enter `--help` to see a list of commands.
@@ -169,7 +169,7 @@ See the example below on how to launch chess as a new player: 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 - +
Stage 3a: Play a turn using Smith Notation @@ -310,30 +310,92 @@ q
+
+ Stage 4: Using commands in Chess +Note: As a reminder, `--help` will display all available commands for chess. + +- Print session details and FEN record for the current turn: + +``` +--info +``` -# Technical Specifications +- 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 +``` +
+ +# Technical Details + +## **Project Scope for v1.0.0** -**Project Scope for v1.0.0** - [x] Terminal based +- [x] Colourful chessboard within unicode and terminal environment constrains +- [x] Full Chess rules - [x] Game mode 1: Local Player vs Player - [x] Game mode 2: Local Player vs AI (Difficulty: Easy) +- [x] Flexible yet butterfingers-proof user input system +- [x] Persistence data serialisation +- [x] FEN I/O +- [x] Turn-based FEN Generation +- [x] PGN Export +- [x] Implement command pattern interface + +## Stretch goals + +- [ ] Adjust computer’s response rate +- [ ] Custom board theme + +## Known Issues + +> [!WARNING] +> Below are a list of of known issues found during testing +> +> 1. PGN export might not include the last move if it is made by White +> 2. FEN import will reset the full move counter, this is a minor issue as it won’t affect the actual gameplay +> -**Technical Documentations can be found below:** +## Technical Documentations -**Test** +**Test Coverage Summary** -| | | -| ---- | ---- | -| | | -| | | -| | | +| Metric | Value | +| ------------------------------ | ------------------- | +| Test Suites | 17 | +| Test cases | 338 | +| Chess related scripts coverage | 100% | +| Overall coverage | 99.01% | +| Lines covered (Libs + Chess) | 1711 (Total: ≈1750) | +| Avg. Hits per line | 2335.8 | +| | | - [Codebase documentation](https://ancientnimbus.github.io/rb-chess/doc/) - [Code coverage report](https://ancientnimbus.github.io/rb-chess/coverage/#_AllFiles) -For more details regarding the development of this project, feel free to checkout the [Wiki](https://github.com/AncientNimbus/rb-chess/wiki) page. +For more details regarding the development of this project, feel free to checkout the [Wiki](https://github.com/AncientNimbus/rb-chess/wiki) page (New article coming soon). -## Gems used +## Gems Used - [Paint](https://github.com/janlelis/paint) - [Whirly](https://github.com/janlelis/whirly) From d9e1cbb22af973b65b7acdc2a747990a3729e231 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 16:26:18 +0100 Subject: [PATCH 6/9] doc: Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 02670f7..c2a8bb4 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ Without further ado, read on below to learn more about my chess project. **Save & Resume** -- Session is automatically save at the end of each turn +- Session is automatically saved at the end of each turn - Load and resume any session without having to restart the program **Input mode options** From 69d1586a2bac65e35ce1cc4084b59461a9a53b09 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 16:35:00 +0100 Subject: [PATCH 7/9] doc: Add links to README --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c2a8bb4..7340b94 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ![Status](https://img.shields.io/badge/Status-Pre_Release-2db84d) -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. +Welcome to the Chess project repo, it is my implementation of a terminal based [Chess](https://www.instructables.com/Playing-Chess/) game written in Ruby, with user experience set as the primary focus. --- @@ -66,9 +66,9 @@ Without further ado, read on below to learn more about my chess project. **Input mode options** -- **Smith Notation** (Default) - Coordinate-based system (`e2e3` to move directly or enter `e2` to preview, enter `e4` to complete the move) +- [**Smith Notation**](https://en.wikipedia.org/wiki/Chess_notation#Notation_systems) (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`) +- [**Algebraic Notation**](https://www.chessable.com/blog/chess-notation-for-beginners/) - The official standard for chess notation (`e4`, `Nc3`, `bxc8=Q`) **Export capabilities** @@ -101,10 +101,12 @@ Note: This mode respects the [Touch-move](https://en.wikipedia.org/wiki/Touch-mo - 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](https://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](https://cli.github.com/) # Getting Started From b2d00728d349146514853eb92acc4f0a6e10933d Mon Sep 17 00:00:00 2001 From: "Alex Y." <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 17:17:38 +0100 Subject: [PATCH 8/9] doc: Add gifs to README --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 7340b94..8106149 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,16 @@ [![Rspec Test Fulltrack](https://github.com/AncientNimbus/rb-chess/actions/workflows/rspec_full_track.yml/badge.svg)](https://ancientnimbus.github.io/rb-chess/coverage/#_AllFiles) ![Status](https://img.shields.io/badge/Status-Pre_Release-2db84d) +

+chess-boot-screen +

+ Welcome to the Chess project repo, it is my implementation of a terminal based [Chess](https://www.instructables.com/Playing-Chess/) game written in Ruby, with user experience set as the primary focus. --- + # Introduction > [!NOTE] @@ -24,6 +29,15 @@ Welcome to the Chess project repo, it is my implementation of a terminal based [ > > All feedback is welcome and appreciated. +
+ Gamplay Preview - v0.9.0 (Spoiler) + +**A classic fool's mate** +

+chess-boot-screen +

+
+ ## Motivations 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. From 59a314082527e096c4cf22e72e12a7f74a937795 Mon Sep 17 00:00:00 2001 From: Ancient Nimbus <99920424+AncientNimbus@users.noreply.github.com> Date: Tue, 5 Aug 2025 17:45:59 +0100 Subject: [PATCH 9/9] doc: Add data serialisation section --- README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8106149..a9d30be 100644 --- a/README.md +++ b/README.md @@ -390,7 +390,63 @@ Note: As a reminder, `--help` will display all available commands for chess. > > 1. PGN export might not include the last move if it is made by White > 2. FEN import will reset the full move counter, this is a minor issue as it won’t affect the actual gameplay -> +> + +## Data Serialisation + +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. + +
+ Click to see a sample of an user profile + +```json +{ + "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 + } +} +``` +
+ + + + ## Technical Documentations