185 lines
5.0 KiB
Markdown
185 lines
5.0 KiB
Markdown
# Sequence Card Game
|
||
|
||
A React implementation of the Sequence card game with TypeScript, Zustand state management, and Tailwind CSS.
|
||
|
||
## Features
|
||
|
||
- **10×10 game board** with 2 decks of cards (no jacks)
|
||
- **4 corner JOKER** wild card positions
|
||
- **Two teams**: Red vs Blue
|
||
- **Simple interaction**: Click cards to cycle: White → Red → Blue → White
|
||
- **Automatic save**: Game state persists in browser localStorage
|
||
- **Mobile responsive**: Works on desktop and mobile devices
|
||
- **Shuffle functionality**: Randomize board before game starts
|
||
- **Turn tracking**: Visual indicator for current player's turn
|
||
- **Score tracking**: Basic score display for both teams
|
||
|
||
## Game Rules (Simplified)
|
||
|
||
1. **Board**: 10×10 grid with 96 cards (2 decks, no jacks) + 4 corner JOKERs
|
||
2. **Teams**: Red vs Blue only
|
||
3. **Claiming cards**: Click any card to claim it for your team
|
||
4. **Sequences**: 5 cards in a row (horizontal, vertical, diagonal) scores 1 point
|
||
5. **Corner JOKERs**: Count as wild cards - only 4 cards + corner needed for sequence
|
||
6. **Game flow**: Teams alternate turns when cards are claimed
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
sequence/
|
||
├── src/
|
||
│ ├── components/ # React components
|
||
│ │ ├── GameBoard.tsx # 10×10 grid container
|
||
│ │ ├── BoardCell.tsx # Individual cell with click handler
|
||
│ │ ├── Card.tsx # Card display component
|
||
│ │ ├── ScoreBoard.tsx # Red/Blue scores display
|
||
│ │ ├── TurnIndicator.tsx # Turn indicator component
|
||
│ │ └── Controls.tsx # Game control buttons
|
||
│ ├── hooks/
|
||
│ │ └── useGameStore.ts # Zustand store with persistence
|
||
│ ├── lib/
|
||
│ │ ├── gameState.ts # TypeScript type definitions
|
||
│ │ ├── boardGenerator.ts # Board generation & shuffling
|
||
│ │ ├── sequenceCheck.ts # Sequence detection logic
|
||
│ │ └── constants.ts # Game constants
|
||
│ ├── App.tsx # Main app layout
|
||
│ └── main.tsx # App entry point
|
||
├── public/ # Static assets
|
||
├── dist/ # Production build output
|
||
└── deploy.sh # Deployment script
|
||
```
|
||
|
||
## Getting Started
|
||
|
||
### Prerequisites
|
||
- Node.js 18+ and npm
|
||
|
||
### Installation
|
||
|
||
1. Navigate to the project directory:
|
||
```bash
|
||
cd /home/sam/home_network/web_sites/sequence
|
||
```
|
||
|
||
2. Install dependencies:
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### Development
|
||
|
||
Start the development server:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
Open http://localhost:5173 in your browser.
|
||
|
||
### Build for Production
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
Preview the production build:
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
### Deployment
|
||
|
||
Use the deployment script to build and deploy to the remote server:
|
||
|
||
```bash
|
||
./deploy.sh
|
||
```
|
||
|
||
Or manually:
|
||
```bash
|
||
# Build the project
|
||
npm run build
|
||
|
||
# Deploy to remote server
|
||
rsync -avz --delete dist/ sam@192.168.20.13:/var/www/sequence/
|
||
|
||
# Or for local testing deployment
|
||
rsync -avz --delete dist/ /var/www/sequence/
|
||
```
|
||
|
||
## Implementation Details
|
||
|
||
### State Management
|
||
- Uses **Zustand** with localStorage persistence
|
||
- Single source of truth for game state
|
||
- Automatic state restoration on page reload
|
||
|
||
### Game Logic
|
||
- **Board generation**: Creates 2 full decks (no jacks), shuffles, places on 10×10 grid
|
||
- **Sequence detection**: Checks for 5-in-a-row patterns (4 with corner JOKER)
|
||
- **Turn management**: Enforces alternating turns between teams
|
||
|
||
### Styling
|
||
- **Tailwind CSS** for utility-first styling
|
||
- **Responsive design**: Works on mobile and desktop
|
||
- **Visual feedback**: Clear color coding for teams and game state
|
||
|
||
## Next Features to Implement
|
||
|
||
1. **Sequence detection & automatic scoring** (logic ready, needs integration)
|
||
2. **Game completion logic** (win conditions)
|
||
3. **Historical game tracking** in localStorage
|
||
4. **Advanced rules** (jack cards, dead cards)
|
||
5. **Multiplayer support** (online or local network)
|
||
6. **AI opponent** for single-player mode
|
||
7. **Sound effects** and animations
|
||
8. **Game statistics** and leaderboards
|
||
|
||
## Technology Stack
|
||
|
||
- **React 18** with TypeScript
|
||
- **Vite** for fast development and building
|
||
- **Zustand** for state management
|
||
- **Tailwind CSS** for styling
|
||
|
||
## Current Status
|
||
|
||
✅ **Phase 1 Complete** (Basic Board & Interaction):
|
||
- 10×10 board with 4 JOKER corners
|
||
- Card display with suits and ranks
|
||
- Click cycle: white → red → blue → white
|
||
- Shuffle functionality
|
||
- Score and turn tracking
|
||
- Game state persistence
|
||
- Responsive design
|
||
|
||
🔄 **Phase 2 In Progress** (Game Logic):
|
||
- Sequence detection ready (needs integration)
|
||
- Score automation on sequence completion
|
||
- Game completion detection
|
||
|
||
## Testing the Application
|
||
|
||
1. **Local development**:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
Visit: http://localhost:5173
|
||
|
||
2. **Production preview**:
|
||
```bash
|
||
npm run build
|
||
npm run preview
|
||
```
|
||
Visit: http://localhost:4173
|
||
|
||
3. **Local deployment test**:
|
||
```bash
|
||
./deploy.sh
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|
||
|
||
## Acknowledgments
|
||
|
||
Based on the classic Sequence card game by Jax Ltd. |