Real-time multiplayer typing competition platform. Host a game, invite friends, and compete in high-speed typing races with live leaderboards.
- Overview
- Features
- Tech Stack
- Installation
- Quick Start
- Game Rules
- Architecture
- API Events
- Configuration
- License
- Attribution
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
- โ 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
| 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 |
- Python 3.10.3
- pip package manager
- Modern browser (Chrome, Firefox, Safari, Edge)
# 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-engineiotyperace-arena/
โโโ server.py
โโโ templates/
โ โโโ index.html
โโโ static/
โ โโโ style.css
โ โโโ script.js
โโโ README.md
โโโ LICENSE
python server.pyServer starts on http://0.0.0.0:5555
Navigate browser to http://localhost:5555
- First Connection = Host: First player auto-promoted to host role
- Typing Challenge: Players race to accurately type displayed text
- Error Threshold: 5+ errors trigger automatic elimination
- Ranking Algorithm: Sorted by WPM (descending), eliminated players listed separately
- Early Submission: Players can finish early if text complete with <5 errors
- Host Authority: Only host can initiate/terminate games
- Nickname Lockdown: Names frozen after game start
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
Connection โ Waiting Room โ Countdown โ Active Typing
โ โ
Player (Input) Host (Monitor)
โ โ
Result Submission Progress Tracking
โ โ
TALLYING โ RESULTS โ Leaderboard Display
| 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 |
| Event | Payload | Purpose |
|---|---|---|
update_state |
game_state |
Full state broadcast to all |
timer_update |
{remaining} |
Server time synchronization |
Modify in server.py:
COUNTDOWN_TIME = 10 # Countdown (seconds)
GAME_DURATION = 120 # Typing window (seconds)
TALLY_DURATION = 10 # Results display (seconds)Update TEST_QUOTES in server.py:
TEST_QUOTES = [
"Your custom typing challenge text...",
"Another competitive typing sample...",
]if __name__ == '__main__':
socketio.run(
app,
host='0.0.0.0', # Network accessibility
port=5555, # Port number
debug=True # Development mode
)Tracked per player:
- WPM: Characters typed / (time elapsed / 60)
- Accuracy: (Correct characters / Total typed) ร 100
- Mistakes: Count of incorrect inputs
- Status: Active or Eliminated
This project is licensed under MIT License with Attribution Requirements.
See LICENSE for full terms.
โ Permitted:
- Commercial and private use
- Modification and redistribution
- Derivative works
- Attribution to original authors
- Modification documentation
- Source code link in distributions
- License inclusion
- 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
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
Copyright ยฉ 2025 Kangwoo Kim
This project is licensed under the MIT License (with attribution required).
Report bugs or suggest features: GitHub Issues
- Socket.IO: https://socket.io/docs/
- Flask: https://flask.palletsprojects.com/
- Eventlet: https://eventlet.net/
- Python 3.10: https://docs.python.org/3.10/
Made in Uganda โข KOICA Volunteer Program