dominoes/DOCUMENTATION.md

Dominoes Game - Technical Documentation

Architecture Overview

This is a full-stack, real-time multiplayer dominoes game built with modern web technologies.

Key Technologies

• Frontend: Next.js 16 (App Router), React 19, TypeScript
• State Management: Zustand
• Real-time Communication: Socket.IO
• Styling: Tailwind CSS v4
• Animations: Framer Motion
• Graphics: HTML5 Canvas API

Game Features

1. Multiplayer Mode

• Real-time synchronization using WebSockets
• Support for 2-4 players per room
• Room-based game sessions with unique 6-character codes
• Automatic reconnection handling
• Player ready system before game starts

2. AI Mode

• Offline single-player against AI
• Three difficulty levels implemented (easy, medium, hard)
• Strategic tile selection algorithm
• Simulated thinking delays for realistic gameplay

3. Game Mechanics

• Traditional domino rules (0-6 tiles, 28 total)
• 7 tiles per player at start
• Boneyard for drawing additional tiles
• Turn-based gameplay with validation
• Win conditions: first to empty hand or lowest score when blocked
• Pass turn functionality when no valid moves

4. Visual Design

• Canvas-based domino tile rendering
• Draggable board for navigation
• Animated tile placement and removal
• Gradient backgrounds and modern UI
• Responsive layout for all screen sizes
• Visual feedback for playable tiles

Project Structure

domino/
├── app/
│   ├── api/socket/
│   │   └── route.ts          # Socket.IO API endpoint (legacy)
│   ├── globals.css               # Global styles
│   ├── layout.tsx                # Root layout with metadata
│   └── page.tsx                  # Main game page (client component)
│
├── components/
│   ├── DominoCanvas.tsx          # Individual tile rendering with Canvas
│   ├── GameBoard.tsx             # Game board with pan/zoom
│   ├── PlayerHand.tsx            # Player's tile hand display
│   ├── Lobby.tsx                 # Game lobby/menu screen
│   ├── WaitingRoom.tsx           # Pre-game waiting area
│   └── GameOver.tsx              # End game modal
│
├── lib/
│   ├── types.ts                  # TypeScript type definitions
│   ├── gameLogic.ts              # Core game rules and mechanics
│   ├── aiLogic.ts                # AI opponent implementation
│   ├── store.ts                  # Zustand state management
│   └── socket-server.ts          # Socket.IO server logic (legacy)
│
├── server.mjs                    # Custom Next.js server with Socket.IO
└── public/                       # Static assets

State Management

Zustand Store (lib/store.ts)

The application uses a single Zustand store that manages:

• Socket connection: WebSocket client instance
• Game state: Current game data (players, board, tiles, etc.)
• Player data: Current player ID, selected tile
• Room information: Room ID, connection status
• Error handling: Error messages and notifications

Key Actions

// Connection
initSocket()              // Initialize Socket.IO connection
createRoom()              // Create new game room
joinRoom(id, name)        // Join existing room
leaveRoom()               // Leave current room

// Gameplay
makeMove(move)            // Place a tile
drawTile()                // Draw from boneyard
selectTile(tile)          // Select tile from hand
setPlayerReady()          // Mark player as ready

// AI
startAIGame(name)         // Start offline AI game
executeAITurn()           // Process AI move

Socket.IO Events

Client → Server

• create-room: Request new room creation
• join-room: Join room with ID and player name
• player-ready: Mark player as ready to start
• make-move: Submit a game move
• draw-tile: Request tile from boneyard
• leave-room: Leave current room

Server → Client

• room-created: Room successfully created (returns room ID)
• room-joined: Successfully joined room (returns game state)
• game-started: Game has begun
• game-state-updated: Game state changed
• player-joined: New player joined
• player-left: Player disconnected
• invalid-move: Move was rejected
• error: General error message

Game Logic

Tile Generation

• Full domino set: 28 tiles (0-0 through 6-6)
• Each tile has left and right values
• Doubles marked for special rendering

Move Validation

1. Check if tile matches board end values
2. Verify it's the player's turn
3. Ensure player owns the tile
4. Validate placement side (left/right)

Win Conditions

1. Primary: Player uses all tiles
2. Blocked: Game ends when no one can move
   • Winner is player with lowest total pip count

AI Strategy (Hard Mode)

• Evaluates tile values (higher = better early game)
• Considers board end options
• Blocks opponents by playing uncommon values
• Prioritizes doubles near end game
• Defensive play: discards high-value tiles first

Canvas Rendering

DominoCanvas Component

• Draws individual tiles with rounded corners
• Renders dots in traditional domino patterns
• Supports selection highlighting
• Hover effects for playable tiles
• Responsive sizing

GameBoard Component

• Renders all placed tiles
• Pan/drag functionality for navigation
• Grid background for visual reference
• Automatic centering on first tile
• Dynamic positioning calculation

Performance Optimizations

1. Canvas Memoization: Tiles re-render only when state changes
2. Socket Batching: State updates batched to reduce network traffic
3. Lazy Loading: Components loaded only when needed
4. Optimized Re-renders: React.memo and useCallback where appropriate
5. Turbopack: Fast bundling and HMR in development

Deployment

Development

npm run dev

Opens at http://localhost:3000 with Socket.IO server integrated

Note: The project uses a custom Next.js server (server.mjs) that integrates Socket.IO directly. This is required for WebSocket functionality.

Production Build

npm run build
npm start

Environment Variables

Create .env.local:

NEXT_PUBLIC_SOCKET_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

For production, update URLs to your domain.

Vercel Deployment

1. Push to GitHub
2. Import in Vercel
3. Add environment variables
4. Deploy

Socket.IO works automatically with Vercel's serverless functions.

Future Enhancements

Potential features to add:

• Tournament mode with multiple rounds
• Player statistics and leaderboards
• Chat functionality
• Custom tile themes/skins
• Sound effects and music
• Spectator mode
• Replay game history
• Mobile app version
• Game speed settings
• Multiple domino variants (Cuban, Mexican, etc.)

Troubleshooting

Socket Connection Issues

• Ensure port 3000 is not blocked
• Check CORS settings for production
• Verify WebSocket support on hosting platform

Build Errors

• Clear .next folder: rm -rf .next
• Reinstall dependencies: rm -rf node_modules && npm install
• Check Node.js version (18+ required)

TypeScript Errors

• Run type check: npx tsc --noEmit
• Ensure all dependencies have type definitions

License

MIT License - Free for personal and commercial use.

Credits

Created with ❤️ using:

• Next.js by Vercel
• Socket.IO
• Zustand by Poimandres
• Framer Motion
• Tailwind CSS