Minechaser (https://minechaser.com)

Minechaser is a web-based multiplayer game based on mechanics known from the classical Minesweeper. Instead of clicking on the board though, the players compete in real time by walking around the board and marking mines with flags. Every correctly placed flag is awarded with a point. Placing flags incorrectly results with an increasing penalty. Player who survives and gains most points wins. Bonuses can be collected to boost one's progress or impede the opponents.

Running locally

Prerequisites: Python v3.10, pip v23, Node.js v18, npm v10

npm install
pip install -r requirements.txt
npm start
cd api && gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 --bind 0.0.0.0:5000 app:socketio_app

Then visit http://localhost:3000 in your browser.

Features

• Three game modes
  • Online game, where player joins a global queue to play with other players on the web
  • Private game, where a link can be shared among a group of friends
  • Single-player game
• User preferences
  • Username, visible to other players
  • Other preferences taking effect locally: disable music, disable sound effects, enable color-blind mode
• In-game features:
  • Real-time updates for players' score, elapsed time, remaining mine count
  • Keyboard controls for desktop users and on-screen controls for touch-screen users, detected automatically
  • Players who stepped on a mine can spectate it or play again
• Game summary screen with players' scores and simple statistics about the game
  • Players in private game are proposed to play against each other again
  • From here players can share the game if they liked it
• Responsive design for all screen sizes

Implementation

Tech Stack

• React v18 with React Router v6, TypeScript v4.9 and ESLint v8
• Build system: Vite v4
• CSS preprocessors and libraries:
  • SASS
  • PostCSS with Autoprefixer and Preset Env (for converting some of the modern CSS syntax for older browsers)
  • PicoCSS v2 - a minimal CSS library leveraging semantic HTML to apply styles
  • Tippy.js for minimal tooltips
• Python v3.10
  • Gunicorn - WSGI HTTP Server
  • Gevent - coroutine-based networking library with Websocket support
  • Bottle.py - for minimal HTTP request handling
  • APScheduler library for scheduling game events
• Websocket communication implemented with socket.io library and its Python counterpart on the server, python-socketio
• Deployed on a DigitalOcean Droplet (VPS) with Nginx as an HTTP server

Selected implementation details

React, JavaScript

• State fully managed using built-in React features: useState hook and contexts
• Component lazy-loading and preloading used to minimize initial bundle size and improve perceived performance (e.g. some components are preloaded during animations)
• Custom hooks used to abstract separate reusable and/or complex logic away from components
• Physical/touchscreen keyboard detection implemented by checking time elapsed between keydown and keyup events
• Player ID and preferences are stored in localStorage, conserving the player's profile for the next time they play
• Optimistic UI updates used for a smoother user experience, minimizing the impact of latency in response time
• Integration with Rollbar to view errors, and prerender.io to send pre-built version of the website to web crawlers

CSS

• Fully responsive design implemented using media queries
• PicoCSS used to leverage semantic HTML elements (like dialog, article, details, progress, [role]) to apply styles
• Container queries used to appropriately size elements within a cell during the game
• OKLCH color space used to pick colors of identical perceived brightness
• CSS Layers used to keep selector specificity as low as possible, keeping the stylesheets clean

Python

• Code arranged in views, services and models
• State of games and information about players is stored in-memory using a dict. In case of server restart (e.g. during a deployment), information about players is serialized, stored and deserialized
• jsonpickle library is used to serialize parts of the state of the game when it is sent to the client. Inclusion of sensitive information is avoided thanks to implementing custom __getstate__ magic method on the model classes.
• Very primitive queue algorithm is used in matchmaking. Players are dequeued when there are 4 players in the queue (maximum number in a game) or with at least two players, the longest waiting player is in the queue for at least 15 seconds.
• APScheduler library is used to schedule future events, like player dequeuing, timing the start of the game, delete finished games, placing bonuses on the board etc.
• The server runs in a single thread, utilizing gevent for spawning greenlets - lightweight coroutines for in-process concurrent execution

Communication and networking

• Socket.io is used for communication, providing useful abstractions and mechanisms like broadcasting, rooms, auto-reconnections etc.
• Difference between client time and server time is calculated when user opens the website and accounted for in further calculations
• Primitive admin console implemented to remotely access and alter the state (password-protected)