ChessNowBot

ChessNowBot - the Telegram Mini App that brings the classic game of chess to your favorite messaging platform! Engage in thrilling chess matches with friends, colleagues, or fellow group members without leaving Telegram. ChessNowBot seamlessly integrates into your chats, offering a user-friendly interface for an immersive chess experience.

First Place Winner in the Telegram Mini App Contest

ChessNowBot has been awarded the first place in the Telegram Mini App Contest. 🎉🏆

ChessNowBot was developed as a submission for the Telegram Mini App Contest. The goal of this competition is to encourage the creation of diverse and useful Mini Apps for Telegram. The ChessNowBot project adheres to the contest guidelines, providing a complete and functional Mini App for playing chess within the Telegram environment.

Demo

You can evaluate ChessNowBot functionality in Telegram. The bot is available under the name @ChessNowBot. Just select any chat, type in @ChessNowBot and add a space.

Features

Game Modes

ChessNowBot offers three predefined game modes, allowing users to choose their preferred chess-playing experience. Additionally, a custom mode lets users define specific timer settings and their starting side (black, white, or random).

Invitation System

Initiate chess games by sending invitations to individual chats, groups, or channels. When recipients accept the invitation, they are directed to a web view within the Telegram app to join the game.

Spectator Mode

Invite multiple participants, but only the first to press "join" engages in the game. Others become spectators, observing the chess match as it unfolds.

Real-time Updates

Stay informed about the game's progress with real-time updates in the Telegram chat. Messages sent by ChessNowBot dynamically reflect the current state of the game, including the players, game status, and outcomes.

Game Statistics

ChessNowBot maintains a database of completed games, allowing users to access personal and global statistics using the /stats command. Track your performance and explore overall trends in the ChessNowBot community.

Overview

The application comprises two main components: the Server and the Client, each residing in their respective directories at the root of the repository.

Server

The server is implemented as a Node.js application written in TypeScript. It consists of two primary parts:

1. ChessNowBot (Telegraf.js):

• The ChessNowBot class, developed using the Telegraf.js library, acts as a Telegram bot and facilitates communication with users through the Telegram inline mode.

• It is responsible for creating game rooms whenever a user initiates a new game invitation.

• It generates a game invitation, that includes a link to the Telegram Mini App with a startapp parameter that has the room ID to connect to.

2. GameServer and ServerRoom (Socket.io):

• GameServer handles connections through Socket.io, validates and manages new client connections.

• Upon connection, the appropriate ServerRoom class is assigned to handle communication and game logic for the connected clients based on the room ID.

• ServerRoom manages game-specific logic, including chessboard state, moves, timers, and other related aspects.

Additionally, the server utilizes SQLite3 as the database for data storage, with Sequelize serving as the Object-Relational Mapping (ORM) tool.

Client

The client is a React application developed in TypeScript, serving as the user interface for ChessNowBot. Key components include:

1. React Chessboard and chess.js:

• The chessboard component is implemented using the react-chessboard package, providing an out-of-the-box, highly customizable solution with support for both Drag and Drop and click-based move mechanics.

• The chess.js library, is used for game logic.

2. GameClient and Socket.io Client:

• The GameClient class manages communication with the server and client-side game logic.

• Socket.io client is used to establish a real-time communication channel with the server.

3. Material UI for UI Design:

• The client UI is designed using Material UI, chosen for its high customizability, accessibility, and resemblance to the native Telegram client UI style.

API Definition

Communication between the server and the client is based on thr API that is defined in TypeScript types in the DataModel.ts file. These types specify the entities transferred between the server and the client. The API is documented using JSDoc comments within the DataModel.ts file.

Setup guide

Prerequisites

Ensure that your server environment meets the following requirements before setting up ChessNowBot:

Operating System:

• The application was tested on Ubuntu 22.04.3 LTS, but it should be also compatible with other operating systems.

Network Configuration:

• The server should have ports 80 and 443 accessible from the internet.

Domain Name:

• You need a domain name.

Node.js and npm:

• The server should have Node.js installed. The application was tested on Node.js v18.18.0. On Ubuntu Node.js could be installed from NodeSource Node.js Binary Distributions
• Ensure npm (Node Package Manager) is also installed.

Step 1: Obtain and configure bot and web app from @BotFather

• Start a conversation with @BotFather in Telegram.
• Send /newbot command to start creating your new bot.
• BotFather will prompt you to supply a name and a username for your bot. The name can be modified at a later time, but the username is permanent, so make your selection thoughtfully.
• BotFather will give you the token to access the HTTP API. Save it somewhere, you will need it at a later stage.
• Now, you need to configure the bot. Send /mybots command and select your newly created bot. Select Bot Settings -> Inline Mode -> Turn on. This is needed to allow your bot to work in inline mode.
• Then select << Back to Settings -> Inline Feedback -> 100%. This is needed for the bot to receive inline ChosenInlineResult updates. More about this.
• Optionally you can set other settings, such as bot picture, description, about text etc.
• Send /newapp command to start creating new web app attached to the bot.
• From the list below select the bot that you have just created.
• BotFather will ask you to enter some information about your app, for Web App URL enter: https://<YOUR-DOMAIN>/. Replace <YOUR-DOMAIN> with your domain name. For short name enter game.

Step 2: Setup ChessNowBot

• Download the source code:

git clone https://github.com/Quatern1on/ChessNowBot
cd ChessNowBot

• Install client and server dependencies:

cd server
npm install

cd ../client
npm install

• Create .env file in the client folder with the following content. Replace yourdomain.name with your domain name:

VITE_SERVER_URL=https://yourdomain.name

• Build client:

npm run build

• Build server:

cd ../server
npm run build

• Create a configuration file server/config/local.json5 with the following content, replace <URL> with url to your web app, like https://yourdomain.name/ (leading slash is important), it will probably be the same as the one you entered for Web App URL at Step 1. Replace <TOKEN> with bot token received from BotFather at step 1:

{
    webApp: {
        customize: {
            url: "<URL>",
        },
        game: {
            name: "game",
        }
    },
    bot: {
        token: "<TOKEN>",
    },
    gameServer: {
        gameModes: {
            bullet: {
                title: "Bullet (1|0)",
                gameRules: {
                    timer: true,
                    initialTime: 60,
                    timerIncrement: 0,
                },
            },
            blitz: {
                title: "Blitz (3|2)",
                gameRules: {
                    timer: true,
                    initialTime: 180,
                    timerIncrement: 2,
                },
            },
            rapid: {
                title: "Rapid (10|5)",
                gameRules: {
                    timer: true,
                    initialTime: 600,
                    timerIncrement: 5,
                },
            },
        },
    },
}

Step 3: Setup nginx

This guide assumes usage of nginx as a reverse proxy for the server, and hosting static files (client bundle). If you are setting up for the development environment, you might not need to install nginx.

• Install nginx:

sudo apt update
sudo apt install nginx

• Check that nginx is active and running:

sudo systemctl status nginx

• Allow inbound traffic on 443 port through your firewall configuration, this step is dependent on cloud provider, and may require adjustments within the virtual machine as well as through the cloud provider's dashboard.

• Create an Nginx server block for ChessNowBot:

sudo mkdir -p /var/www/ChessNowBot
sudo chown -R $USER:$USER /var/www/ChessNowBot
sudo chmod -R 755 /var/www/ChessNowBot

• Copy client build into newly created folder:

cd ..
cp -r ./client/build/* /var/www/ChessNowBot/

• Create a new configuration