Connect-5/README.md

Connect-5 🎮

Premium Real-Time Multiplayer Gomoku Game

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
• Player Statistics: Track wins, losses, and draws
• Auto-Login: Username persistence across sessions
• Session Management: Automatic reconnection handling
• 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)
• MySQL 8.0+ (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 (edit database.js with your credentials)
# Update the following in database.js:
# - host: 'your-mysql-host'
# - user: 'your-database-user'
# - password: 'your-password'
# - database: 'your-database-name'

# Start the server
npm start

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

---

🎮 Usage

Local Play

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

Multiplayer

1. Click "🌐 Multiplayer"
2. Enter your username (3-20 characters, family-friendly)
3. Select your preferred board size
4. Click "Challenge" next to any online player
5. Wait for them to accept
6. 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)   │
└─────────────┘                             └──────┬───────┘
                                                   │
                                                   ▼
                                            ┌──────────────┐
                                            │    MySQL     │
                                            │   Database   │
                                            └──────────────┘

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
• MySQL2: MySQL database driver with promises

Database

• MySQL: Relational database for persistent storage
• Connection Pooling: Optimized database connections

Dependencies

{
  "express": "^4.18.2",
  "socket.io": "^4.6.1",
  "mysql2": "^3.2.0",
  "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          # MySQL connection & queries
├── 🎯 gameManager.js       # Multiplayer game management
├── 📦 package.json         # Dependencies
└── 📚 README.md            # This file

---

⚙️ Configuration

Database Configuration

Edit database.js:

const dbConfig = {
    host: 'your-mysql-host',      // MySQL server address
    user: 'your-database-user',    // Database username
    password: 'your-password',     // Database password
    database: 'your-database-name',// Database name
    waitForConnections: true,
    connectionLimit: 10,
    queueLimit: 0
};

Server Configuration

Edit server.js to change the port:

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

---

🎯 Game Rules

Objective

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

How to Play

1. Players take turns placing their pieces (X or O) on the board
2. Click any empty cell to place your piece
3. The game checks for wins in all 8 directions
4. First player to connect 5 wins!
5. 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

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

---

🐛 Troubleshooting

Connection Refused Error

Problem: Cannot connect to MySQL database
Solution: Ensure MySQL is running and credentials in database.js are correct

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

---

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. 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!