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
- [x] Initialize Node.js project with `package.json`
- [x] Install dependencies: `express`, `socket.io`, `uuid`
- [x] Create basic Express server serving static files from `public/`
- [x] Implement Socket.io room system:
  - `join-room` event - player joins with username
  - `leave-room` event - player leaves
  - Broadcast `player-joined` / `player-left` to room
- [x] Track players in room with IDs, names, ready status
- [x] 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
- [x] 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)
- [x] Create `public/js/renderer.js` with:
  - Canvas setup per player board
  - Draw grid, active piece, locked pieces
  - Classic Tetris colors for each piece type
- [x] Wire keyboard controls (arrow keys + space for hard drop)
- [x] 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
- [x] Server: Add game state tracking per room
  - Active pieces, board states, scores
  - Game running/paused/over status
- [x] Client `public/js/network.js`:
  - Send player actions to server (`move-piece`, `rotate`, `drop`)
  - Receive state updates and apply locally
- [x] Server: Broadcast state at ~20fps to all room players
- [x] Server: Handle `start-game` when 2+ players ready
- [x] Client: Use networked state
- [x] 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
- [x] Server: Track lines cleared per player
- [x] 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
- [x] Garbage row representation (filled row with 1 random gap)
- [x] Server: Pick random target(s) when garbage sent
- [x] Client: Receive garbage, shift board up, add garbage at bottom
- [x] Visual: Garbage rows have distinct color (gray/black)
- [x] 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
- [x] `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`)
- [x] `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:
  - [x] Row clear flash animation
  - [x] 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
- [x] 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
- [x] Score tracking and leaderboard
- [x] 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
```json
{
  "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