████████╗██╗ ██╗██████╗ ███████╗███████╗██╗ ██╗██╗███████╗████████╗
╚══██╔══╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔════╝██║ ██║██║██╔════╝╚══██╔══╝
██║ ╚████╔╝ ██████╔╝█████╗ ███████╗██║ █╗ ██║██║█████╗ ██║
██║ ╚██╔╝ ██╔═══╝ ██╔══╝ ╚════██║██║███╗██║██║██╔══╝ ██║
██║ ██║ ██║ ███████╗███████║╚███╔███╔╝██║██║ ██║
╚═╝ ╚═╝ ╚═╝ ╚══════╝╚══════╝ ╚══╝╚══╝ ╚═╝╚═╝ ╚═╝
A real-time multiplayer typing competition game using WebSockets with PostgreSQL.
- Overview
- Features
- Architecture
- Prerequisites
- Installation
- Development
- Playing the Game
- Technical Implementation
- Troubleshooting
- Future Improvements
- Contributing
- License
TypeSwift is a fast-paced multiplayer typing competition where players race to type words as quickly and accurately as possible. The game leverages WebSockets to provide real-time synchronization across all connected players, allowing you to see everyone's typing progress as it happens.
The game automatically assigns each player a unique name and avatar, eliminating the need for accounts or sign-ins. Players compete on a level playing field where typing speed and accuracy are the only factors that determine your ranking.
- Real-time Multiplayer: See other players' typing progress in real-time with animated progress bars
- Automatic Player Profiles: Each player gets assigned a random name and avatar tied to their device
- Competitive Gameplay: Race against others to type words the fastest
- Dynamic Word Progression: When the majority of players complete the current word, a new one automatically appears
- Live Leaderboard: Real-time updates showing the fastest typists and their WPM (words per minute)
- Word Per Minute Calculation: Accurate WPM metrics based on character count and completion time
- Device Persistence: Player stats and identity persist between sessions on the same device
- Responsive Design: Works on desktop and mobile devices
- No Account Required: Jump straight into gameplay without registration or login
TypeSwift uses a modern web architecture with:
+---------------+
| Web Client |
+-------+-------+
|
| WebSocket
|
+-------+-------+ +-------------+
| Node.js API | <---> | PostgreSQL |
+---------------+ +-------------+
- Frontend: Vite-powered React client that renders the UI and handles user input
- Backend: Node.js server with Socket.io for real-time communication
- Database: PostgreSQL with TypeORM for persistent data storage
- Real-time Development: Vite for fast, HMR-enabled frontend development
├── client/
│ ├── src/ # Client source code
│ │ ├── components/ # React components
│ │ └── main.jsx # Main client entry point
│ ├── public/ # Static web assets
│ │ └── index.html # Main HTML structure
│ └── vite.config.js # Vite configuration
├── server/
│ ├── src/ # Server source code
│ │ ├── controllers/# API controllers
│ │ ├── models/ # TypeORM models
│ │ ├── services/ # Business logic
│ │ └── index.js # Server entry point
│ └── package.json # Server dependencies
├── package.json # Project dependencies
└── README.md # Project documentation
- Node.js (v16 or later)
- PostgreSQL (v13 or later)
- Docker (optional, for containerized development)
- Clone the repository:
git clone https://github.com/yourusername/typeswift.git
cd typeswift- Install dependencies:
npm install- Set up the database:
# Create a PostgreSQL database
createdb typeswift- Configure environment variables:
Create a .env file in the root directory with the following variables:
# Database
DATABASE_URL=postgres://username:password@localhost:5432/typeswift
# Server
PORT=3000
NODE_ENV=development
- Start Redis and PostgreSQL:
# Using Docker (recommended)
docker compose up -d postgres
# Or run locally if installed
# PostgreSQL should be running as a service- Start the development server:
# Start both client and server in development mode
npm run dev-
Open your browser and navigate to http://localhost:5173
-
For a multiplayer experience, open the same URL in multiple browser windows or share with friends on the same network.
To customize the word list, modify the wordList.js file in the server directory:
// server/src/data/wordList.js
module.exports = [
"your",
"custom",
"words",
"here",
// ...more words
];- When you open the game, you'll automatically be assigned a random name and avatar.
- Wait for the current word to appear in the center of the screen.
- Type the word as quickly and accurately as possible in the input field.
- Watch your progress and other players' progress in real-time.
- When you complete the word correctly, your score and WPM will be calculated and added to the leaderboard.
- When the majority of players complete the word, a new one will appear automatically.
- Keep playing to improve your WPM score and climb the leaderboard!
The client uses React with Vite to:
- Connect to the server using Socket.io
- Render the UI and handle user input
- Calculate typing progress and WPM
- Update the display of other players' progress in real-time
- Manage the leaderboard based on player performance
Key components:
GameContainer: Main game component managing game stateWordDisplay: Shows the current word to typePlayerProgress: Visualizes typing progress for all playersLeaderboard: Shows rankings based on WPMInputField: Handles user typing input
The Node.js server with Socket.io:
- Manages WebSocket connections for real-time updates
- Handles player connections and disconnections
- Tracks typing progress for all connected players
- Persists player statistics in PostgreSQL using TypeORM
- Generates new words when the majority complete the current one
Key components:
- Models:
Word,Player,GameSession - Controllers:
gameController,playerController - Services:
wordService,progressTracker,statsCalculator
- Player loads the game and connects via Socket.io
- Server assigns a player ID and shares the current word
- As the player types, progress updates are sent to the server
- Server broadcasts these updates to all connected clients via WebSockets
- When a player completes a word, their stats are updated in PostgreSQL
- When the majority complete a word, the server generates a new one
- The cycle continues with the new word
- Build the client code:
npm run build-
The compiled files will be available in the
client/distdirectory. -
Start the production server:
npm run start- Ensure PostgreSQL is running before starting the server
- Check that the configured ports are not blocked by a firewall
- Try clearing your browser cache and reloading
- Make sure all dependencies are installed with
npm install - Verify environment variables are set correctly
- Check that Node.js version is compatible (v16+)
- If the game is lagging, try reducing the number of connected clients
- For best performance, use a modern browser like Chrome, Firefox, or Edge
- User Accounts: Optional accounts for persistent statistics across devices
- Custom Game Rooms: Create private games with friends
- Difficulty Levels: Word lists of varying difficulty
- Game Modes: Time attack, accuracy focus, or endurance modes
- Mobile Optimization: Better touch keyboard support for mobile devices
- Internationalization: Support for multiple languages
- Themes: Light/dark mode and custom themes
- Sound Effects: Audio feedback for typing and completion
Contributions are welcome! Here's how you can contribute:
- Fork the repository
- Create a new branch (
git checkout -b feature/your-feature) - Make your changes
- Commit your changes (
git commit -m 'Add some feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
MIT