Update README with full game description, controls, and setup instructions

README.md

@@ -1,3 +1,53 @@
-# asteroids
+# Asteroids (1979 Clone)
 
-Clone of the classic 1979 Atari Asteroids arcade game. Python + Pygame implementation with vector graphics, toroidal screen wrapping, rotating/thrusting ship, shooting, asteroid breakup, scoring, and lives.
+A faithful Python + Pygame reimplementation of the classic **1979 Atari Asteroids** arcade game.
+
+## Gameplay
+
+- Pilot your triangular ship through a field of asteroids
+- Rotate, thrust, and shoot to survive
+- Asteroids break into smaller pieces when hit
+- Everything wraps around the edges of the screen (toroidal topology)
+- Score points by destroying asteroids
+- You have 3 lives — avoid collisions!
+
+## Features Implemented
+- Vector-style line graphics (classic look)
+- Smooth ship rotation and acceleration
+- Bullet firing with limited on-screen bullets
+- Large/Medium/Small asteroids with proper splitting
+- Screen wrapping for ship, asteroids, and bullets
+- Score counter and lives display
+- Game over / restart
+- Simple sound effects using Pygame mixer (optional)
+
+## Controls
+
+| Key          | Action          |
+|--------------|-----------------|
+| Left/Right   | Rotate ship     |
+| Up           | Thrust forward  |
+| Space        | Fire bullet     |
+| H            | Hyperspace (random jump) |
+| P            | Pause / Resume  |
+| R            | Restart (game over) |
+| ESC          | Quit            |
+
+## How to Run
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the game
+python asteroids.py
+```
+
+## Requirements
+- Python 3.8 or newer
+- Pygame >= 2.0
+
+## Notes
+This is a fan recreation for learning and fun. It captures the core mechanics and feel of the 1979 original. No original assets or code from Atari are used.
+
+Enjoy the nostalgia!