A browser-based space strategy game built with Python, Pygame, and Pygbag. Conquer the galaxy by capturing planets, building fleets, and outmaneuvering your AI opponent!
Or run locally (see Quick Start below)
- Strategic Planet Conquest: Click planets to select and send fleets to capture territory
- Dynamic Ship Production: Larger planets produce 1-4 ships per second
- Real-time Combat: Ships automatically battle when reaching enemy planets
- Fleet Management: Use the slider to control exactly how many ships to send
- Victory Conditions: Capture all enemy planets to win, or lose everything to defeat
- 🔄 Recall: Instantly return all your fleets to their origin planets
- ⚡ Production Surge: Double ship production on all planets for 10 seconds
- 🛡️ Shield Generator: Reduce incoming damage by 50% on a planet for 15 seconds
- Three Difficulty Levels:
- Easy: Slow, cautious, targets closest planets
- Medium: Balanced strategy with moderate aggression
- Hard: Fast decisions, 70% aggression, uses abilities strategically, prioritizes high-production planets
- Small: 7 planets - Quick skirmishes
- Medium: 13 planets - Balanced gameplay
- Large: 19 planets - Epic battles
Games typically take between 1 and 5 minutes.
Three distinct sound packs to choose from:
- Default: Space-themed sci-fi sounds
- Classical: Rachmaninoff and Beethoven for conquest and defeat
- Silly: Cartoon sound effects (BONK! BOING!)
- Scoreboard: Track your best games with persistent high scores
- Statistics: View planets controlled, ships produced, battles won/lost
- Scoring System: Base 100 points, penalties for losses, bonuses for fast victories
# Install pipenv if you don't have it
pip install pipenv
# Install project dependencies
pipenv install
# Activate the virtual environment
pipenv shellpython main.py# Build and test locally
pipenv run pygbag main.py
# This starts a local server at http://localhost:8000
# The game will run in your browser- Start a New Game: Enter your name and configure your game settings
- Select a Planet: Click one of your blue planets
- Send a Fleet:
- Adjust the slider to choose how many ships to send
- Click a target planet (enemy red or neutral gray)
- Use Abilities Wisely: Each ability can only be used once per game
- Strategic Tips:
- Larger planets = more ship production
- Shield your high-production planets when under attack
- Use Production Surge when you control multiple large planets
- Recall can save your fleets from a losing battle
Your score is based on tactical performance and speed:
Final Score = Tactical Score + Time Bonus
Start with 100 points, lose points for mistakes:
- Lost Battle (attack repelled): -5 points
- Lost Planet (conquered by enemy): -10 points
- Minimum Tactical Score: 0
Fast victories are rewarded:
- Under 60 seconds: +50 bonus (Perfect speedrun! ⚡)
- Under 2 minutes: +30 bonus (Very fast 🚀)
- Under 3 minutes: +15 bonus (Fast ⏱️)
- Under 5 minutes: +5 bonus (Moderate 🐢)
- 5+ minutes: No time bonus
- Maximum Score: 150 (100 tactical + 50 time bonus)
- Perfect Game: 150 points (no losses, under 60 seconds)
- Defeat: 0 points (always)
Strategy Tips:
- Speed matters! Fast victories can offset tactical mistakes
- Each lost battle costs 5 points, lost planets cost 10
- Use Shield ability to prevent costly planet losses
- Balance risk vs speed - 60s, 120s, 180s, and 300s are critical time breakpoints
planet_wars/
├── main.py # Entry point and game loop
├── game/
│ ├── game_state.py # Core game logic and state management
│ ├── entities.py # Planet and Ship classes
│ ├── renderer.py # All drawing and UI rendering
│ ├── input_handler.py # Mouse/keyboard input handling
│ ├── abilities.py # Special ability system
│ ├── config.py # Configuration and persistence
│ ├── scoreboard.py # High score tracking
│ ├── game_over.py # Victory/defeat screen
│ ├── sound.py # Sound system management
│ ├── logger.py # Cross-platform logging
│ ├── ai/
│ │ ├── base_ai.py # AI interface
│ │ └── simple_ai.py # Strategic AI implementation
│ ├── sound_plugins/
│ │ ├── base_sound_plugin.py # Sound plugin interface
│ │ ├── default_plugin.py # Space-themed sounds
│ │ ├── classical_plugin.py # Classical music
│ │ └── silly_plugin.py # Cartoon sounds
│ └── menus/
│ ├── base_menu.py # Shared menu functionality
│ ├── menu.py # Main menu
│ ├── game_config_menu.py # Game configuration
│ └── scoreboard_menu.py # High scores display
├── assets/
│ └── audio/
│ ├── mp3/ # Audio files for desktop
│ ├── ogg/ # Audio files for browser (OGG Vorbis)
│ ├── generate_default_sounds.py # Generate default sounds
│ ├── generate_silly_sounds.py # Generate silly sounds
│ ├── convert_to_ogg.py # MP3 to OGG conversion
│ └── trim_audio.py # Audio trimming utility
├── tests/
│ ├── unit/ # Unit tests for all modules
│ └── integration/ # Integration tests
├── files/ # Local data storage (gitignored)
│ └── README.md
├── docs/ # Documentation
│ ├── BROWSER_DEPLOYMENT.md
│ └── SOUND_SYSTEM.md
├── Pipfile # Dependency management
└── README.md
# Run all tests
pipenv run pytest
# Run with coverage
pipenv run pytest --cov=game --cov-report=html
# Run specific test file
pipenv run pytest tests/unit/test_game_state.py -v
# Run integration tests
pipenv run pytest tests/integration/ -vCurrent test coverage: 300+ tests across all modules
# Run linter
pipenv run pytest --pylint
# Check specific files
pipenv run pylint game/game_state.py# Generate default space sounds
cd assets/audio
pipenv run python generate_default_sounds.py
# Generate silly cartoon sounds
pipenv run python generate_silly_sounds.py
# Trim audio files (MP3 input, creates both MP3 and OGG)
pipenv run python trim_audio.py path/to/file.mp3 7 # Trim to 7 seconds
# Convert all MP3s to OGG for browser compatibility
pipenv run python convert_to_ogg.py- Sound System - Audio plugin architecture
- Lucas - His ideas, help, and enthusiasm helped make this game what it is
- Built with assistance from Cursor AI
- Audio processing using pydub and pygame
- Classical music: Rachmaninoff's Prelude in C-sharp minor, Beethoven's Symphony No. 5
Enjoy conquering the galaxy! 🌌👾🚀