# Grid Battle Game - Project Plan

## Game Overview
A 2-player turn-based tactical shooter played on a grid. Players spawn in different locations, submit moves simultaneously, then watch them execute together. Victory comes from hitting your opponent with a bullet.

## Core Gameplay

### Grid World
- **Grid Size**: 20x20 cells (configurable)
- **Player Spawning**: Each player spawns in a different grid cell location
- **Visual**: HTML/CSS grid with distinct player representations

### Turn-Based Combat System
- **Simultaneous Moves**: Both players submit their actions privately
- **Turn Execution**: Once both players submit, all actions execute together
- **Actions Per Turn**: Multiple moves allowed per turn (configurable)
- **Action Types**:
  - **Move**: Navigate in cardinal directions (North/South/East/West)
  - **Shoot**: Fire bullets in cardinal directions that travel in straight lines

### Win Condition
- **Bullet Hit**: If a bullet intersects with the opponent, that player loses instantly
- **Game Over**: Winner declared, game ends immediately

## Multiplayer System

### Session Flow
1. **Player 1**: Picks a name and starts a game session
2. **Invite Link**: System generates unique game URL
3. **Player 2**: Clicks link, picks name, joins game
4. **Game Start**: Both players connected, game begins

### Technical Requirements
- Real-time bidirectional communication between players
- Session management with unique game IDs
- Name validation and conflict handling
- Connection state management (reconnection, disconnection)

## Configuration System

### Game Settings (game-config.js)
```javascript
const GAME_CONFIG = {
  GRID_WIDTH: 20,
  GRID_HEIGHT: 20,
  MAX_PLAYERS: 2,
  MOVES_PER_TURN: 3,           // How many actions each player gets
  BULLET_SPEED: 1,             // Cells per turn bullets travel
  TURN_TIMEOUT_MS: 30000,      // Max time to submit moves
  CELL_SIZE_PX: 30,            // Visual size of each grid cell
  SPAWN_BUFFER: 3,             // Minimum cells between player spawns
  GAME_NAME: "Grid Battle"
}
```

### Server Settings (server-config.js)
```javascript
const SERVER_CONFIG = {
  PORT: 8050,
  HOST: 'localhost',
  STATIC_PATH: './public',
  WEBSOCKET_PATH: '/ws'
}
```

## Technical Architecture

### Project Structure
```
/
├── server.js              # Main server entry point
├── server-config.js       # Webserver settings
├── game-config.js         # Game mechanics settings
├── package.json           # NPM scripts and dependencies
├── public/               # Static HTML/CSS/JS files
│   ├── index.html        # Game interface
│   ├── style.css         # Grid and UI styling
│   └── game.js           # Client-side game logic
└── game-logic/           # Server-side game logic
    ├── game-session.js   # Session management
    ├── turn-manager.js   # Turn execution
    └── collision.js      # Bullet collision detection
```

### Startup
- **Simple Launch**: `npm start` starts everything
- **Port**: Server runs on http://localhost:8050
- **Ready to Play**: Game immediately accessible in browser

## Game States

### Connection States
- **Waiting for Players**: Lobby state, waiting for Player 2
- **Both Connected**: Game ready to start
- **In Game**: Active gameplay, turn submission/execution
- **Game Over**: Victory screen, option to play again

### Turn Phases
1. **Move Submission**: Players privately choose actions
2. **Validation**: Server validates all moves
3. **Simultaneous Execution**: All actions happen together
4. **Result Calculation**: Check for bullets hits, update positions
5. **Next Turn**: Return to submission phase or declare winner

## Key Technical Components

### Server-Side
- WebSocket server for real-time communication
- Game session management
- Turn-based logic with simultaneous execution
- Bullet trajectory and collision detection
- Player spawn positioning
- Move validation and conflict resolution

### Client-Side
- Grid rendering and visual updates
- Move input interface (directional controls)
- Real-time game state synchronization
- Player feedback (turn status, game results)
- Connection handling (reconnection, errors)

## Design Principles
Following clear code principles:
- **No Clever Tricks**: Straightforward, readable implementations
- **Descriptive Naming**: Functions like `calculateBulletPath()` not `cbp()`
- **Single Responsibility**: Each function does ONE thing
- **Explicit Error Handling**: No silent failures
- **Configurable Settings**: All magic numbers in config files
- **Easy Maintenance**: Code written for violent psychopaths who know where you live

## Development Approach
- Start with basic grid and player positioning
- Add turn-based move submission
- Implement bullet firing and collision detection
- Add multiplayer session management
- Polish UI and game experience
- Test edge cases and error handling