Nebula Runner

A browser-based endless space runner dodge asteroids, collect orbs, and survive the void

Overview

Nebula Runner is a fully browser-based endless space runner built with Next.js 15 and the HTML5 Canvas API no backend, no sign-up, no configuration required. It runs entirely offline with all game state persisted to localStorage. Unlike Flash-era games or heavy Unity WebGL exports, it loads instantly and plays at 60fps on any modern browser, including mobile.

✨ Features

• 🚀 Physics-based ship movement smooth velocity and tilt with mouse, touch, and D-pad controls
• 🎯 4 escalating difficulty tiers EASY → MEDIUM → HARD → INSANE, each unlocking new obstacle types
• 💥 Combo multiplier system chain orb collections for up to 5× score multiplier
• 🛡️ Power-ups Shield, Slow Motion, and Invincibility with expiry warnings
• ☄️ Asteroid split mechanic near-misses at MEDIUM+ have a 25% chance to fracture asteroids
• 🌀 Black holes accretion disk visuals and gravitational lensing effects
• ⚡ Laser beam obstacles 1.5s warning phase followed by a 2s active kill zone (HARD+)
• 🏎️ Speed zones entering one doubles ship speed for 3 seconds (INSANE)
• 🌟 3-layer parallax star field warp-speed motion blur kicks in above score 200
• 🎵 Procedural audio 13 distinct sounds synthesized via Web Audio API, zero audio files
• 🏆 Achievement system unlockable achievements persisted to localStorage
• 📱 Mobile D-pad 60fps continuous movement with diagonal support via held directions
• 💫 Particle effects collision burst, orb collection spiral, thruster exhaust
• 📳 Screen shake on collision with linear decay

🛠 Tech Stack

🚀 Quick Start

Prerequisites

• Node.js 18+
• pnpm (npm install -g pnpm)

Installation

# 1. Clone the repo
git clone https://github.com/MuhammadTanveerAbbas/nebula-runner.git
cd nebula-runner

# 2. Install dependencies
pnpm install

# 3. Run the development server
pnpm dev

# 4. Open in browser
# http://localhost:3000

🔐 Environment Variables

No environment variables are required. The game runs fully offline with zero configuration.

If you want to add optional deployment or analytics integrations, create a .env.local file:

# Deployment (optional)
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Analytics (optional)
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id

📁 Project Structure

nebula-runner/
├── public/              # Static assets (favicon, robots.txt)
├── src/
│   ├── app/             # Next.js App Router (layout, page, sitemap)
│   ├── components/      # UI + game components (GameCanvas, MobileControls, etc.)
│   │   └── ui/          # shadcn/ui primitives
│   ├── hooks/           # Custom React hooks (useGameEngine, use-mobile)
│   └── lib/
│       └── game/        # Core game engine (audio, constants, types, utils)
├── .env.example
├── package.json
└── README.md

📦 Available Scripts

🎮 Game Controls

🌐 Deployment

This project is deployed on Vercel.

Deploy Your Own

1. Click the button above
2. Connect your GitHub account
3. Deploy no environment variables needed

🗺 Roadmap

• [x] Physics-based ship movement
• [x] 4 difficulty tiers with unique obstacles
• [x] Combo multiplier system
• [x] Power-ups (Shield, Slow Motion, Invincibility)
• [x] Procedural Web Audio synthesis
• [x] Achievement system with localStorage persistence
• [x] Mobile D-pad with 60fps continuous movement
• [ ] Global leaderboard
• [ ] Additional power-up types
• [ ] Unlockable ship skins

🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

👨‍💻 Built by The MVP Guy