|
|
|
|
|
# ♟️ chess websocket server
|
|
|
|
|
|
|
|
|
|
|
|
This project represents a simple websocket server to play chess.
|
|
|
|
|
|
|
|
|
|
|
|
- [Local setup](#local-setup)
|
|
|
|
|
|
- [Interacting with websocket server to play chess](#interacting-with-websocket-server-to-play-chess)
|
|
|
|
|
|
- [Chess moves](#chess-moves)
|
|
|
|
|
|
- [Features](#features)
|
|
|
|
|
|
- [Limitations](#limitations)
|
|
|
|
|
|
- [References](#references)
|
|
|
|
|
|
|
|
|
|
|
|
## Local setup
|
|
|
|
|
|
|
|
|
|
|
|
There are two major ways to locally setup the project to have it up and running:
|
|
|
|
|
|
|
|
|
|
|
|
- [Build from source](#build-from-source)
|
|
|
|
|
|
- [Build with Docker](#build-from-docker)
|
|
|
|
|
|
|
|
|
|
|
|
### Build from source
|
|
|
|
|
|
|
|
|
|
|
|
Requirements:
|
|
|
|
|
|
|
|
|
|
|
|
- `golang 1.19`
|
|
|
|
|
|
- `PORT` environment exported
|
|
|
|
|
|
|
|
|
|
|
|
Export `PORT` environmental variable. The port can be any port you would like.
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
export PORT=8080
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Install dependencies:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
go mod download
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Run the project:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
go run .
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Build with Docker
|
|
|
|
|
|
|
|
|
|
|
|
Requirements:
|
|
|
|
|
|
|
|
|
|
|
|
- `docker`
|
|
|
|
|
|
|
|
|
|
|
|
Build the docker image:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
docker build -t chess .
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Run the project with `PORT` env set:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
docker run -d -e PORT=8080 -p 8080:8080 chess
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Interacting with websocket server to play chess
|
|
|
|
|
|
|
|
|
|
|
|
To play chess, players need to be matched with other player.
|
|
|
|
|
|
|
|
|
|
|
|
Firstly, connect using websocket to the endpoint `ws://localhost:8080/rooms`.
|
|
|
|
|
|
After successful connection, client (e.g. player) needs to wait for response from the server.
|
|
|
|
|
|
The response will be of the following type:
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
9c954450-ad7b-4dcc-ab2f-6c556c0835ef
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
This is the UUID of the game session.
|
|
|
|
|
|
|
|
|
|
|
|
Secondly, when UUID is received connect to the next endpoint - `ws://localhost:8080/rooms/9c954450-ad7b-4dcc-ab2f-6c556c0835ef`.
|
|
|
|
|
|
The UUID should be placed after `/rooms/` path.
|
|
|
|
|
|
|
|
|
|
|
|
After successful connection, the client will receive its own chess color, either `white` or `black`.
|
|
|
|
|
|
|
|
|
|
|
|
From now on, players can exchange moves to play chess.
|
|
|
|
|
|
|
|
|
|
|
|
> If only one user connects, then the server will not send any color information.
|
|
|
|
|
|
> That's because the server waits for second player to join. After both players join,
|
|
|
|
|
|
> the players will receive own colors.
|
|
|
|
|
|
|
|
|
|
|
|
## Chess moves
|
|
|
|
|
|
|
|
|
|
|
|
The players exchange with text messages to indicate their chess move.
|
|
|
|
|
|
As of chess move notation - [Long algebraic notation](long-algebraic-notation) is used.
|
|
|
|
|
|
|
|
|
|
|
|
Players need to send chess move messages strictly by the defined notion. If the chess engine fails
|
|
|
|
|
|
to identify the chess move, then the player will receive an error message - the user will be prompted
|
|
|
|
|
|
to send a valid move.
|
|
|
|
|
|
|
|
|
|
|
|
[long-algebraic-notation]: https://en.wikipedia.org/wiki/Algebraic_notation_(chess)#Long_algebraic_notation
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
|
|
|
|
|
|
|
- Supports many concurrent games.
|
|
|
|
|
|
|
|
|
|
|
|
## Limitations
|
|
|
|
|
|
|
|
|
|
|
|
- No player reconnect mechanism. If one of user's connection interrupts, then the game session will end.
|
|
|
|
|
|
|
|
|
|
|
|
## References
|
|
|
|
|
|
|
|
|
|
|
|
- Chess Engine - [notnil/chess](https://github.com/notnil/chess).
|
|
|
|
|
|
- Websocket library - [gorilla/websocket](https://github.com/gorilla/websocket).
|
