monquigrid/idea.md

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)

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)

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