dennii/Connect-5
1
0
Fork 0
mirror of https://github.com/DeNNiiInc/Connect-5.git synced 2026-04-17 22:46:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Major README update with Surrender, Rematch, and Auto-Start details

Browse Source
This commit is contained in:
DeNNiiInc
2025-12-22 19:48:16 +11:00
parent 632dedcf57
commit c03cd62dad
1 changed files with 71 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

348
README.md
View File

@@ -13,7 +13,7 @@ A beautiful, feature-rich implementation of the classic Connect-5 (Gomoku) game
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-3ECF8E.svg)](https://postgresql.org/) [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-3ECF8E.svg)](https://postgresql.org/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[Play Now](https://connect5.beyondcloud.technology/) • [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Multiplayer](#multiplayer) • [Tech Stack](#tech-stack) [Play Now](https://connect5.beyondcloud.technology/) • [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Multiplayer](#multiplayer) • [Deployment](#production-deployment)
</div> </div>
@@ -22,32 +22,25 @@ A beautiful, feature-rich implementation of the classic Connect-5 (Gomoku) game
## ✨ Features ## ✨ Features
### 🎯 Game Modes ### 🎯 Game Modes
- **Local Play**: Play against friends on the same device - **Local Play**: Play against friends on the same device.
- **Real-Time Multiplayer**: Challenge players online with instant move synchronization - **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 - **Multiple Board Sizes**: Choose from 15×15, 20×20, 25×25, or 50×50 grids.
### 🏳️ Surrender & Rematch (NEW)
- **Surrender Option**: Realizing you're beaten? gracefully forfeit the game with the "Surrender" button to save time.
- **Instant Rematch**: After a game ends, challenge your opponent to a rematch instantly from the Game Over screen.
- **Seamless Flow**: Both players are kept in sync during surrender or rematch negotiations.
### 🛡️ Reliability (NEW)
- **Smart Reconnects**: If you lose internet or refresh the page, you are **instantly placed back in your active game** with the board restored.
- **Game State Protection**: No more abandoned games due to minor connection blips.
- **Race Condition Handling**: Robust server-logic preventing errors during rapid interactions.
### 🎨 Premium Design ### 🎨 Premium Design
- **Graphing Paper Aesthetic**: Beautiful dark theme with clean lines - **Graphing Paper Aesthetic**: Beautiful dark theme with clean lines.
- **Smooth Animations**: Polished piece placement and victory effects - **Smooth Animations**: Polished piece placement and victory effects.
- **Glassmorphism UI**: Modern, translucent interface elements - **Glassmorphism UI**: Modern, translucent interface elements.
- **Responsive Design**: Works seamlessly on desktop and mobile devices - **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
--- ---
@@ -64,6 +57,8 @@ A beautiful, feature-rich implementation of the classic Connect-5 (Gomoku) game
### Victory Screen ### Victory Screen
![Victory Screen](screenshots/victory-screen.png) ![Victory Screen](screenshots/victory-screen.png)
*(New screenshots for Surrender/Rematch UI coming soon)*
</div> </div>
--- ---
@@ -86,13 +81,13 @@ cd Connect-5
npm install npm install
# Configure database # Configure database
# 1. Ensure PostgreSQL is running and create the database: # 1. Create database: CREATE DATABASE connect5;
# CREATE DATABASE connect5; # 2. Setup config:
# 2. Copy db.config.example.js to db.config.js
cp db.config.example.js db.config.js cp db.config.example.js db.config.js
# 3. Edit db.config.js with your credentials
# 3. Edit db.config.js with your PostgreSQL credentials # 4. Initialize Database Schema
# 4. Run the SQL schema # (Check update-dbschema.js if psql is not available)
psql -h HOST -U postgres -d connect5 -f postgres-schema.sql psql -h HOST -U postgres -d connect5 -f postgres-schema.sql
# Start the server # Start the server
@@ -101,259 +96,82 @@ npm start
The server will start on **http://localhost:3000** The server will start on **http://localhost:3000**
For detailed setup instructions, see [README_DB_CONFIG.md](README_DB_CONFIG.md)
--- ---
## 🎮 Usage ## 🎮 Usage
### Local Play ### Multiplayer Instructions
1. Open **http://localhost:3000** in your browser 1. Click **"🌐 Multiplayer"**.
2. Click **"🎮 Local Play"** 2. Enter your username (3-20 characters).
3. Select your preferred board size (15×15, 20×20, 25×25, or 50×50) 3. **Lobby**: See online players and their stats (Wins/Losses).
4. Start playing! Player X goes first 4. **Challenge**: Click "Challenge" next to a player.
5. Get 5 in a row to win (horizontal, vertical, or diagonal) 5. **Game On**: Once accepted, the board loads for both of you.
### Multiplayer ### In-Game Controls
1. Click **"🌐 Multiplayer"** - **Place Piece**: Click any empty intersection.
2. Enter your username (3-20 characters, family-friendly) - **Surrender**: Click the "Surrender" button (Game Controls area) to forfeit.
3. Select your preferred board size - **Rematch**: After the game, click "Challenge Again" to keep playing the same opponent.
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 ## 🚀 Production Deployment
### Architecture We support **Zero-Downtime Reliability** and **Auto-Start**.
``` ### 1. Automated Deployment
┌─────────────┐ WebSocket ┌──────────────┐ Use our deployment script to setup Nginx/Apache and Node.js automatically:
│ Client │◄─────────────────────────►│ Server │
│ (Browser) │ Socket.io Events │ (Node.js) │ ```bash
└─────────────┘ └──────┬───────┘ sudo bash deploy.sh
│
▼
┌──────────────┐
│ Supabase │
│ PostgreSQL │
└──────────────┘
``` ```
### Database Schema ### 2. Auto-Start on Reboot (Systemd)
Never worry about server restarts again. Install the systemd service:
**Players Table** ```bash
- Player information and statistics sudo bash setup-auto-start.sh
- Unique usernames with constraints ```
- Win/Loss/Draw tracking *This ensures the app starts automatically and waits for the database to be ready.*
**Active Sessions Table** ### 3. Auto-Deploy (Git Hooks)
- Online player monitoring Enable automatic updates when you `git pull`:
- Heartbeat-based connection tracking
- Automatic cleanup of stale sessions
**Games Table** ```bash
- Game state and history bash setup-auto-deploy.sh
- Player assignments (X/O) ```
- Winner recording *This installs a hook to restart the service automatically after code changes.*
**Game Moves Table** See [DEPLOYMENT.md](DEPLOYMENT.md) for full details.
- 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 ## 🛠️ Tech Stack
### Frontend ### Frontend
- **HTML5**: Semantic markup - **HTML5/CSS3**: Custom Glassmorphism design
- **CSS3**: Advanced styling with CSS Grid and Flexbox - **Vanilla JS**: No frameworks, pure performance
- **Vanilla JavaScript**: Pure ES6+ without frameworks - **Socket.io Client**: Real-time events
- **Socket.io Client**: Real-time communication
### Backend ### Backend
- **Node.js**: JavaScript runtime - **Node.js + Express**: Robust server
- **Express.js**: Web application framework - **Socket.io**: WebSocket management
- **Socket.io**: WebSocket library for real-time bidirectional communication - **PostgreSQL**: Rigid data persistence (Players, Games, Moves, Sessions)
- **Supabase Client**: PostgreSQL database client with real-time capabilities
### Database ### Database Schema
- **PostgreSQL**: Robust open-source relational database - **Reliability First**: Games are stored with status (`active`, `completed`, `abandoned`).
- **Connection Pooling**: Efficient connection management - **Data Integrity**: Players and Moves are linked via Foreign Keys.
- **Native SQL**: Direct PostgreSQL queries for performance
### Dependencies
```json
{
"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:
```bash
cp db.config.example.js db.config.js
```
Edit `db.config.js`:
```javascript
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](README_DB_CONFIG.md) for detailed setup instructions.
### Server Configuration
Edit `server.js` to change the port:
```javascript
const PORT = process.env.PORT || 3000;
```
---
## 🚀 Production Deployment
For production deployment, use the automated deployment script:
```bash
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](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
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 ## 🐛 Troubleshooting
### Connection Refused Error | Issue | Solution |
**Problem**: Cannot connect to PostgreSQL database |-------|----------|
**Solution**: Verify credentials in `db.config.js` and check PostgreSQL is running | **Database Disconnected** | Check `db.config.js`. If on production, run `bash setup-auto-deploy.sh` to fix sync issues. |
| **"Function not found"** | Run `node update-dbschema.js` to patch missing SQL functions. |
### Port Already in Use | **Cannot Connect** | Ensure port 3000 is open. |
**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](DEPLOYMENT.md)
--- ---
@@ -361,26 +179,6 @@ For more troubleshooting, see [DEPLOYMENT.md](DEPLOYMENT.md)
Contributions are welcome! Please feel free to submit a Pull Request. 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 ## 📧 Contact
@@ -389,12 +187,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
- YouTube: [@beyondcloudtechnology](https://www.youtube.com/@beyondcloudtechnology) - YouTube: [@beyondcloudtechnology](https://www.youtube.com/@beyondcloudtechnology)
- Repository: [DeNNiiInc/Connect-5](https://github.com/DeNNiiInc/Connect-5) - Repository: [DeNNiiInc/Connect-5](https://github.com/DeNNiiInc/Connect-5)
---
<div align="center"> <div align="center">
Made with 💜 by Beyond Cloud Technology
**Made with 💜 by Beyond Cloud Technology**
⭐ Star this repository if you found it helpful!
</div> </div>