battle-royal-tetris/PLAN.md

Tetris Battle Royale - Implementation Plan

Context

Build a multiplayer Tetris Battle Royale game where 2-8 players compete. When a player clears rows, those rows are garbage-dumped onto random opponents' boards. Players see all other boards in real-time. Uses WebSocket for multiplayer and classic retro aesthetics.

Architecture

Tech Stack

• Frontend: HTML5 Canvas, CSS3, Vanilla JavaScript
• Backend: Node.js + Socket.io for real-time WebSocket communication
• No frameworks - pure vanilla implementation

File Structure

tetris-battle-royale/
├── server/
│   ├── index.js          # Socket.io server, game state management
│   └── package.json
├── public/
│   ├── index.html        # Game UI with player grids
│   ├── css/
│   │   └── style.css     # Retro pixel-art styling
│   └── js/
│       ├── game.js       # Core Tetris logic
│       ├── renderer.js   # Canvas rendering
│       ├── network.js    # Socket.io client
│       ├── ui.js         # HUD and game messages
│       └── app.js        # Main application
└── README.md

---

Phase 1: Server Setup & Multiplayer Infrastructure [DONE]

Goal: Get a working Node.js server with Socket.io that handles rooms and player connections.

Todos

• Initialize Node.js project with package.json
• Install dependencies: express, socket.io, uuid
• Create basic Express server serving static files from public/
• Implement Socket.io room system:
  • join-room event - player joins with username
  • leave-room event - player leaves
  • Broadcast player-joined / player-left to room
• Track players in room with IDs, names, ready status
• Create simple HTML page to test connection

Success criteria: Can open 2+ browser tabs, join same room, see player list update.

---

Phase 2: Core Tetris Game Logic [DONE]

Goal: Implement single-player Tetris mechanics on the client side.

Todos

• Create public/js/game.js with:
  • 10x20 grid data structure
  • Tetromino definitions (I, O, T, S, Z, J, L shapes and colors)
  • Piece spawning at top center
  • Movement: left, right, soft drop
  • Rotation with wall kick (basic SRS)
  • Hard drop (instant place)
  • Row clearing detection
  • Game over detection (piece collides at spawn)
• Create public/js/renderer.js with:
  • Canvas setup per player board
  • Draw grid, active piece, locked pieces
  • Classic Tetris colors for each piece type
• Wire keyboard controls (arrow keys + space for hard drop)
• Game loop with adjustable speed (starts slow, speeds up with lines)

Success criteria: Single-player Tetris works smoothly with all piece types and controls.

---

Phase 3: Multiplayer Game State Sync [DONE]

Goal: Connect multiple players and sync game state in real-time.

Todos

• Server: Add game state tracking per room
  • Active pieces, board states, scores
  • Game running/paused/over status
• Client public/js/network.js:
  • Send player actions to server (move-piece, rotate, drop)
  • Receive state updates and apply locally
• Server: Broadcast state at ~20fps to all room players
• Server: Handle start-game when 2+ players ready
• Client: Use networked state
• Sync piece positions, board state, scores across all players

Success criteria: 2+ players can play simultaneously, all see each other's boards and piece movements in real-time.

---

Phase 4: Garbage Battle System [DONE]

Goal: Implement the battle royale mechanic - clearing rows sends garbage to opponents.

Todos

• Server: Track lines cleared per player
• Implement garbage row calculation:
  • 1 line → 0 garbage rows
  • 2 lines → 1 garbage row to random opponent
  • 3 lines → 2 garbage rows to random opponent(s)
  • 4 lines (Tetris) → 4 garbage rows
• Garbage row representation (filled row with 1 random gap)
• Server: Pick random target(s) when garbage sent
• Client: Receive garbage, shift board up, add garbage at bottom
• Visual: Garbage rows have distinct color (gray/black)
• Elimination: Player loses when garbage reaches top

Success criteria: Clearing rows visibly adds garbage rows to opponent boards.

---

Phase 5: Retro UI Polish [IN PROGRESS]

Goal: Classic Tetris aesthetic with multi-board layout.

Todos

• public/css/style.css:
  • Import Press Start 2P font from Google Fonts
  • CSS Grid layout for player boards (adaptive 2x2 or 2x4)
  • Retro color scheme (dark background, bright pieces)
  • CRT scanline overlay effect
  • Pixelated canvas rendering (image-rendering: pixelated)
• public/js/ui.js:
  • Player info HUD (name, score, lines)
  • Player list sidebar with status (playing/eliminated)
  • Room join screen with username input
  • "Ready" button and countdown before game start
  • Game over screen with winner announcement
  • Next piece preview panel
• Visual effects:
  • Row clear flash animation
  • Garbage receiving shake effect
  • Player color indicators per board

Success criteria: Game looks like classic Tetris with all boards visible and polished UI.

---

Phase 6: Polish & Edge Cases [PENDING]

Goal: Handle real-world scenarios and add final touches.

Todos

• Player disconnect handling:
  • Remove from room, update player list
  • Continue game with remaining players or end if <2
• Rejoin support (optional): Allow disconnected player to rejoin
• Score tracking and leaderboard
• Level system: Speed increases every 10 lines
• Combo system: Bonus for consecutive clears
• Sound effects (optional): Clear, garbage receive, game over
• Settings menu: Speed, sound toggle, controls
• README with setup instructions

Success criteria: Game handles disconnections gracefully, full feature set working.

---

Dependencies

{
  "dependencies": {
    "express": "^4.18.2",
    "socket.io": "^4.7.2",
    "uuid": "^9.0.0"
  }
}

Verification

1. npm install then node server/index.js
2. Open http://localhost:3000 in 2-8 tabs
3. Join same room, click Ready, verify countdown
4. Play and verify garbage rows appear on opponents
5. Test disconnects, game over, winner announcement