42 Cursus - ft_transcendence

Team
Yavin Contré	Paul Salamé	Yanis Sabik

Technologies

Debian version : bookworm (12.5)

Python version : >=3.10.1

Django version : 4.2.11

PostgreSQL version : latest (currently 16.3)

Web version : HTML5 | CSS3 | JavaScript (latest)

Bootstrap version : v5.3.3

ThreeJS release : r166

JWT : Payload: custom | Encryption algorithm: HMACSHA256

Modules

Summary

Final Mark
$$\textbf{\Huge \color{green} ★★★ \ 125 \ ★★★}$$ $$/ 100$$

	Major Module amt.	Minor Module amt.	Total Score
Selected	$$12$$	$$5$$	$$\textbf{14.5}$$ $$/ 9.5$$
💯 Validated	$$12$$	$$5$$	$$\textbf{\color{green} 14.5}$$ $$/ 9.5$$

Important

•   Major module score: +1.0 / module

•   Major module score: +0.5 / module

•   Required Score: 7.0

•   Required Score to get all the bonuses: 9.5

Selected Modules

State	Class	Category	Module
✅	major	Web	Use a Framework as backend
✅	minor	Web	Use a front-end framework or toolkit
✅	minor	Web	Use a database for the backend
✅	major	User Management	Standard user management, authentication, users across tournaments
✅	major	User Management	Implementing a remote authentication
✅	major	Gameplay and user experience	Remote players
✅	major	Gameplay and user experience	Multiplayers (more than 2 in the same game)
✅	major	Gameplay and user experience	Add Another Game with User History and Matchmaking
✅	minor	Gameplay and user experience	Game Customization Options
✅	major	Gameplay and user experience	Live chat
✅	major	AI-Algo	Introduce an AI Opponent
✅	major	Cybersecurity	Implement Two-Factor Authentication (2FA) and JWT
✅	major	Devops	Designing the Backend as Microservices
✅	major	Graphics	Use of advanced 3D techniques
✅	minor	Accessibility	Expanding Browser Compatibility
✅	minor	Accessibility	Multiple language supports
✅	major	Server-Side Pong	Replacing Basic Pong with Server-Side Pong and Implementing an API

Module List

• Web

  • Major module: Use a Framework as backend.
  • Minor module: Use a front-end framework or toolkit.
  • Minor module: Use a database for the backend.
  • Major module: Store the score of a tournament in the Blockchain.

• User Management

  • Major module: Standard user management, authentication, users across tournaments.
  • Major module: Implementing a remote authentication.

• Gameplay and user experience

  • Major module: Remote players
  • Major module: Multiplayers (more than 2 in the same game).
  • Major module: Add Another Game with User History and Matchmaking.
  • Minor module: Game Customization Options.
  • Major module: Live chat.

• AI-Algo

  • Major module: Introduce an AI Opponent.
  • Minor module: User and Game Stats Dashboards

• Cybersecurity

  • Major module: Implement WAF/ModSecurity with Hardened Configuration and HashiCorp Vault for Secrets Management.
  • Minor module: GDPR Compliance Options with User Anonymization, Local Data Management, and Account Deletion.
  • Major module: Implement Two-Factor Authentication (2FA) and JWT.

• Devops

  • Major module: Infrastructure Setup for Log Management.
  • Minor module: Monitoring system.
  • Major module: Designing the Backend as Microservices.

• Graphics

  • Major module: Use of advanced 3D techniques.

• Accessibility

  • Minor module: Support on all devices.
  • Minor module: Expanding Browser Compatibility.
  • Minor module: Multiple language supports.
  • Minor module: Add accessibility for Visually Impaired Users.
  • Minor module: Server-Side Rendering (SSR) Integration.

• Server-Side Pong

  • Major module: Replacing Basic Pong with Server-Side Pong and Implementing an API.
  • Major module: Enabling Pong Gameplay via CLI against Web Users with API Integration.

[Major] Use a framework as backend

Backend used : Django (version 4.2.11)

Lang : Python (version >=3.10.1)

Main application : ./src/django/workspace/ft_django

Additional Application : ./src/django/workspace/ft_django : API, Authentication, Databases

Short explanation : The backend is developed using Django, a high-level Python web framework that encourages rapid and clean development. But beacause of the subject restrictions, we are using Django as a lite backend. The main purpose of it is to send a basic html base to the users and to provide an API to make the communication between the frontend and the database.

[Minor] Use a front-end framework or toolkit

Frontend add-on used : Bootstrap toolkit (version v5.3.3)

Lang : CSS3, JavaScript

Implemented in : ./src/nginx/templates/index.html

Short explanation : The frontend design is developed using Bootstrap, a free and open-source CSS/JS framework directed at responsive front-end web development. It contains some pretty design templates for typography, forms, buttons, navigation, and other interface components. We thank a lot the Bootstrap team for their amazing work. (They are the real MVP for letting us use a such great tool: we don't have to spend hours on the design part !)

[Minor] Use a database for the backend

Database used : PostgreSQL (version latest, currently 16.3)

Lang : Bash, Python (and no SQL !)

Implemented in : ./srcs/postgresql and ./src/django/workspace/api_app/models.py

Short explanation : A database is sooooo useful. We all know that. Then wich one to choose ? The most used ? MySQL ? Nooo.... too easy. The subject is asking for a challenge. So we decided to use PostgreSQL. It is an object-relational database system that uses and extends the SQL language combined with many features that safely store and scale the most complicated data workloads. To use it, so simple: use Python. A table is basically a class, a row is an instance of the class, and a column is an attribute of the class. And that's it ! Django will do the rest. You can now store and retrieve data from the database. It's like magic.

[Major] Standard user management, authentication, users across tournaments

The standard user management feels mandatory. Of course our user should behave and be managed like .. real users !

That is why :

• Users can subscribe to the website in a secure way. (see more)
• Registered users can log in in a secure way. (see more)
• Users can select a unique display name to play the tournaments. (their username)
• Users can update their information. (route: /settings)
• Users can upload an avatar, with a default option if none is provided. (route: /settings)
• Users can add others as friends and view their online status.
• User profiles display stats, such as wins and losses. (route: /profile/<id>)
• Each user has a Match History including 1v1 games, dates, and relevant details, accessible to logged-in users. (route: /profile/<id>)

[Major] Implementing a remote authentication

TODO

[Major] Remote players

Once more, the remote players are a must-have. We want to play with our friends, even if they are not in the same room as us. That's why we have implemented the remote players feature. Django is made to be able to handle multiple requests at the same time. So it was not that hard to implement this feature.

[Major] Multiplayers (more than 2 in the same game)

Multiplayer games is one of the only "original" choice we made. We wanted to make a game where at least a dozen of players could play at the same time, or maybe more ? How about with n players ?
How did we manage to do that ? Well, instead of playing in a basic rectangle arena, we decided to make a regular polygonal one. Obviously, the number of sides of the polygon is the number of players.
With the graphics technology we used, we were able to make an up to 30 players game (without lag) !

[Major] Add Another Game with User History and Matchmaking

This feature was tough to implement. Because of the modules Multiplayers (more than 2 in the same game), Use of advanced 3D techniques and Replacing Basic Pong with Server-Side Pong and Implementing an API, the amount of work was huge.
So instead of making a whole new game physics engine, we decided to make, no one, but two new game modes ! We are proud to present you :

• First To Mode (FT) : The first player to reach the score limit wins the game.
• Time Out Mode (TO) : The player with the highest score when the time is over wins the game.
• Battle Royale Mode (BR) : The last player alive wins the game.

For the user history part, everything is stored in the database. The user can see his stats, his match history, and more in his profile page (route /profile/<id>).

Finally, for the matchmaking part, we decided to make a simple matchmaking system. The player can choose to join a random existing game.
◦ If multiple games are found, the player will join the game where the users have the closest winrate to his, ensuring a fair and balanced match.
◦ If no game is found, the player will create a new game and wait for other players to join.

The matchmaking system follows the following math :

$${\large \text{PlayerWins} \ = P_w }$$

$${\large \text{PlayerLosses} \ = P_l }$$

$${\large \text{PlayerWinrate} \ = P_r = \frac{P_w}{P_w + P_l} }$$

$${\large \text{GamePlayerCount} \ = G_{pc} }$$

$${\large \text{GameAverageRatio} \ = G_r = \frac{\sum_{i = 1}^{G_{pc}} r\left(G_i\right)}{G_{pc}} }$$

$${\large \text{Matchmaking} \ : \ \text{Smallest} \ G \ni \left| P_r - G_r \right|, \forall G \in \ \text{AvailableGames} }$$

To put it in a nutshell, we follow these goals :

• Develop a new, engaging game to diversify the platform’s offerings and entertain users.
• Implement user history tracking to record and display individual user’s gameplay statistics.
• Create a matchmaking system to allow users to find opponents and participate in fair and balanced matches.
• Ensure that user game history and matchmaking data are stored securely and remain up-to-date.
• Optimize the performance and responsiveness of the new game to provide an enjoyable user experience. Regularly update and maintain the game to fix bugs, add new features, and enhance gameplay.

[Minor] Game Customization Options

On each game creation, the player will meet a configuration page where he can choose a plethora of options to customize his game.

• Game Mode : Either First To, Time Out, or Battle Royale.
• Number of Players : From 2 to 30. Determines the shape of the arena.
• Ball Speed : Either Slow, Normal, or Fast. Affects the starting velocity AND the acceleration of the rebounds.
• Theme : 4 themes available. Changes the color, the style and the ambiance of the arena and the paddles.
• [FT Only] Score Limit : Determines the score limit to win the game.
• [TO Only] Time Limit : Determines the duration of the game.

To conclude, we :

• Offer customization features, such as power-ups, attacks, or different maps, that enhance the gameplay experience.
• Allow users to choose a default version of the game with basic features if they prefer a simpler experience.
• Ensure that customization options are available and applicable to all games offered on the platform.
• Implement user-friendly settings menus or interfaces for adjusting game parameters.
• Maintain consistency in customization features across all games to provide a unified user experience.

[Major] Live chat

TODO

[Major] Introduce an AI Opponent

TODO

[Major] Implement Two-Factor Authentication (2FA) and JWT

TODO

[Major] Designing the Backend as Microservices

Microservices set up with : Docker (docker-compose) (version latest)

OS used for the containers : Debian (version bookworm (12.5))

Implemented in : ./srcs

Compose file : ./srcs/docker-compose.yml

Short explanation : The backend is designed as microservices. Each service is a container. We separated the project into 3 main parts, our services :

• PostgreSQL : The database service. (mounted on ./srcs/postgresql)

• Django : The main backend service. (mounted on ./srcs/django)

• Nginx : The frontend service. (mounted on ./srcs/nginx)

[Major] Use of advanced 3D techniques

Advanced 3D librairy used : ThreeJs (release r166)

Lang : JavaScript

Implemented in : ./src/nginx/static/js/pong_game

[Minor] Expanding Browser Compatibility

We are proud to announce that our website is compatible with every nowadays browser. We have tested it on the most used ones such as Chrome, Firefox, Safari, Edge. We are using the latest technologies, so we are sure that it will work on your computer too. If not, please let us know. We will do our best to fix it. (^^')

[Minor] Multiple language supports

Thanks to the 42 student community, we managed to make our website available in multiple languages. We are proud to present you the 9 following languages :

• English (en) : The default language. (./src/nginx/static/lang/en.json)

• French (fr) : The language of love. (./src/nginx/static/lang/fr.json)

• Spanish (es) : The language of the sun. (./src/nginx/static/lang/es.json)

• German (de) : The language of the beer. (./src/nginx/static/lang/de.json)

• Mandarin (cn) : The language of the future. (./src/nginx/static/lang/cn.json)

• Japanese (jp) : The language of the samurai. (./src/nginx/static/lang/jp.json)

• Russian (ru) : The language of the cold. (./src/nginx/static/lang/ru.json)

• Egiptian (eg) : The language of the desert. (./src/nginx/static/lang/eg.json)

• Georgian (ka) : The language of the mountains. (./src/nginx/static/lang/ka.json)

[Major] Replacing Basic Pong with Server-Side Pong and Implementing an API

TODO

Main file tree

.
├── srcs/
│   ├── postgresql/
│   │   ├── ...
│   │   └── Dockerfile
│   ├── django/                   # [[ BACKEND ]]
│   │   ├── workspace/
│   │   │   ├── api_app/          # API, Authentication, Databases
│   │   │   │   ├── views/
│   │   │   │   │   └── ...
│   │   │   │   ├── auth.py
│   │   │   │   ├── jwt.py
│   │   │   │   ├── models.py     # DB configuration
│   │   │   │   ├── urls.py
│   │   │   │   └── ...
│   │   │   ├── ft_django/        # Core of the django project
│   │   │   │   ├── game_engine/
│   │   │   │   │   └── ...
│   │   │   │   ├── chat_socket.py
│   │   │   │   ├── pong_socket.py
│   │   │   │   ├── settings.py
│   │   │   │   ├── urls.py
│   │   │   │   └── ...
│   │   │   └── manage.py
│   │   ├── ...
│   │   └── Dockerfile
│   ├── nginx/                    # [[ FRONTEND ]]
│   │   ├── static/
│   │   │   ├── css/
│   │   │   │   └── ...
│   │   │   ├── img/
│   │   │   │   └── ...
│   │   │   ├── js/               # Website content (SPA)
│   │   │   │   ├── components/
│   │   │   │   │   └── ...
│   │   │   │   ├── pages/
│   │   │   │   │   └── ...
│   │   │   │   ├── pong_game/
│   │   │   │   │   └── ...
│   │   │   │   └── ...
│   │   │   ├── font/             # Fonts (.ttf files)
│   │   │   │   └── ...
│   │   │   └── lang/             # Languages (.json files)
│   │   │       └── ...
│   │   ├── templates/
│   │   │   └── index.html
│   │   ├── ...
│   │   └── Dockerfile
│   ├── .env
│   ├── secrets.env               # Credentials (API keys)
│   └── docker-compose.yml
├── Makefile
└── README.md