Battery Rush

A grid-based retro survival game where you control a robot with limited battery power.

Game Description

In Battery Rush, you control a robot that moves on a grid. Each move drains your battery, and you must collect energy cells to stay alive while avoiding enemies. The game ends when your battery runs out or an enemy catches you.

Gameplay Demo

Experience the retro survival action - collect energy cells, avoid enemies, and survive as long as possible!

Features

• Grid-based movement system
• Battery management mechanics
• Random enemy and energy cell spawning
• Score tracking and high scores
• Retro-style graphics and sound effects
• Multiple game states (menu, gameplay, game over)

Project Structure

battery_rush/
├── main.py                    # Main entry point
├── requirements.txt           # Python dependencies
├── README.md                 # This file
└── game/                     # Game package
    ├── __init__.py
    ├── core/                 # Core game engine
    │   ├── __init__.py
    │   ├── game_engine.py    # Main game engine
    │   └── input_handler.py  # Input management
    ├── states/               # Game states
    │   ├── __init__.py
    │   ├── base_state.py     # Base state class
    │   ├── menu_state.py     # Main menu
    │   ├── game_state.py     # Main gameplay
    │   └── game_over_state.py # Game over screen
    ├── entities/             # Game entities (player, enemies, etc.)
    ├── systems/              # Game systems (rendering, collision, etc.)
    ├── audio/                # Audio management
    └── utils/                # Utilities and constants
        ├── __init__.py
        └── constants.py      # Game constants

Installation

1. Make sure you have Python 3.7+ installed
2. Install dependencies:

python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

## Running the Game

```bash
python main.py

Controls

• WASD or Arrow Keys: Move the robot
• Space or P: Pause game / Start from menu
• R: Restart game (from game over screen)
• ESC: Quit to menu / Quit game

Development Status

This is a modular rebuild of Battery Rush with the following implementation phases:

1. ✅ Phase 1: Project scaffolding and basic game loop
2. ✅ Phase 2: Game entities (player, enemies, energy cells) and core gameplay
3. ✅ Phase 3: Audio system and sound effects
4. ✅ Phase 4: Polish and additional features

Game Features Implemented

Core Gameplay

• ✅ Grid-based robot movement with battery drain
• ✅ Random enemy spawning and movement
• ✅ Energy cell collection and battery recharging
• ✅ Collision detection (player vs enemies/energy cells)
• ✅ Score tracking and high score system
• ✅ Game over conditions (battery depletion or enemy contact)

Visual Features

• ✅ Animated energy cells with pulsing effect
• ✅ Player battery indicator on character
• ✅ Color-coded battery bar (green/yellow/red)
• ✅ Real-time entity counters
• ✅ Pause functionality with overlay
• ✅ Particle effects system (pickup, death, movement trails)
• ✅ Screen shake effects for dramatic moments
• ✅ Low battery sparking effects
• ✅ Visual feedback for all player actions

Audio Features

• ✅ Procedural retro sound effects generation
• ✅ Movement sounds (subtle beeps)
• ✅ Energy cell pickup sounds (rising power-up tone)
• ✅ Game over sound (dramatic descending sequence)
• ✅ Menu selection sounds
• ✅ Pause/unpause audio feedback
• ✅ Low battery warning sounds (pulsing alert)
• ✅ Audio toggle functionality (M key)
• ✅ Volume control and audio management

Advanced Features

• ✅ Dynamic difficulty progression system
• ✅ Persistent high score tracking (saved to file)
• ✅ Detailed high scores screen with statistics
• ✅ Survival time tracking
• ✅ Cause of death recording
• ✅ Level progression with increasing challenge
• ✅ Performance monitoring (particle count display)

Game Balance & Progression

• Battery drains 2 points per move (scales with difficulty)
• Energy cells recharge 25 battery points
• Score: 1 point per move, 10 points per energy cell
• Dynamic enemy/energy cell limits based on difficulty level
• Enemy speed increases with level progression
• Spawn rates adjust automatically for balanced challenge

Controls

• WASD or Arrow Keys: Move the robot
• Space or P: Pause game / Start from menu
• M: Toggle audio on/off
• DOWN Arrow: View high scores (from menu)
• UP/DOWN Arrows: Scroll high scores list
• R: Restart game (from game over screen)
• ESC: Quit to menu / Quit game

High Score System

• Tracks top 10 scores with detailed information
• Records survival time and cause of death
• Persistent storage in high_scores.json
• Statistics tracking (games played, average score, etc.)
• Achievement notifications for new high scores

Difficulty Progression

• Level 1-3: Beginner to Easy
• Level 4-6: Normal difficulty
• Level 7-10: Hard difficulty
• Level 11-15: Expert difficulty
• Level 16+: Nightmare difficulty

Each level increases:

• Enemy spawn rate and movement speed
• Maximum number of enemies on screen
• Battery drain rate (slightly)
• Reduces energy cell spawn rate

Technical Excellence

• Modular Architecture: Clean separation of concerns
• Performance Optimized: Efficient particle system and collision detection
• Extensible Design: Easy to add new features and game modes
• Professional Polish: Screen shake, particle effects, persistent data
• Error Handling: Graceful degradation for audio/file system issues
• Cross-Platform: Works on any system with Python and pygame

Next Steps

Battery Rush is now a complete, polished retro gaming experience! The game successfully combines engaging survival gameplay, professional visual and audio presentation, and advanced features like difficulty progression and persistent high scores.