A beautiful, feature-rich implementation of the classic Connect-5 (Gomoku) game with real-time multiplayer support, built with modern web technologies.

Play Now • Features • Installation • Usage • Multiplayer • Tech Stack

✨ Features

🎯 Game Modes

Local Play: Play against friends on the same device
Real-Time Multiplayer: Challenge players online with instant move synchronization
Multiple Board Sizes: Choose from 15×15, 20×20, 25×25, or 50×50 grids

🎨 Premium Design

Graphing Paper Aesthetic: Beautiful dark theme with clean lines
Smooth Animations: Polished piece placement and victory effects
Glassmorphism UI: Modern, translucent interface elements
Responsive Design: Works seamlessly on desktop and mobile devices

🌐 Multiplayer Features

Player Lobby: See all online players in real-time
Challenge System: Send and receive game invitations
Surrender Option: Forfeit games gracefully with confirmation
Rematch System: Instantly challenge the same opponent again
Reliable Connections: Auto-reconnect and state restoration
Player Statistics: Track wins, losses, and draws
Auto-Login: Username persistence across sessions
Profanity Filter: Safe and family-friendly usernames

🎲 Gameplay

8-Direction Win Detection: Horizontal, vertical, and diagonal
Turn-Based System: Clear turn indicators
Win Highlighting: Animated winning sequence display
Draw Detection: Automatic board-full detection
Score Tracking: Persistent score tracking in local and multiplayer modes

📸 Screenshots

Local Game Mode

Different Board Sizes

Victory Screen

🚀 Installation

Prerequisites

Node.js 18+ (Download)
PostgreSQL Database (Download)
Git (Download)

Quick Start

# Clone the repository
git clone https://github.com/DeNNiiInc/Connect-5.git
cd Connect-5

# Install dependencies
npm install

# Configure database
# 1. Ensure PostgreSQL is running and create the database:
#    CREATE DATABASE connect5;
# 2. Copy db.config.example.js to db.config.js
cp db.config.example.js db.config.js

# 3. Edit db.config.js with your PostgreSQL credentials
# 4. Run the SQL schema
psql -h HOST -U postgres -d connect5 -f postgres-schema.sql

# Start the server
npm start

The server will start on http://localhost:3000

For detailed setup instructions, see README_DB_CONFIG.md

🎮 Usage

Local Play

Open http://localhost:3000 in your browser
Click "🎮 Local Play"
Select your preferred board size (15×15, 20×20, 25×25, or 50×50)
Start playing! Player X goes first
Get 5 in a row to win (horizontal, vertical, or diagonal)

Multiplayer

Click "🌐 Multiplayer"
Enter your username (3-20 characters, family-friendly)
Select your preferred board size
Click "Challenge" next to any online player
Wait for them to accept
Game starts automatically!

Keyboard Shortcuts

Enter: Submit username in multiplayer mode
Click: Place piece on board
Refresh: Return to lobby after game ends

🌐 Multiplayer System

Architecture

┌─────────────┐         WebSocket          ┌──────────────┐
│   Client    │◄─────────────────────────►│   Server     │
│  (Browser)  │     Socket.io Events       │  (Node.js)   │
└─────────────┘                             └──────┬───────┘
                                                   │
                                                   ▼
                                            ┌──────────────┐
                                            │   Supabase   │
                                            │  PostgreSQL  │
                                            └──────────────┘

Database Schema

Players Table

Player information and statistics
Unique usernames with constraints
Win/Loss/Draw tracking

Active Sessions Table

Online player monitoring
Heartbeat-based connection tracking
Automatic cleanup of stale sessions

Games Table

Game state and history
Player assignments (X/O)
Winner recording

Game Moves Table

Complete move history
Position tracking for each move
Replay capability support

Real-Time Features

Instant Updates: Move synchronization in real-time
Challenge System: Send and accept game invitations
Player Presence: Live online/offline status
Disconnect Handling: 30-second grace period for reconnection
Auto-Reconnect: Seamless session restoration

🛠️ Tech Stack

Frontend

HTML5: Semantic markup
CSS3: Advanced styling with CSS Grid and Flexbox
Vanilla JavaScript: Pure ES6+ without frameworks
Socket.io Client: Real-time communication

Backend

Node.js: JavaScript runtime
Express.js: Web application framework
Socket.io: WebSocket library for real-time bidirectional communication
Supabase Client: PostgreSQL database client with real-time capabilities

Database

PostgreSQL: Robust open-source relational database
Connection Pooling: Efficient connection management
Native SQL: Direct PostgreSQL queries for performance

Dependencies

{
  "express": "^4.18.2",
  "socket.io": "^4.6.1",
  "pg": "^8.11.3",
  "bad-words": "^3.0.4",
  "cors": "^2.8.5",
  "nodemon": "^2.0.22"
}

📁 Project Structure

Connect-5/
├── 📄 index.html           # Main HTML file
├── 🎨 styles.css           # Game styling
├── 🎨 multiplayer-styles.css  # Multiplayer UI styles
├── 🎮 game.js              # Game logic (local & multiplayer)
├── 🌐 multiplayer.js       # Multiplayer client logic
├── 🖼️ Logo.png             # BCT logo
├── 🔧 server.js            # Express & Socket.io server
├── 💾 database.js          # PostgreSQL connection & queries
├── 🎯 gameManager.js       # Multiplayer game management
├── 📦 package.json         # Dependencies
└── 📚 README.md            # This file

⚙️ Configuration

Database Configuration

Create db.config.js from the example:

cp db.config.example.js db.config.js

Edit db.config.js:

module.exports = {
    HOST: 'your-postgres-host',
    USER: 'postgres',
    PASSWORD: 'your-database-password',
    DB: 'connect5',
    dialect: 'postgres',
    pool: { max: 5, min: 0, acquire: 30000, idle: 10000 }
};

See README_DB_CONFIG.md for detailed setup instructions.

Server Configuration

Edit server.js to change the port:

const PORT = process.env.PORT || 3000;

🚀 Production Deployment

For production deployment, use the automated deployment script:

sudo bash deploy.sh

The script will:

✅ Prompt for project directory
✅ Request PostgreSQL credentials
✅ Configure database connection
✅ Install dependencies
✅ Detect and configure web server (Nginx/Apache)
✅ Start Node.js server
✅ Test endpoints

See DEPLOYMENT.md for detailed deployment instructions.

🎯 Game Rules

Objective

Be the first player to get 5 pieces in a row (horizontally, vertically, or diagonally).

How to Play

Players take turns placing their pieces (X or O) on the board
Click any empty cell to place your piece
The game checks for wins in all 8 directions
First player to connect 5 wins!
If the board fills up with no winner, it's a draw

Winning Sequences

Horizontal: ●●●●●
Vertical: Stacked 5 pieces
Diagonal: 5 pieces in a diagonal line (both directions)

🔧 Development

Running in Development Mode

# Start with auto-reload
npm start

# The server uses nodemon for automatic restarts on file changes

Testing Multiplayer Locally

Open two browser windows/tabs
Navigate to http://localhost:3000 in both
Click "Multiplayer" in each window
Enter different usernames
Send a challenge from one window
Accept it in the other window
Play the game!

🐛 Troubleshooting

Connection Refused Error

Problem: Cannot connect to PostgreSQL database
Solution: Verify credentials in db.config.js and check PostgreSQL is running

Port Already in Use

Problem: Port 3000 is already occupied
Solution: Change the PORT in server.js or stop the other application

Players Not Showing in Lobby

Problem: Online players list is empty
Solution: Check database connection and ensure both users are logged in

Username Already Taken

Problem: Username registration fails
Solution: Try a different username or check the database for duplicates

Database Disconnected

Problem: Status bar shows "Disconnected"
Solution: Check db.config.js credentials and PostgreSQL server status

For more troubleshooting, see DEPLOYMENT.md

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by the classic Gomoku game
Built with ❤️ by Beyond Cloud Technology
Special thanks to the open-source community

📧 Contact

Beyond Cloud Technology

YouTube: @beyondcloudtechnology
Repository: DeNNiiInc/Connect-5

Made with 💜 by Beyond Cloud Technology

⭐ Star this repository if you found it helpful!

Languages

JavaScript 55.7%

CSS 19.2%

Shell 10.7%

HTML 10.2%

PowerShell 2.4%

Other 1.8%

README.md Unescape Escape

Connect-5 🎮