🚀 Asteroids Game

A classic arcade-style space shooter built with Python and Pygame, where you pilot a ship through an asteroid field and blast rocks into smaller fragments while trying to survive as long as possible.

---

📖 Description

This project is a faithful recreation of the iconic Asteroids arcade game.
You control a spaceship drifting through space, destroying asteroids that fragment into smaller pieces upon impact. As the game progresses, the number of objects on screen increases, creating a fast-paced and progressively challenging experience.

The implementation focuses on clean game architecture, physics-based movement, and frame-rate independent gameplay, making it both playable and easy to extend.

---

✨ Features

• Smooth player controls
  Responsive rotation and thrust using physics-based movement.

• Dynamic shooting mechanics
  Projectile firing with a configurable cooldown system.

• Asteroid spawning system
  Randomized asteroid generation from screen edges.

• Accurate collision detection
  Circle-based hitboxes for consistent and efficient collision checks.

• Asteroid splitting logic
  Large asteroids split into medium, medium into small, and small are destroyed.

• 60 FPS gameplay
  Delta-time based movement for frame-rate independence.

• Game state logging
  Automatic logging of events for debugging and analysis.

---

🎮 How to Play

Controls

• W — Thrust forward
• S — Thrust backward
• A — Rotate left
• D — Rotate right
• SPACE — Shoot (0.3s cooldown)

Objective

Destroy asteroids while avoiding collisions.

• Large asteroids split into medium
• Medium asteroids split into small
• Small asteroids are destroyed completely
• Colliding with any asteroid ends the game

Survive as long as possible while managing increasing screen chaos.

---

🛠️ Installation & Setup

Prerequisites

• Python 3.12+
• uv package manager

Steps

# Clone the repository
git clone https://github.com/Utkarsh736/asteroids.git

# Navigate to the project directory
cd asteroids

# Install dependencies
uv sync

# Run the game
uv run main.py

---

🔧 Technologies Used

• Python 3.12 — Core programming language
• Pygame 2.6.1 — Rendering, input handling, and game loop
• uv — Fast Python dependency management
• Vector Math — pygame.math.Vector2 for physics calculations

---

📁 Project Structure

asteroids/
├── main.py           # Game loop and initialization
├── player.py         # Player ship logic
├── asteroid.py       # Asteroid entity with splitting behavior
├── shot.py           # Bullet projectile logic
├── circleshape.py    # Base class for circular game entities
├── asteroidfield.py  # Asteroid spawning and management
├── logger.py         # Game state and event logging
├── constants.py      # Game configuration and tuning
└── .gitignore        # Ignored files (logs, cache, etc.)

---

🚧 Future Enhancements

• Score tracking and high-score persistence
• Lives and respawn mechanics
• Power-ups (shields, rapid fire, bombs)
• Sound effects and background music
• Multiple difficulty levels
• Particle effects for explosions
• Screen wrapping (teleporting across edges)
• Start menu, pause, and game-over screens

---

🤝 Contributing

Contributions are welcome.

1. Fork the repository

2. Create a feature branch

   git checkout -b feature/AmazingFeature

3. Commit your changes

   git commit -m "Add AmazingFeature"

4. Push to the branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

---

📝 License

This project is open source and available under the MIT License.

---

🙏 Acknowledgments

Built as part of the Boot.dev Python course, focusing on hands-on learning of game development fundamentals using Python and Pygame.