Snatch Game - Competitive Clicker

A real-time multiplayer competitive clicker game built with Colyseus.js and Vue 3.

Features

• 🎮 Real-time multiplayer gameplay
• 🏆 10-minute competitive clicking battles
• 👥 2 players per room with automatic matchmaking
• 🎯 Unique player naming system with auto-increment
• 🎛️ Admin dashboard for game management
• 📊 Real-time statistics and monitoring
• 🔄 Automatic reconnection support
• ⏸️ Pause/Resume/Restart game controls

Tech Stack

• Backend: Colyseus.js, Express, TypeScript
• Frontend: Vue 3, Vite, TypeScript
• Real-time: WebSockets
• Styling: Custom CSS

System Architecture

How It Works

The game uses a client-server architecture with WebSocket connections for real-time communication:

1. Connection Flow

Player → Lobby Room → Game Room → Game Session

1. Initial Connection: When a player opens the app, they automatically join the LobbyRoom
2. Name Assignment: Players receive a unique name (guest, guest-2, etc.) with auto-increment per unique base name
3. Matchmaking: Players click "Quick Play" to find or create a game room
4. Room Transition: Players leave the lobby and join a GameRoom (max 2 players)
5. Game Start: When 2 players are in a room, the game automatically starts

2. Room Management

LobbyRoom:

• Single shared room for all waiting players
• Manages unique player names
• Handles matchmaking requests
• Shows available game rooms
• Tracks which players are in games

GameRoom:

• Individual rooms with exactly 2 players maximum
• Manages game state (waiting, playing, paused, finished)
• 10-minute countdown timer
• Click counting and winner determination
• Auto-restart after game ends

3. State Synchronization

The game uses Colyseus Schema for state management:

GameState {
  players: Map<Player>    // Connected players
  gameStatus: string       // waiting|playing|paused|finished
  timeRemaining: number    // Seconds left in game
  winner: string          // Winner's name
}

Player {
  sessionId: string
  name: string
  clicks: number
  connected: boolean
}

State Updates:

• Server authoritative - only server can modify state
• Automatic synchronization to all clients
• Delta compression - only changes are sent
• 60Hz update rate for real-time feel

4. Communication Protocol

Client → Server Messages:

• setName: Change player name in lobby
• quickPlay: Request matchmaking
• click: Register a click in game
• joinRoom: Join specific room

Server → Client Messages:

• gameJoined: Room ID to join
• playerInfo: Player's session info
• gameStart: Game has started
• gameEnd: Game finished with results
• gamePaused: Game paused
• gameRestart: Game restarting

State Callbacks:

• onAdd: Player joined
• onRemove: Player left
• onChange: Property changed
• listen: Specific field updates

5. Name Management System

Base: "jose"
- First jose → "jose"
- Second jose → "jose-2"
- Third jose → "jose-3"

Base: "maria"
- First maria → "maria"
- Second maria → "maria-2"

• Names are managed by a singleton NameManager
• Each unique base name has its own counter
• Names are released when players disconnect
• Names persist when moving between rooms

6. Game Flow Sequence

1. Lobby Phase:

   Connect → Assign Name → Show Online Players → Wait for Action
   

2. Matchmaking:

   Quick Play → Find Available Room → No Room? Create New → Join Room
   

3. Waiting Phase:

   Join Room → Show "Waiting for opponent" → Display Players (1/2)
   

4. Game Phase:

   2 Players Connected → Start Timer → Enable Clicking → Count Clicks
   

5. End Phase:

   Timer Reaches 0 → Determine Winner → Show Results → Auto-restart in 5s
   

7. Reconnection Handling

• 30-second grace period for disconnected players
• Game pauses if a player disconnects during play
• Game resumes when player reconnects
• Maintains click count and game state

8. Admin Dashboard

The dashboard connects via HTTP REST API and WebSocket monitoring:

REST Endpoints (Port 3000):

• GET /api/rooms - List all active rooms
• GET /api/rooms/:id/stats - Get room statistics
• POST /api/rooms/:id/pause - Pause a game
• POST /api/rooms/:id/restart - Restart a game
• POST /api/rooms/:id/kick/:playerId - Kick a player

Real-time Monitoring:

• Total CCU (Concurrent Users)
• Active rooms and their status
• Player statistics per room
• Live game state updates

Installation

# Install all dependencies
npm run install:all

Development

# Start both server and client in development mode
npm run dev

This will start:

• Server on http://localhost:3000
• Client on http://localhost:5173

Environment Variables (Client)

Create client/.env (or copy client/.env.example) to configure endpoints:

VITE_WS_URL=ws://localhost:3000
VITE_API_URL=http://localhost:3000/api

For production over HTTPS, use wss:// for VITE_WS_URL and an HTTPS API base for VITE_API_URL.

URLs

• Game: http://localhost:5173
• Admin Dashboard: http://localhost:5173/dashboard
• Colyseus Monitor: http://localhost:3000/colyseus
• API Endpoints: http://localhost:3000/api

Project Structure

snatchgame/
├── server/                 # Backend Colyseus server
│   ├── src/
│   │   ├── rooms/         # Game and Lobby rooms
│   │   ├── schemas/       # State schemas
│   │   ├── utils/         # Utilities (name manager)
│   │   ├── adminApi.ts    # Admin REST API
│   │   └── index.ts       # Server entry point
│   └── package.json
│
├── client/                 # Frontend Vue application
│   ├── src/
│   │   ├── views/         # Vue components (Lobby, Game, Dashboard)
│   │   ├── services/      # Colyseus client service
│   │   ├── router/        # Vue Router
│   │   └── main.ts        # App entry point
│   └── package.json
│
└── shared/                 # Shared types between client and server
    └── types.ts

Game Rules

1. Players enter the lobby and choose a username
2. Click "Quick Play" to join or create a game room
3. Game starts when 2 players join a room
4. Players have 10 minutes to click as fast as possible
5. The player with the most clicks wins
6. Games automatically restart after finishing

Admin Dashboard

The admin dashboard provides:

• View all active rooms and their status
• Pause/Resume games in progress
• Restart games
• Kick players from rooms
• View real-time statistics
• Monitor server performance

API Endpoints

• GET /api/rooms - List all active rooms
• GET /api/rooms/:roomId/stats - Get room statistics
• POST /api/rooms/:roomId/pause - Pause a game
• POST /api/rooms/:roomId/resume - Resume a game
• POST /api/rooms/:roomId/restart - Restart a game
• POST /api/rooms/:roomId/kick/:playerId - Kick a player
• GET /api/stats - Get global server statistics