A modern, browser-based reimagining of the classic Asteroids arcade game — built with TypeScript, Three.js, and an Entity-Component-System architecture.
- 3D Graphics — Procedurally generated asteroid meshes, particle explosions, screen shake, and a scrolling starfield
- Multiple Weapons — Single shot, spread shot, laser beam, and homing missiles
- Power-Up System — Shield, rapid fire, multi-shot, and extra life drops
- Boss Encounters — Unique bosses every 5 waves with distinct attack patterns and AI
- Wave Progression — Increasing difficulty with asteroid count, speed, and spawn scaling
- Audio — Sound effects and background music with per-channel volume controls (Howler.js)
- Leaderboard — Local high score tracking with name entry
- Strict TypeScript — Full strict-mode compiler with no implicit
any, null checks, and unused detection
# Clone the repository
git clone https://github.com/Zxela/asteroids.git
cd asteroids
# Install dependencies
npm install
# Start development server
npm run devOpen http://localhost:5173 in your browser.
| Key | Action |
|---|---|
| W / Up Arrow | Thrust forward |
| A / Left Arrow | Rotate left |
| D / Right Arrow | Rotate right |
| Space | Fire weapon |
| Escape | Pause game |
| Category | Tool |
|---|---|
| Rendering | Three.js — WebGPU / WebGL 2 |
| Language | TypeScript 5.7 (strict mode) |
| Build | Vite 6 |
| Testing | Vitest with V8 coverage (51 test files) |
| Audio | Howler.js |
| Linting & Formatting | Biome |
| Hosting | Netlify |
The game uses an Entity-Component-System (ECS) pattern for clean separation of data and logic:
Entities Components Systems
───────── ────────────── ────────────────
Ship → Transform, Velocity, InputSystem
Asteroids → Physics, Collider, PhysicsSystem
Projectiles → Health, Weapon, CollisionSystem
Power-Ups → Renderable, ... DamageSystem
Bosses WeaponSystem
WaveSystem
RenderSystem
AudioSystem
Game state is managed via a Finite State Machine: Loading → MainMenu → Playing ⇄ Paused → GameOver.
src/
├── main.ts # Entry point
├── game/ # Game loop and orchestration
├── ecs/ # Core ECS engine
├── components/ # Component definitions
├── systems/ # Game systems (input, physics, render, etc.)
├── entities/ # Entity factory functions
├── rendering/ # Three.js scene, camera, and mesh management
├── state/ # Finite state machine
├── ui/ # HUD, menus, and overlays
├── config/ # Tuning constants and game configuration
└── types/ # Shared TypeScript type definitions
npm run dev # Start dev server with HMR
npm run build # Type-check + production build
npm run preview # Serve production build locally
npm run test # Run test suite
npm run test:watch # Run tests in watch mode
npm run test:coverage # Generate V8 coverage report
npm run check # Biome lint + format (auto-fix)
npm run check:all # Lint + tests
npm run check:deps # Circular dependency check
npm run check:unused # Unused exports check (knip)| Browser | Version |
|---|---|
| Chrome | 90+ |
| Firefox | 90+ |
| Safari | 15+ |
| Edge | 90+ |
MIT