# Grid Battle Game Development Project

## Clear Code Principles

Write code as if the person maintaining it is a violent psychopath who knows where you live:

    NO CLEVER TRICKS: Clear, obvious code only
    DESCRIPTIVE NAMING: processTextNodes() not ptn() or handleStuff()
    COMMENT EASLY UNDERSTANABLE TO HELP HUMANS UNDERSTAND
    SINGLE RESPONSIBILITY: Each function does ONE thing
    EXPLICIT ERROR HANDLING: No silent failures

## Project Overview

This is a 2-player turn-based tactical shooter game built with:
- **Frontend**: HTML5, CSS3, Vanilla JavaScript
- **Backend**: Node.js with Express.js
- **Database**: SQLite3 for persistent game state
- **Architecture**: REST API with polling-based real-time updates

## Game Mechanics

- **Grid**: 20x20 grid-based battlefield
- **Turn System**: Simultaneous action submission, sequential execution
- **Actions**: 4 moves per turn + 1 shot (doesn't cost a move)
- **Movement**: Cardinal directions only (N/S/E/W)
- **Combat**: Instant bullet hits, shots fire during movement sequence
- **Win Condition**: Hit opponent with bullet

## Development Workflow

### User-Driven Development
- User provides specific feature requests and bug reports
- Immediate implementation and testing cycle
- Iterative refinement based on user feedback
- Real-time debugging with user participation

### Code Quality Standards
- Use TodoWrite tool to track all tasks and progress
- Fix bugs immediately when reported by user
- Prioritize user experience over code elegance
- Maintain clear, readable code for future development

### Testing Approach
- User tests all features in real gameplay scenarios
- Fix issues as they arise during actual play
- No formal testing framework - rely on user feedback
- Console logging for debugging complex game logic

## Architecture Decisions

### Why SQLite over WebSockets
- **Persistence**: Game state survives server restarts
- **Replay System**: Complete event logging for game replays
- **Tournament Support**: Database structure supports future tournaments
- **Leaderboards**: Player statistics and rankings
- **Simplicity**: Easier to debug and maintain than WebSocket state

### Why Polling over WebSockets
- **Reliability**: No connection drops or reconnection issues
- **Simplicity**: Standard HTTP requests, easier to debug
- **Stateless**: Each request is independent
- **Browser Compatibility**: Works everywhere without special protocols

## Key Implementation Notes

### Turn Execution Order
1. Store original positions before any actions
2. Process all shots first (from original positions)
3. Then process all movements
4. This ensures shots are truly "instant" and fire from pre-movement positions

### Hit Detection
- Shots are instant and check against positions before movement
- Exclude shooter from hit detection to prevent self-hits
- Comprehensive logging for debugging hit detection issues

### Animation System
- Visual animations are separate from game logic
- Animations show step-by-step turn execution
- Game end screens delayed until animations complete
- Bullet trails fade over 5 seconds for visual clarity

## Development History

The project was built iteratively through direct user collaboration:
1. Started with basic grid and movement mechanics
2. Added multiplayer with SQLite backend
3. Implemented turn-based combat system
4. Added visual feedback and animations
5. Implemented game end flow and rematch functionality
6. Continuous bug fixing and feature refinement

## Current Status

**Completed Features:**
- Full multiplayer game with invite links
- Turn-based combat with visual feedback
- Game end screens and rematch functionality
- Comprehensive database schema for future features

**Known Issues:**
- Shot detection intermittently failing in some scenarios
- Play Again button needs refinement
- Starting positions are fixed (need randomization)

**Next Features:**
- Randomized spawn positions
- Obstacles for strategic cover
- Enhanced shot detection reliability

