About •
Features •
Architecture •
Tech Stack •
Installation •
AI Collaboration •
Future Enhancements
This is a modern Python implementation of the classic Asteroids arcade game, built as a portfolio project demonstrating clean architecture, object-oriented programming principles, and polished game development. Originally created as part of Boot.dev's curriculum, this version has been significantly enhanced with professional-grade features including sophisticated collision detection, smooth visual transitions, persistent high score tracking, and a well-organized codebase.
The project showcases:
- Clean Architecture: Modular design with clear separation of concerns
- Advanced OOP: Proper inheritance hierarchies, polymorphism, and composition
- Game Polish: Fade transitions, particle effects, color cycling, and responsive controls
- Professional Practices: Type hints, comprehensive documentation, and logical code organization
- Classic Mechanics: Navigate your ship through space, destroying asteroids to progress through waves
- Progressive Difficulty: Each wave spawns more asteroids with increasing challenge
- Scoring System: Real-time score display with gradient color effects
- High Score Tracking: Top 5 high scores persist between sessions with player names
- Smooth Transitions: Context-aware fade effects
- Full-screen fades between major game states
- Text-only fades for wave transitions (stars remain visible)
- Animated name entry to high scores display
- Dynamic Starfield: Twinkling stars that move continuously through space
- Color Cycling: Rainbow gradient effects on titles and UI elements
- Particle Effects: Visual feedback on asteroid destruction
- Screen Shake: Impact feedback on collisions
- Intuitive Controls: Arrow keys for rotation, spacebar for thrust, and shooting
- Name Entry System: Interactive interface for recording high scores with visual placeholder
- Replay Option: Seamless transition from game over to new game
- Startup Sequence: Animated terminal-style boot sequence with system checks
- Triangle-Circle Collision: Mathematically accurate collision detection using barycentric coordinates
- Precise Hitboxes: Player hitbox matches visual triangle shape (not approximated as circle)
- Continuous Motion: Asteroids and stars continue moving during text fade transitions
- Event Logging: Optional JSON-based logging for game state and events
The project follows a modular, object-oriented architecture with clear separation of concerns:
src/
├── config/ # Game configuration and constants
│ ├── constants.py # All game constants (colors, speeds, dimensions)
│ └── funcs.py # Utility functions
│
└── game/
├── effects/ # Visual effects
│ └── fade.py # Multiple fade transition methods
│
├── entities/ # Game objects (sprites)
│ ├── asteroid.py # Asteroid with splitting logic
│ ├── asteroidfield.py # Spawning system
│ ├── particle.py # Particle effects
│ ├── player.py # Player ship with triangle hitbox
│ ├── shot.py # Projectile system
│ ├── star.py # Individual twinkling stars
│ └── starfield.py # Background star generation
│
├── main.py # Game loop and orchestration
│
├── screens/ # UI screens and components
│ ├── gameover.py # Game over with name entry
│ ├── screen.py # Abstract base screen class
│ ├── section.py # Reusable text rendering component
│ └── splash.py # Splash screen with high scores
│
├── shapes/ # Collision detection geometry
│ ├── circleshape.py # Circle collision logic
│ ├── shape.py # Base class for all game objects
│ └── triangleshape.py # Triangle collision with barycentric coords
│
├── systems/ # Support systems
│ ├── highscores.py # JSON-based persistence
│ ├── logger.py # Event and state logging
│ └── startup.py # Terminal-style boot sequence
Inheritance Hierarchy:
Shape (base)
├── CircleShape (radius-based collision)
│ ├── Asteroid
│ ├── Shot
│ ├── Particle
│ └── Star
└── TriangleShape (polygon-based collision)
└── Player
Screen System:
Screen (abstract base)
├── SplashScreen (title and high scores)
└── GameOverScreen (name entry and replay)
└── Section (reusable text component)
Key Principles Demonstrated:
- Single Responsibility: Each class has one clear purpose
- Open/Closed: Extensible through inheritance without modification
- Liskov Substitution: All shapes and screens properly override parent methods
- DRY (Don't Repeat Yourself): Section class eliminates UI duplication
- Composition over Inheritance: Screens compose Section objects
| Technology | Description |
|---|---|
 |
Modern Python with type hints and latest features |
 |
Game development framework for sprites, rendering, and input |
|
Fast, modern Python package manager and task runner |
|
Lightning-fast Python linter and formatter |
- Pygame CE 2.5.6+: Core game engine for graphics, sprites, and event handling
- Python 3.13+: Leverages modern Python features including enhanced type system
- UV Package Manager: Rapid dependency management and virtual environment handling
- Ruff: Code quality enforcement with 100-character line limit
- Python 3.13 or higher
- UV package manager (installation guide)
-
Clone the repository:
git clone https://github.com/YourUsername/asteroids cd asteroids -
Install dependencies (UV will automatically create a virtual environment):
uv sync
-
Run the game:
uv run main.py
- Arrow Keys: Rotate left/right, thrust forward
- Spacebar: Shoot
- Enter: Confirm selections (splash screen, name entry, replay)
- Backspace: Edit name during high score entry
- Y/N: Replay choice on game over
Game constants can be adjusted in src/config/constants.py:
- Player speed, rotation rate, and shoot cooldown
- Asteroid sizes, speeds, and spawn rates
- Screen dimensions and colors
- Logging preferences (game state and events)
This project demonstrates how AI can be an effective development accelerator and learning tool while highlighting the continued importance of human judgment in software architecture.
Rapid Implementation:
- Generated boilerplate code for game entities and systems
- Implemented complex algorithms (triangle-circle collision using barycentric coordinates)
- Created comprehensive fade transition system with multiple context-aware methods
- Automated import updates during large-scale refactoring (directory reorganization)
Problem-Solving Assistance:
- Debugged subtle issues like nested loop break statements preventing high score display
- Identified and fixed "warp speed" artifact during fade transitions (caused by updating positions while fading)
- Resolved import path issues after moving files to new directory structure
Learning Accelerator:
- Explained mathematical concepts (barycentric coordinates for point-in-triangle testing)
- Provided detailed rationale for architectural decisions
- Demonstrated Python-specific patterns and best practices
While AI proved invaluable for implementation speed, human intervention was critical for maintaining code quality and architectural integrity:
Architectural Decisions:
- Recognized when AI's "optimizations" violated the Liskov Substitution Principle by changing method signatures in child classes
- Identified code bloat from successive refactoring iterations and initiated cleanup
- Designed the logical directory structure organizing code by responsibility (entities, shapes, screens, effects, systems)
Pattern Recognition:
- Caught AI storing parameters unnecessarily in
__init__when they could be passed to methods - Noticed inconsistencies between SplashScreen and GameOverScreen parameter handling
- Recognized that the Section class pattern could eliminate code duplication across screens
OOP Principles:
- Understood that Python's flexible method signatures shouldn't violate inheritance contracts, even though technically allowed
- Saw the opportunity to create a Shape base class hierarchy before AI suggested it
- Ensured proper separation of concerns (collision logic in shape classes, rendering in entity classes)
Systemic Thinking:
- After multiple AI-driven refactors, recognized the need to audit for unused methods (
fade_out_screen,fade_in_screen) - Understood that different types of fades (full-screen vs. text-only) required separate methods, not overloaded behavior
- Anticipated that moving files would require coordinated import updates across multiple layers
AI excels at:
- Writing repetitive code quickly
- Implementing well-defined algorithms
- Searching for and fixing specific bugs
- Explaining technical concepts
Humans remain essential for:
- High-level architectural vision
- Recognizing when "optimizations" create technical debt
- Maintaining consistency across a growing codebase
- Applying design principles and patterns holistically
The most effective approach combines AI's speed with human judgment, using AI as a powerful tool while maintaining human oversight of system design and code quality.
Several features have been identified for potential future development:
- Lives System: Three lives with respawn mechanics and 1-up power-ups
- Power-ups: Shield, invincibility, rapid fire, and bombs
- Scoring Sophistication: Streak bonuses with visual feedback, distance multipliers
- Sound Effects: Engine thrust, shooting, explosions, and ambient music
- Difficulty Modes: Easy, Normal, Hard with different spawn rates and speeds
- Leaderboard Integration: Online high score submission and retrieval
- Replay System: Record and playback gameplay sessions
- Performance Optimization: Spatial partitioning for collision detection
- Configurable Controls: Key remapping through settings menu
- Test Suite: Comprehensive unit tests for collision detection and game logic
- Asset Management: Proper resource loading system for future sprite graphics
Caroline Jones - @Carolista - CodeWithCarrie.com - LinkedIn
This project is created for educational and portfolio purposes.