Skip to content

About

Real-time WebSocket-based typing battle platform. Built for the KOICA Mpigi IT Competition (Nov 2025).

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

โŒจ๏ธ TypeRace Arena

Real-time multiplayer typing competition platform. Host a game, invite friends, and compete in high-speed typing races with live leaderboards.

Python JavaScript Flask License


๐Ÿ“‹ Table of Contents


๐ŸŽฎ Overview

TypeRace Arena is a competitive real-time multiplayer typing game built with Flask and WebSocket. Players join a lobby, wait for the host to start, and race against each other to type given text accurately and quickly.

Key Capabilities:

  • Real-time synchronization via WebSocket (Socket.IO)
  • Host-based game management with automatic host reassignment
  • Performance metrics: WPM (Words Per Minute), Accuracy, Error tracking
  • Interactive keyboard visualization with live key feedback
  • Dynamic leaderboard with ranking and statistics
  • Error elimination system: Automatic disqualification at 5+ mistakes

โœจ Features

  • โœ… Multiplayer Lobby System: Join seamlessly, real-time nickname updates
  • โœ… Host Controls: Game initiation and lifecycle management by host only
  • โœ… Spectator Mode: Host monitors all players in real-time
  • โœ… Live Typing Stats:
    • Real-time WPM calculation
    • Accuracy percentage tracking
    • Live error detection
    • Automatic word progression
  • โœ… Visual Keyboard: Interactive QWERTY layout with keystroke feedback
  • โœ… Results Dashboard: Ranked leaderboard after each session
  • โœ… Automatic Error Handling: Player elimination, host reassignment on disconnect
  • โœ… Responsive Layout: Desktop and tablet optimized
  • โœ… Configurable Timing: Adjustable countdown, game duration, results window

๐Ÿ› ๏ธ Tech Stack

Layer Technology
Backend Python 3.10.3, Flask, Flask-SocketIO, Eventlet
Frontend HTML5, CSS3, JavaScript (ES6+)
Real-time Communication WebSocket (Socket.IO)
Async Runtime Eventlet greenlets

๐Ÿ“ฆ Installation

Prerequisites

  • Python 3.10.3
  • pip package manager
  • Modern browser (Chrome, Firefox, Safari, Edge)

Setup

# Clone repository
git clone https://github.com/kangwoo-kim/typerace-arena.git
cd typerace-arena

# Create virtual environment
python3.10 -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install dependencies
pip install flask flask-socketio eventlet python-socketio python-engineio

๐Ÿš€ Quick Start

Directory Structure

typerace-arena/
โ”œโ”€โ”€ server.py
โ”œโ”€โ”€ templates/
โ”‚   โ””โ”€โ”€ index.html
โ”œโ”€โ”€ static/
โ”‚   โ”œโ”€โ”€ style.css
โ”‚   โ””โ”€โ”€ script.js
โ”œโ”€โ”€ README.md
โ””โ”€โ”€ LICENSE

Run Server

python server.py

Server starts on http://0.0.0.0:5555

Access Application

Navigate browser to http://localhost:5555


๐Ÿ“ Game Rules

  1. First Connection = Host: First player auto-promoted to host role
  2. Typing Challenge: Players race to accurately type displayed text
  3. Error Threshold: 5+ errors trigger automatic elimination
  4. Ranking Algorithm: Sorted by WPM (descending), eliminated players listed separately
  5. Early Submission: Players can finish early if text complete with <5 errors
  6. Host Authority: Only host can initiate/terminate games
  7. Nickname Lockdown: Names frozen after game start

๐Ÿ—๏ธ Architecture

Backend State Machine

Client Connect
    โ†“
Register in game_state
    โ†“
First? โ†’ Assign Host
    โ†“
Broadcast to all clients
    โ†“
Host Triggers Start
    โ†“
COUNTDOWN โ†’ IN_PROGRESS โ†’ TALLYING โ†’ RESULTS
    โ†“
Calculate rankings, eliminate errors
    โ†“
Distribute results

Frontend Flow

Connection โ†’ Waiting Room โ†’ Countdown โ†’ Active Typing
    โ†“                                        โ†“
    Player (Input)                     Host (Monitor)
    โ†“                                        โ†“
    Result Submission              Progress Tracking
    โ†“                                        โ†“
    TALLYING โ†’ RESULTS โ†’ Leaderboard Display

๐Ÿ“ก API Events

Client โ†’ Server

Event Payload Purpose
start_game โ€” Host initiates countdown
force_end_game โ€” Host terminates game immediately
submit_result {wpm, accuracy, mistakes} Player submits score
player_progress {progress} Player sends typing progress (0-100%)
change_nickname {nickname} Player updates displayed name
return_to_lobby โ€” Host resets to waiting room

Server โ†’ Client

Event Payload Purpose
update_state game_state Full state broadcast to all
timer_update {remaining} Server time synchronization

โš™๏ธ Configuration

Game Timing

Modify in server.py:

COUNTDOWN_TIME = 10   # Countdown (seconds)
GAME_DURATION = 120   # Typing window (seconds)
TALLY_DURATION = 10   # Results display (seconds)

Text Pool

Update TEST_QUOTES in server.py:

TEST_QUOTES = [
    "Your custom typing challenge text...",
    "Another competitive typing sample...",
]

Server Configuration

if __name__ == '__main__':
    socketio.run(
        app,
        host='0.0.0.0',    # Network accessibility
        port=5555,         # Port number
        debug=True         # Development mode
    )

๐Ÿ“Š Performance Metrics

Tracked per player:

  • WPM: Characters typed / (time elapsed / 60)
  • Accuracy: (Correct characters / Total typed) ร— 100
  • Mistakes: Count of incorrect inputs
  • Status: Active or Eliminated

๐Ÿ“„ License

This project is licensed under MIT License with Attribution Requirements.

See LICENSE for full terms.

License Summary

โœ… Permitted:

  • Commercial and private use
  • Modification and redistribution
  • Derivative works

โš ๏ธ Required:

  • Attribution to original authors
  • Modification documentation
  • Source code link in distributions
  • License inclusion

๐Ÿ‘ฅ Attribution

Original Developer

  • Kangwoo Kim (Mutabi Jake)
    • Backend: Architecture, game logic, server/network management
    • Frontend: UI/UX, client-side interaction
    • Affiliation: Kangnam University โ€“ AI Department
    • Current: KOICA Project Volunteer (Uganda)
    • GitHub: https://github.com/applelog

Attribution Requirements

When using, modifying, or redistributing this software, please include:

TypeRace Arena
Original Developer: Kangwoo Kim (Mutabi Jake)
Source: https://github.com/applelog/typerace-arena
License: MIT License with Attribution

Legal Notice

Copyright ยฉ 2025 Kangwoo Kim
This project is licensed under the MIT License (with attribution required).


๐Ÿ“ฎ Issues & Contributions

Report bugs or suggest features: GitHub Issues


๐ŸŽ“ Technical References


Made in Uganda โ€ข KOICA Volunteer Program

About

Real-time WebSocket-based typing battle platform. Built for the KOICA Mpigi IT Competition (Nov 2025).

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages