Portal Chess

A real-time multiplayer chess variant featuring portal mechanics. Pieces can teleport across the board through magical portals, adding a strategic twist to the classic game.

Features

• Real-time multiplayer gameplay via WebSockets
• Portal mechanics - pieces teleport through linked portal pairs
• Multiple game modes with different portal behaviors
• Google OAuth authentication
• Player matchmaking and rating system
• Game history and replay support
• Responsive chess board UI

Tech Stack

Client:

• React 19 + TypeScript
• Vite
• Socket.io Client

Server:

• Node.js + Express
• Socket.io for real-time communication
• PostgreSQL with Drizzle ORM
• Redis for session/game state
• Passport.js with Google OAuth
• JWT authentication

Shared:

• Game engine and types shared between client/server

Project Structure

portal-chess/
├── client/          # React frontend
├── server/          # Express backend
├── shared/          # Shared game engine & types
├── docs/            # Design documentation
└── package.json     # Root workspace config

Prerequisites

• Node.js 20+
• PostgreSQL
• Redis
• Google OAuth credentials

Setup

1. Clone the repository:

   git clone https://github.com/Mnehmos/portal-chess.git
   cd portal-chess

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp server/.env.example server/.env
   # Edit server/.env with your configuration

   Required environment variables:

   • DATABASE_URL - PostgreSQL connection string
   • REDIS_URL - Redis connection string
   • GOOGLE_CLIENT_ID - Google OAuth client ID
   • GOOGLE_CLIENT_SECRET - Google OAuth client secret
   • JWT_SECRET - Secret for JWT token signing

4. Set up the database:

   npm run build:shared
   cd server && npx tsx scripts/setup-db.ts

Development

Run both client and server concurrently:

npm run dev

Or run them separately:

npm run dev:client   # React dev server on :5173
npm run dev:server   # Express server on :3001

Building for Production

Build all packages:

npm run build:all

Build server only (for deployment):

npm run build:server

Docker

Build the server Docker image:

docker build -f server/Dockerfile -t portal-chess-server .

Run with environment variables:

docker run -p 3001:3001 \
  -e DATABASE_URL=... \
  -e REDIS_URL=... \
  -e GOOGLE_CLIENT_ID=... \
  -e GOOGLE_CLIENT_SECRET=... \
  -e JWT_SECRET=... \
  portal-chess-server

Testing

Run client tests:

npm run test

Run server tests:

npm run test:server

Run all tests:

npm run test:all

Game Rules

Portal Chess follows standard chess rules with the addition of portals:

1. Portals appear as linked pairs on the board
2. When a piece moves onto a portal, it teleports to the linked portal
3. Portals can be used strategically for attacks, defense, and positioning
4. Different game modes offer varying portal behaviors (static, rotating, random)

License

MIT