mirror of
https://github.com/DeNNiiInc/Connect-5.git
synced 2026-04-18 03:06:01 +00:00
Add comprehensive README with documentation and features
This commit is contained in:
361
README.md
Normal file
361
README.md
Normal file
@@ -0,0 +1,361 @@
|
|||||||
|
# Connect-5 🎮
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
[](https://nodejs.org/)
|
||||||
|
[](https://socket.io/)
|
||||||
|
[](https://www.mysql.com/)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
|
[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Multiplayer](#multiplayer) • [Tech Stack](#tech-stack)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✨ 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
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
### Local Game Mode
|
||||||
|
|
||||||
|
|
||||||
|
### Multiplayer Lobby
|
||||||
|
|
||||||
|
|
||||||
|
### Live Gameplay
|
||||||
|
|
||||||
|
|
||||||
|
### Board Size Options
|
||||||
|
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Installation
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- **Node.js** 18+ ([Download](https://nodejs.org/))
|
||||||
|
- **MySQL** 8.0+ ([Download](https://www.mysql.com/downloads/))
|
||||||
|
- **Git** ([Download](https://git-scm.com/))
|
||||||
|
|
||||||
|
### Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
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:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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](LICENSE) file for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🙏 Acknowledgments
|
||||||
|
|
||||||
|
- Inspired by the classic Gomoku game
|
||||||
|
- Built with ❤️ by [Beyond Cloud Technology](https://www.youtube.com/@beyondcloudtechnology)
|
||||||
|
- Special thanks to the open-source community
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📧 Contact
|
||||||
|
|
||||||
|
**Beyond Cloud Technology**
|
||||||
|
- YouTube: [@beyondcloudtechnology](https://www.youtube.com/@beyondcloudtechnology)
|
||||||
|
- Repository: [DeNNiiInc/Connect-5](https://github.com/DeNNiiInc/Connect-5)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
**Made with 💜 by Beyond Cloud Technology**
|
||||||
|
|
||||||
|
⭐ Star this repository if you found it helpful!
|
||||||
|
|
||||||
|
</div>
|
||||||
Reference in New Issue
Block a user