mirror of
https://github.com/DeNNiiInc/Connect-5.git
synced 2026-04-17 18:26:01 +00:00
Docs: Complete overhaul of README with production URL and screenshots
This commit is contained in:
243
README.md
243
README.md
@@ -4,16 +4,15 @@
|
||||
|
||||
**Premium Real-Time Multiplayer Gomoku Game**
|
||||
|
||||
[](https://connect5.beyondcloud.technology/)
|
||||
[](https://connect5.beyondcloud.technology/)
|
||||
|
||||
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://postgresql.org/)
|
||||
[](LICENSE)
|
||||
|
||||
[Play Now](https://connect5.beyondcloud.technology/) • [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Multiplayer](#multiplayer) • [Deployment](#production-deployment)
|
||||
[Features](#-features) • [Visual Tour](#-visual-tour) • [How to Play](#-how-to-play) • [Deployment](#-deployment)
|
||||
|
||||
</div>
|
||||
|
||||
@@ -21,232 +20,104 @@ A beautiful, feature-rich implementation of the classic Connect-5 (Gomoku) game
|
||||
|
||||
## ✨ Features
|
||||
|
||||
### 🎯 Game Modes
|
||||
- **Local Play**: Play against friends on the same device with smooth turn-based gameplay
|
||||
- **Real-Time Multiplayer**: Challenge players worldwide with <50ms move synchronization
|
||||
- **Multiple Board Sizes**: Tactical variety with 15×15, 20×20, 25×25, or epic 50×50 grids
|
||||
- **Smart Matchmaking**: Player lobby with live stats (Wins/Losses/Draws) for informed challenges
|
||||
### 🌟 Visual Excellence (New!)
|
||||
- **Flash Last Move**: The most recent move pulses with a **neon glow** (2x brightness) for 2 seconds, making game flow instantly readable.
|
||||
- **Winning Highlight**: The 5 winning pieces are permanently highlighted with a victory animation.
|
||||
- **Customizable Visibility**: New **Grid & Dot Sliders** allow you to adjust board contrast in real-time.
|
||||
- **Graphing Paper Aesthetic**: Dark-themed, precision-grid design with glassmorphism UI elements.
|
||||
|
||||
### 🌐 Multiplayer Features (NEW & ENHANCED)
|
||||
### 🌐 Multiplayer Experience
|
||||
- **Real-Time Lobby**: See online players, challenge them instantly, and track their stats (Wins/Losses).
|
||||
- **Live Presence**: Notifications for challenges, accepts, and declines.
|
||||
- **Persistent Identity**: Username and stats are saved automatically.
|
||||
- **Reconnection Support**: Resume your game even if you accidentally refresh or lose internet briefly.
|
||||
|
||||
#### Core Multiplayer
|
||||
- **Live Player Lobby**: See all online players with real-time presence indicators
|
||||
- **Challenge System**: Send and receive game invitations with instant notifications
|
||||
- **Player Statistics**: Track your performance with persistent win/loss/draw records
|
||||
- **Auto-Login**: Username persistence across sessions with 30-day cookie storage
|
||||
- **Profanity Filter**: Family-friendly environment with bad-words filtering
|
||||
|
||||
#### 🏳️ Surrender & Rematch (NEW)
|
||||
- **Graceful Surrender**: End hopeless games early with the Surrender button
|
||||
- Confirmation modal prevents accidental surrenders
|
||||
- Immediate stats update (counts as loss for surrenderer, win for opponent)
|
||||
- Both players notified instantly
|
||||
- **Instant Rematch**: Challenge the same opponent immediately after any game
|
||||
- "Challenge Again" button in Game Over modal
|
||||
- Full negotiation flow (accept/decline)
|
||||
- Preserves board size preference
|
||||
- No need to return to lobby between rematches
|
||||
|
||||
#### 🛡️ Reliability & State Management (NEW)
|
||||
- **Smart Disconnect Handling**: 30-second grace period for network blips
|
||||
- Automatic reconnection on internet restoration
|
||||
- Full board state restoration (all moves preserved)
|
||||
- Seamless resume even with new socket connection
|
||||
- **Game State Protection**: No more abandoned games from accidental refreshes
|
||||
- **Race Condition Prevention**: Server-side state locks prevent double-actions
|
||||
- **Session Recovery**: Resume active games automatically on page reload
|
||||
|
||||
### 🎨 Premium Design
|
||||
- **Graphing Paper Aesthetic**: Beautiful dark theme with precision grid lines
|
||||
- **Smooth Animations**:
|
||||
- Polished piece placement with scale effects
|
||||
- Victory sequence highlighting with glow effects
|
||||
- Modal transitions with glassmorphism
|
||||
- **Modern UI Components**:
|
||||
- Glassmorphism overlays with backdrop blur
|
||||
- Gradient accents and hover states
|
||||
- Responsive button designs
|
||||
- **Cross-Platform**: Flawless experience on desktop, tablet, and mobile
|
||||
|
||||
### 🎲 Gameplay Excellence
|
||||
- **8-Direction Win Detection**: Scan horizontal, vertical, and both diagonals
|
||||
- **Turn Indicators**: Clear visual feedback showing whose turn it is
|
||||
- **Win Highlighting**: Animated display of the winning 5-piece sequence
|
||||
- **Draw Detection**: Automatic detection when board is full
|
||||
- **Move Validation**: Client and server-side validation prevents invalid moves
|
||||
- **Persistent Scoring**: All games saved to PostgreSQL with complete move history
|
||||
### 🎮 Gameplay Depth
|
||||
- **Multiple Board Sizes**: Choose from tight 15×15 tactical matches to epic 50×50 wars.
|
||||
- **Smart Controls**:
|
||||
- **Surrender**: Gracefully bow out of a lost position.
|
||||
- **Rematch**: Challenge the same opponent again instantly.
|
||||
- **Win Detection**: Full 8-direction detection algorithm with server-side validation.
|
||||
|
||||
---
|
||||
|
||||
## 📸 Screenshots
|
||||
## 📸 Visual Tour
|
||||
|
||||
<div align="center">
|
||||
|
||||
### Multiplayer Lobby
|
||||
*Challenge players worldwide in real-time*
|
||||
|
||||
*Challenge players in real-time from the lobby*
|
||||
|
||||
### Local Game Mode
|
||||
### Intense Local Play
|
||||
*Smooth, responsive gameplay with new "Last Move Zoom"*
|
||||
|
||||
|
||||
### Different Board Sizes
|
||||
### Variable Board Sizes
|
||||
*From standard 15x15 to massive 50x50 grids*
|
||||
|
||||
|
||||
### Victory Screen
|
||||
### Victory Celebration
|
||||
*Clear winner announcement with move highlighting*
|
||||
|
||||
|
||||
### Surrender Modal
|
||||
### Fair Play Features
|
||||
*Surrender options and robust game state management*
|
||||
|
||||
*Gracefully end games with the new confirmation modal*
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Installation
|
||||
## 🎮 How to Play
|
||||
|
||||
### Prerequisites
|
||||
- **Node.js** 18+ ([Download](https://nodejs.org/))
|
||||
- **PostgreSQL** Database ([Download](https://www.postgresql.org/download/))
|
||||
- **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
|
||||
# 1. Create database: CREATE DATABASE connect5;
|
||||
# 2. Setup config:
|
||||
cp db.config.example.js db.config.js
|
||||
# 3. Edit db.config.js with your credentials
|
||||
|
||||
# 4. Initialize Database Schema
|
||||
# (Check update-dbschema.js if psql is not available)
|
||||
psql -h HOST -U postgres -d connect5 -f postgres-schema.sql
|
||||
|
||||
# Start the server
|
||||
npm start
|
||||
```
|
||||
|
||||
The server will start on **http://localhost:3000**
|
||||
|
||||
---
|
||||
|
||||
## 🎮 Usage
|
||||
|
||||
### Multiplayer Instructions
|
||||
### Local Mode (Same Device)
|
||||
1. Select **"🎮 Local Play"**.
|
||||
2. Choose board size (Standard 15x15 recommended).
|
||||
3. Take turns placing X and O.
|
||||
4. First to get **5 in a row** (horizontal, vertical, or diagonal) wins!
|
||||
|
||||
### Multiplayer Mode (Online)
|
||||
1. Click **"🌐 Multiplayer"**.
|
||||
2. Enter your username (3-20 characters).
|
||||
3. **Lobby**: See online players and their stats (Wins/Losses).
|
||||
4. **Challenge**: Click "Challenge" next to a player.
|
||||
5. **Game On**: Once accepted, the board loads for both of you.
|
||||
|
||||
### In-Game Controls
|
||||
|
||||
- **Place Piece**: Click any empty intersection.
|
||||
- **Surrender**: Click the "Surrender" button (Game Controls area) to forfeit.
|
||||
- **Rematch**: After the game, click "Challenge Again" to keep playing the same opponent.
|
||||
2. Enter a username.
|
||||
3. **Lobby**: Click "Challenge" next to any online player.
|
||||
4. **Accept**: When challenged, a notification appears—click Accept to start.
|
||||
5. **Play**: Moves are synced instantly (<50ms).
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Production Deployment (Proxmox + TurnKey Linux)
|
||||
## 🚀 Deployment
|
||||
|
||||
We recommend using a **Proxmox TurnKey Node.js Container** for production.
|
||||
The production environment runs on **Proxmox (TurnKey Node.js)** with a fully automated CI/CD pipeline.
|
||||
|
||||
### ✅ 1. One-Click Remote Deployment (Windows)
|
||||
Easily deploy from your local Windows machine to the remote server using the included PowerShell script.
|
||||
### Production URL
|
||||
**[https://connect5.beyondcloud.technology/](https://connect5.beyondcloud.technology/)**
|
||||
|
||||
**Pre-requisite:** Create `deploy-config.json` in your project root (this file is ignored by git):
|
||||
```json
|
||||
{
|
||||
"host": "172.16.69.214",
|
||||
"username": "root",
|
||||
"password": "YOUR_SSH_PASSWORD",
|
||||
"remotePath": "/var/www/connect5",
|
||||
"gitToken": "YOUR_GITHUB_TOKEN"
|
||||
}
|
||||
```
|
||||
### Automated Updates
|
||||
The server checks GitHub every **5 minutes**.
|
||||
- **Push code**: `git push origin main`
|
||||
- **Wait 5 mins**: Server pulls, installs dependencies, and restarts automatically.
|
||||
|
||||
**To Deploy or Update:**
|
||||
```powershell
|
||||
### Manual Deployment
|
||||
```bash
|
||||
# Force immediate update from Windows
|
||||
.\deploy-remote.ps1
|
||||
```
|
||||
*This script automatically updates code, installs dependencies, and restarts the service.*
|
||||
|
||||
### 🔄 2. Automated Updates (Cron Job)
|
||||
The server is configured to **automatically pull updates from GitHub every 5 minutes**.
|
||||
- **No changes?** Nothing happens.
|
||||
- **New code?** The server pulls changes, runs `npm install`, and restarts the app using the `post-merge` hook.
|
||||
|
||||
### 🛡️ 3. Cloudflare Tunnel (Secure Access)
|
||||
The application is securely exposed using a Cloudflare Tunnel, eliminating the need to open router ports.
|
||||
|
||||
**Service Status:**
|
||||
```bash
|
||||
systemctl status connect5
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
journalctl -u connect5 -f
|
||||
```
|
||||
|
||||
### 🔒 4. Security & Configuration
|
||||
- **Systemd**: The app runs as a `systemd` service (`connect5`), ensuring it auto-starts on boot.
|
||||
- **Nginx**: Configured as a reverse proxy on Port 80.
|
||||
- **Secrets**: Database credentials are stored in `db.config.js` and excluded from source control.
|
||||
|
||||
See [PROXMOX_DEPLOY_TEMPLATE.md](PROXMOX_DEPLOY_TEMPLATE.md) for the manual setup guide.
|
||||
See [PROXMOX_DEPLOY_TEMPLATE.md](PROXMOX_DEPLOY_TEMPLATE.md) for full server setup details.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tech Stack
|
||||
|
||||
### Frontend
|
||||
- **HTML5/CSS3**: Custom Glassmorphism design
|
||||
- **Vanilla JS**: No frameworks, pure performance
|
||||
- **Socket.io Client**: Real-time events
|
||||
|
||||
### Backend
|
||||
- **Node.js + Express**: Robust server
|
||||
- **Socket.io**: WebSocket management
|
||||
- **PostgreSQL**: Rigid data persistence (Players, Games, Moves, Sessions)
|
||||
|
||||
### Database Schema
|
||||
- **Reliability First**: Games are stored with status (`active`, `completed`, `abandoned`).
|
||||
- **Data Integrity**: Players and Moves are linked via Foreign Keys.
|
||||
- **Frontend**: Vanilla JS (ES6+), CSS3 Variables, Socket.io Client.
|
||||
- **Backend**: Node.js, Express, Socket.io.
|
||||
- **Database**: PostgreSQL (Stores games, moves, players).
|
||||
- **Infrastructure**: Proxmox LXC, Cloudflare Tunnel, Nginx.
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| **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. |
|
||||
| **Cannot Connect** | Ensure port 3000 is open. |
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
---
|
||||
|
||||
## 📧 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
|
||||
Made with 💜 by <strong>Beyond Cloud Technology</strong><br>
|
||||
<a href="https://www.youtube.com/@beyondcloudtechnology">YouTube</a> • <a href="https://github.com/DeNNiiInc/Connect-5">GitHub</a>
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user