Live Demo (The site may open slowly because I deployed the project to a free vercel account)
Chess web application with detailed explanations that offers users a playable chess game and additional features. This project is not designed by using chess programming techniques(0x88, bitboards, etc.). But all the rules of chess are implemented in this project. The project consists of three parts: Chess Platform, Platform, and Chess. More detailed information about these parts can be found in the Architecture section. The project is written entirely in TypeScript and tested with Vitest.
- by ChessPlatform
- Connection between Platform and Chess
- by Chess
- General Rules: Check, Checkmate, Stalemate.
- Other Rules: Threefold repetition, Fifty-move rule.
- Board: Includes animations and sounds for moves. Also, easily customizable from css.
- Move Calculation: Calculation and validation of every piece.
- Special Moves: Castling, Promotion, En Passant.
- Score Calculation: For more information check this.
- Algebraic Notation: For more information check this.
- Fen Notation: For more information check this.
- Caching: With active-passive options.
- Logging: Detailed descriptions of calculation in engine and board.
- Standalone Versions: For use just board or engine.
- by Platform
- Notation Table: Shows the algebraic notation calculated by chess on UI.
- Score Section: Shows the score calculated by chess on UI.
- Game Creator: Input for custom fen notation and select box for some template fen notations.
- Log Console: Shows the log created by chess on UI in every action.
In this section, I will explain the project's architecture without going into too much detail as much as possible. As I mentioned in the introduction, the project currently consists of two main parts and the third part that provides connection between main parts and manages the app.
-
Chess Platform
The part that provides connection between Platform and Chess. Creates Chess instance and provides it to Platform instance. So, chess methods can be used by platform's components. And by connecting Platform and Chess, it provides the start point for the project. -
Chess
Chess provides a playable game on web by using ChessEngine and ChessBoard instances. Also, has a Cache system for save the game and log system for save the details of every action.
-
ChessEngine
ChessEngine provides the mechanism of the game. All the rules of chess are implemented in this class and can be used as standalone or directly by Chess class for playable game by connecting with ChessBoard. -
ChessBoard
ChessBoard provides the interactive chessboard that players can make actions but doesn't have any mechanism. ChessBoard can be used as standalone or directly by Chess class for playable game by connecting with ChessEngine. Also, both board and pieces can be visualized from assets.
-
ChessEngine
-
Platform
Platform provides some UI components by using chess instance that connected by Chess Platform. Currently, Platform has four components: Notation Table that shows every played move of players as algebraic notation, Score Section(comes with notation table) that shows score of every player, Game Creator that provide 2 different create form(used with fen notation) for users, and Log Console that shows the log of every action of players on UI by using chess instance's log system.
classDiagram
class ChessPlatform {
+ readonly chess: Chess
- readonly platform: Platform
+ constructor()
}
class Chess {
- chessBoard: ChessBoard
- chessEngine: ChessEngine
+ constructor()
}
class ChessEngine {
+ constructor()
}
class ChessBoard {
+ constructor()
}
class Platform {
- readonly chess: Chess
- notationTable: NotationTable
- gameCreator: GameCreator
- logConsole: LogConsole
+ constructor()
}
class NotationTable {
- readonly chess: Chess
+ constructor()
}
class GameCreator {
- readonly chess: Chess
+ constructor()
}
class LogConsole {
- readonly chess: Chess
+ constructor()
}
ChessPlatform *-- Chess
ChessPlatform *-- Platform
Chess "0..1" o-- "1" ChessBoard
Chess "0..1" o-- "1" ChessEngine
Platform "1" *-- "0..1" NotationTable
Platform "1" *-- "0..1" GameCreator
Platform "1" *-- "0..1" LogConsole
-
Clone the repository.
git clone https://github.com/bberkay/chess-platform.git -
Install the dependencies(typescript, vite, vitest).
npm install -
Run the project
npm run dev
<html>
<head>
<title>Chess Platform</title>
</head>
<body>
<div id = "chessboard"></div> <!-- Required while using ChessPlatform -->
<div id = "notation-table"></div> <!-- Optional, also provide score table -->
<div id = "log-console"></div> <!-- Optional -->
<div id = "game-creator"></div> <!-- Optional -->
<!-- Initiate Chess Platform -->
<script>
import { ChessPlatform } from "./src/ChessPlatform";
import { StartPosition } from "./src/Chess/Types";
/**
* If there is a game in cache, then platform
* will load it. Otherwise, platform will create
* a new standard game.
*/
const enableCaching = true; // default
const chessPlatform = new ChessPlatform(enableCaching); // same as new const chessPlatform = new ChessPlatform();
// Also, chess methods can be used from chessPlatform.
chessPlatform.chess.createGame(StartPosition.Standard);
</script>
</body>
</html>Also, this is current usage in index.html of the Live Demo.
<html>
<head>
<title>Chess without Platform</title>
</head>
<body>
<div id = "chessboard"></div> <!-- Required while using Chess -->
<!-- Initiate Chess without Platform -->
<script>
import { Chess } from "./src/Chess/Chess";
/**
* If there is a game in cache, then chess
* will load it. Otherwise, chess will
* create a new standard game.
*/
const enableCaching = true; // default
const chess = new Chess(enableCaching); // same as new const chess = new Chess();
</script>
</body>
</html>Most (but not all) of the public methods you can use within the Chess class.
| File | Name | Description |
|---|---|---|
| See | createGame(position) | Create a new game with the given position using ChessEngine and ChessBoard |
| See | getGameAsFenNotation() | Get the fen notation of the current game as string |
| See | getGameAsJsonNotation() | Get the json notation of the current game |
| See | getNotation() | Get the algebraic notation of the current game |
| See | getScores() | Get the scores of the current game as an object |
| See | getLogs() | Get the logs of the current game as an array |
| See | clearLogs() | Clear the logs of the current game |
<html>
<head>
<title>Chessboard Standalone</title>
</head>
<body>
<div id = "chessboard"></div> <!-- Required while using ChessBoard -->
<!-- Initiate Chessboard as Standalone -->
<script>
import { ChessBoard } from "./src/Chess/Board/ChessBoard";
import { Square } from "./src/Chess/Types";
// Standard game will be created in constructor.
const chessBoard = new ChessBoard()
// Play on board(without engine)
chessBoard.playMove(Square.e2, Square.e4);
</script>
</body>
</html>Most (but not all) of the public methods you can use within the ChessBoard class.
| File | Name | Description |
|---|---|---|
| See | createGame(position) | Create a new game with the given position(just board no mechanics). |
| See | highlightMoves(moves) | Highlight the given moves/squares on the board. |
| See | showStatus(status) | Show the given status(Game Status) on the board as popup. |
| See | getLogs() | Get the logs of the all operations that made on the board as an array. |
// somefile.ts/somefile.js
import { ChessEngine } from "./src/Chess/Engine/ChessEngine";
import { Square } from "./src/Chess/Types";
// Standard game will be created in constructor.
const chessEngine = new ChessEngine();
// Play on engine(without board)
chessEngine.playMove(Square.e2, Square.e4);Most (but not all) of the public methods you can use within the ChessEngine class.
| File | Name | Description |
|---|---|---|
| See | createGame(position) | Create a new game with the given position(on terminal/console). |
| See | getGameAsFenNotation() | Get the fen notation of the current game as string |
| See | getGameAsJsonNotation() | Get the json notation of the current game |
| See | getGameAsASCII() | Get the ASCII representation of the current game |
| See | getMoves(square) | Get moves of the piece on the given square as Moves. |
| See | playMove(from, to) | Move the piece from the given square to the given square on the engine. |
| See | getGameStatus() | Get current status of game as Game Status |
| See | getNotation() | Get the algebraic notation of the current game |
| See | getScores() | Get the scores of the current game as an object |
| See | getLogs() | Get the logs of the current game as an array |
Chess Platform is tested with Vitest. Tests consist mostly of engine tests like move calculation, move validation, checkmate, stalemate, etc. Also, there are some tests for converting operations like fen notation to json notation. You can run all the tests with the following command.
npm run test
My first plan is to switch from Node.js to Bun. Multiplayer support, which will be controlled by ChessPlatform, is also one of my main goals. Along with multiplayer support, options such as proposing a takeback, offering a draw, resigning from a match, and viewing possibility of previous moves from the notation table will need to be developed. I also have some smaller plans on my list, such as PGN support in chess and table marking in the chessboard.