README
<p align="center"> A 3D marble racing game built with Three.js and Cannon-es physics, featuring 6 levels of increasing difficulty, glassmorphism UI, and a dynamic starfield background. </p>
<p align="center"> <img src="https://img.shields.io/badge/Three.js-0.161-blue?logo=three.js" alt="Three.js"/> <img src="https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript" alt="TypeScript"/> <img src="https://img.shields.io/badge/Vite-7.2-purple?logo=vite" alt="Vite"/> <img src="https://img.shields.io/badge/Physics-cannon--es-green" alt="cannon-es"/> </p>
Quick Start
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run buildOpen http://localhost:5173 and press any key to start.
Controls
| Key | Action |
|---|---|
| WASD / Arrow Keys | Move marble |
| Space | Jump |
| Mouse | Rotate camera |
| R | Restart level |
Levels
The game features 6 levels, each with a unique theme, skybox, and set of mechanics:
| # | Name | Time | Features |
|---|---|---|---|
| 1 | Practice Run | 45s | Gentle ramps, wide paths |
| 2 | The Valley | 75s | Elevation changes, open terrain |
| 3 | The Vortex | 60s | Spiral bowl, center hole drop |
| 4 | The Slalom | 65s | Banked S-curves, downhill racing |
| 5 | The Gauntlet | 75s | Tilted tiles, escalators, half-pipes |
| 6 | The Fortress | 90s | Turrets, water, trampolines, portals |
<p align="center"> <img src="docs/images/screenshot-action.png" alt="Action Shot" width="700"/> </p>
Game Elements
- Checkpoints - Save your progress and earn bonus time
- Escalators - Green tiles that push your marble forward
- Banked turns - Angled surfaces to maintain speed through curves
- Turrets - Shoot projectiles you need to dodge
- Water hazards - Fall in and lose a life
- Trampolines - Bounce across gaps
- Portals - Teleport between two points
- Collectibles - Extra lives, shields, and time bonuses
Documentation
For detailed gameplay tips and strategy, see the User Guide.
Tech Stack
- Three.js - 3D rendering with orthographic isometric camera
- cannon-es - Physics simulation (gravity, collisions, forces)
- TypeScript - Type-safe game logic
- Vite - Dev server and bundler
- Web Audio API - Procedural sound effects and background music
Building
# Production build
npm run build
# Preview production build
npm run preview
The built output goes to dist/ and can be served by any static file host.
License
ISC