Terravroom

Drive anywhere on planet Earth in full 3D. Terravroom is a high-performance, browser-based 3D driving simulation built with Three.js and Vite. It streams real-world road networks, architectural buildings, bridges, elevated transit viaducts, terrain elevations, street furniture, vegetation, and live traffic dynamically using real OpenStreetMap (OSM) data worldwide.

🌟 Highlights & Key Features

🌍 Real-World Global Streaming & Multi-Mirror Failover

• Live OpenStreetMap Ingestion: Procedurally generates 3D road ribbons, complex junctions, multi-tier buildings, multipolygon architectural landmarks, parks, and waterways on-the-fly via high-speed Overpass API endpoints.
• Ultra-Fast Multi-Mirror Network: High-availability mirror failover (maps.mail.ru, overpass-api.de, lz4, kumi, private.coffee) ensuring instantaneous ingestion worldwide (e.g., Lahore, Tokyo, Monaco, New York, Paris, London, Nürburgring).
• Persistent IndexedDB Cache: Downloaded regions are stored in browser IndexedDB for zero-latency instant replays and offline capability.
• Infinite Procedural Fallback: Seamlessly generates structured procedural cities if unmapped terrain is encountered.

🗺️ Vector World Map & Neon Road Cartography

• Interactive Global Location Picker: Seamless Leaflet-powered world map with Nominatim geocoding search and custom latitude/longitude teleportation.
• True Neon Roads Tile Engine: Custom raster-to-neon tile processor (NeonTileProcessor.js & NeonMapRenderer.js) transforming standard dark OpenStreetMap tiles into luminous electric cyan road vectors on obsidian black backdrops.
• Real-Time Active Country Highlight: Built-in vector world map background (WorldMapBackground.js) with point-in-polygon country boundary detection and pulsing neon country highlights for the active spawn point.

🏎️ 3D Garage Showroom & 4 Iconic Vehicle Classes

Explore authentic .glb 3D vehicle models rendered in a dedicated 360° turntable showroom with floor reflections, detailed vehicle specification sheets, interactive audio rev previews, and real-time paint customization via the CyberColorPicker:

| Vehicle | Class / Badge | Top Speed | Nitro Speed | 0–100 km/h | Drivetrain | Sound Profile | Handling & Dynamics | | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :--- | :--- | | Mazda RX-7 FD3S | ROTARY | 255 km/h | 320 km/h | 3.2s | RWD | 13B Twin-Rotor Turbo | 50:50 balance, featherweight chassis, high downforce, razor-sharp touge drift tuning. | | Lamborghini Aventador | V12 BULL | 350 km/h | 420 km/h | 2.8s | AWD (Haldex IV) | 6.5L Naturally Aspirated V12 | Carbon monocoque, 8,500 RPM scream, active aero vectoring, 50ms ISR gearbox shifts. | | Nissan Skyline R34 | GODZILLA | 315 km/h | 395 km/h | 2.7s | AWD (ATTESA E-TS) | 2.6L RB26DETT Twin-Turbo | Legendary twin-turbo inline-6, active torque-vectoring AWD, circuit-dominating grip. | | Nova 396 Big Block | V8 MUSCLE | 235 km/h | 300 km/h | 3.8s | RWD (Positraction) | 6.5L 396ci Big Block V8 | Raw American muscle, massive low-end torque, thunderous rumble, tire-shredding power-slides. |

• CyberColorPicker & Swatches: Select from 9 curated gloss presets (Crimson Red, Sunset Orange, Cyber Yellow, Emerald Green, Neon Cyan, Electric Blue, Deep Purple, Pure White, Midnight Black) or pick any custom hex shade with live 3D preview.

🚦 Autonomous Dynamic Road Traffic

• OSM Spline-Based AI Traffic: Autonomous vehicles (sedans, vans, city buses) procedurally spawned and navigating along real OSM road centerlines.
• Day/Night Lighting Integration: Traffic vehicles automatically activate glowing Xenon headlights and red taillight ground illumination in sunset, night, and cyberpunk lighting conditions.
• Configurable Density: Adjust traffic density from Off to Low, Realistic, or High directly from the Settings menu.

🎧 Warm Harmonic Procedural Audio Synthesizer

• Harmonic Additive Engine Synth: Powered by the Web Audio API using filtered sub-bass sine waves and warm low-pass triangle waves with soft-clipping saturation (no harsh square-wave buzzing).
• Acoustic Signatures per Vehicle: Unique audio profiles matching each car (screaming twin-rotor turbo, high-revving 8,500 RPM V12, twin-turbo inline-6 purr, and deep throaty V8 rumble).
• Dynamic Sound Effects: Progressive engine RPM pitch modulation, turbo blow-off valve hiss, pink-noise tire screech on drifts, metallic obstacle crash impacts, horn (H), and in-menu audio rev testing.

🛣️ Multi-Tier Roadways & Elevated Viaduct Architecture

• Expressways & Highways: Dark high-grip asphalt with realistic aggregate noise, yellow inner shoulder line, solid white outer shoulder, and proportional dashed white lane divider markings.
• City Streets & Avenues: Multi-lane urban roads with double solid yellow centerlines and sidewalk curbs.
• Local Streets & Alleys: Clean paving without intrusive markings.
• Elevated Viaducts & Metro Lines: Dynamic clearances for elevated transit systems (e.g. Lahore Orange Line Metro viaduct) supported by structural concrete columns so vehicles drive cleanly underneath without clipping.
• Anti-Clipping Road Filter: Automatically detects and removes ground-level building footprints that intersect drivable road surfaces.

🏢 4 Architectural Building Facade Styles

Procedurally textured building extrusions classified by height, type, and location:

1. Modern Reflective Glass Skyscraper: Deep sapphire/cyan curtain-wall glass with steel mullions.
2. Commercial High-Rise: Slate cladding with tinted office windows and horizontal floor louvers.
3. Residential Sandstone & Brick Apartments: Warm natural stone facade with window casings and balcony trims.
4. Contemporary Concrete / Civic: Architectural precast concrete panels with expansion seams and ribbon windows.

💡 Interactive Street Furniture & Physical Obstacle Collisions

• Roadside Streetlamps: Correctly aligned streetlamps whose fixture arms extend directly inward over the asphalt surface from both curbs. Includes realistic nighttime light pools and dynamic spot lights that actively react to the time of day.
• Obstacle Collisions: Physical collision detection for streetlamp posts and tree trunks with realistic momentum deceleration and bounceback.

🌳 Lush Procedural Vegetation System

• Roadside Boulevards: Tree-lined sidewalks featuring leafy oaks, tropical date palms, and roadside shrubs placed at natural intervals along all drivable streets.
• Park Groves: Natural clusters of 3D oak, pine, and palm trees throughout parks, grass polygons, and recreational spaces.

🏁 Checkpoint Street Race Mode

• Generates procedural multi-checkpoint street racing circuits using the surrounding real-world road topology.
• Real-time race timer, animated 3D checkpoint arches, dynamic minimap course route visualization, and victory celebration overlays.

⛅ Dynamic 24-Hour Lighting & Real-World Timezone Presets

Press N or click the atmospheric lighting toggle to switch between 7 rich lighting and timezone configurations:

• ☀️ Day: Crisp sunlight with realistic soft shadows and natural ambient skylight.
• 🌅 Sunset: Warm golden-hour orange and purple horizon glow.
• 🌙 Night: Pitch-dark realistic night atmosphere with forward Xenon LED headlight beams and dynamic red taillight / brake light ground projections.
• 🔮 Cyberpunk: Neon cyan and magenta atmospheric illumination with high-contrast reflections.
• 🌫️ Foggy: Dense moody atmospheric mist.
• 💻 System Time (Sys Time): Dynamically calculates your local computer system clock and applies Day, Sunset, or Night accordingly.
• 📍 City Solar Time (City Time): Dynamically calculates real solar time at the selected city's longitude (spawnLon / 15.0). Teleporting to Tokyo, Monaco, Lahore, or New York sets the true real-world local time of that city!

🎥 6 Advanced Camera Perspectives

Press C to cycle or press keys 1 through 6 to switch instantly:

1. Chase Cam (1): Dynamic third-person camera with smooth spring physics and speed-dependent FOV expansion.
2. Roof Cam (2): Elevated chase perspective anchored above the vehicle roofline.
3. Hood Cam (3): Fixed bonnet camera anchored above the front splitter with zero lag at high speeds.
4. Bumper / 1st Person Cam (4): Pure front nose camera with vehicle body hidden for 100% clean forward visibility.
5. Interior Cockpit Cam (5): Driver seat point of view looking out over the dashboard and windscreen.
6. Free / Orbit Cam (6): Free 360° mouse-drag inspection view around the vehicle.

📊 Telemetry Bento Overlay & TerraAI Copilot

• Dark Bento Telemetry Grid (T / B): Fullscreen spotlight telemetry grid with live sparklines, G-force gauges, tire temperature, surface grip %, and OSM node counters.
• Mini Telemetry Bar: Compact HUD widgets displayed directly above the GPS radar showing Lateral G, Surface Grip %, Tire Temp (°C), and Active Roads Count.
• TerraAI Driving Copilot: Slide-out AI assistant drawer offering contextual driving tips, city history, car tuning suggestions, and Web Speech voice output.
• Driver.js Tour Guide: Interactive onboarding walk-through introducing HUD elements, radar controls, and telemetry features.
• Driver Profile & Stats: Driver license dashboard tracking total distance traveled (km), top speed achieved, drift points, and completed races stored in localStorage.

🎮 Controls & Keybindings

| Key / Control | Action | | :--- | :--- | | W / ↑ / Z | Accelerate Throttle | | S / ↓ | Brake / Reverse | | A / D or ← / → / Q | Steer Left / Right | | Shift | Engage Nitro Boost 🔥 | | Space | Handbrake Power-Slide Drift | | C | Cycle Camera Mode (Chase → Roof → Hood → Bumper → Interior → Free) | | 1 – 6 | Jump Directly to Camera Mode (1: Chase, 2: Roof, 3: Hood, 4: Bumper, 5: Interior, 6: Free) | | L | Toggle Vehicle Headlights (Day / Night Xenon Beams) | | R | Reset Vehicle to Nearest Drivable Road | | N | Cycle Lighting & Weather (Day → Sunset → Night → Cyberpunk → Foggy → Sys Time → City Time) | | M | Toggle & Expand Live 2D GPS Radar Minimap | | T / B | Toggle Telemetry Bento Grid & Mini HUD Bar | | H | Sound Vehicle Horn / Cycle HUD Visibility Mode | | X | Toggle 3D Skeleton / Wireframe Mesh Inspection | | Right Mouse Drag | Orbit Camera Angle (in Orbit / Free Mode) | | Mouse Wheel | Zoom Camera In / Out |

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• npm (bundled with Node.js)

Installation & Run

1. Clone the repository:

   git clone https://github.com/RasikhAli/Terravroom.git
   cd Terravroom
   

2. Install dependencies:

   npm install
   

3. Start the local development server:

   npm run dev
   

4. Open in browser: Navigate to http://localhost:5173/ in your browser.

5. Build for production:

   npm run build
   

6. Preview production build locally:

   npm run preview
   

🌍 Popular Preset Locations

Choose any custom coordinate on Earth via the interactive world map and search bar, or jump directly into built-in presets:

| Location | Country | Coordinates | Highlights | | :--- | :---: | :---: | :--- | | Lahore | 🇵🇰 Pakistan | 31.5204° N, 74.3587° E | Multan Road, Mall Road, Orange Line elevated viaduct, and historic city grid. | | Monaco | 🇲🇨 Monte Carlo | 43.7384° N, 7.4246° E | Famous tight harbor hairpin corners, coastal elevation, and seaside boulevard. | | Shibuya Crossing | 🇯🇵 Tokyo, Japan | 35.6595° N, 139.7005° E | Dense skyscraper canyon, crosswalks, and Japanese city road layout. | | Times Square | 🇺🇸 New York, USA | 40.7580° N, -73.9855° W | Iconic Manhattan grid with massive high-rise architecture and avenues. | | Nürburgring Nordschleife | 🇩🇪 Germany | 50.3356° N, 6.9475° E | Famous 20+ km forest circuit curves, elevation changes, and high-speed straights. | | Eiffel Tower | 🇫🇷 Paris, France | 48.8584° N, 2.2945° E | Wide Parisian boulevards, roundabouts, and Seine river bridges. |

🛠️ Project Architecture

Terravroom/
├── index.html                   # Main HTML entry point with modern typography & viewport configuration
├── package.json                 # Dependencies (Three.js r185, Vite 8, Leaflet, Anime.js, Driver.js, Lucide)
├── style.css                    # Comprehensive cyber-glassmorphic styling system & UI components
├── vite.config.js               # Vite configuration with server host rules
├── public/
│   ├── favicon.svg              # Vector favicon
│   ├── icons.svg                # Icon sprites
│   └── models/                  # High-quality 3D .glb vehicle models
│       ├── mazda-rx7.glb        # Mazda RX-7 FD3S model
│       ├── lamborghini.glb      # Lamborghini Aventador model
│       ├── nissan-skyline.glb   # Nissan Skyline R34 model
│       ├── muscle-car.glb       # Nova 396 Big Block muscle car model
│       └── audi-e-tron.glb      # Electric performance model
└── src/
    ├── main.js                  # Main orchestrator, Game lifecycle loop & hotkey bindings
    ├── assets/
    │   └── world-countries.json # GeoJSON vector boundaries for global country highlighting
    ├── config/
    │   └── vehicles.js          # Vehicle configs, specs, sound profiles, paint swatches & presets
    ├── engine/
    │   ├── Elevation.js         # Simplex noise topographical elevation engine
    │   ├── LabelManager.js      # 3D floating street & district name labels
    │   ├── PlayerStats.js       # Driver license mileage, high speed & race statistics tracker
    │   ├── RaceManager.js       # Procedural checkpoint race circuit builder & timer
    │   ├── SceneManager.js      # WebGL renderer, 6 cameras, post-processing & 7 lighting modes
    │   ├── Showroom.js          # Interactive 3D garage turntable showroom
    │   ├── StreetProps.js       # Instanced streetlamps, night light pools & physical colliders
    │   ├── TileManager.js       # Concentric geographical chunking, Overpass streaming & tile caching
    │   ├── TrafficManager.js    # Autonomous multi-vehicle AI traffic on OSM road splines
    │   ├── VegetationProps.js   # Procedural roadside boulevards, palms, oaks & park foliage
    │   └── VehicleVisualFactory.js # 3D GLB model loader & procedural fallback generator
    ├── osm/
    │   ├── GeometryBuilder.js   # 3D procedural roads, ribbons, viaducts, junctions & facades
    │   └── OverpassClient.js    # Multi-mirror Overpass API fetcher with IndexedDB caching
    ├── physics/
    │   ├── CarController.js     # Raycast suspension, drift physics, nitro & collision dynamics
    │   └── SoundEngine.js       # Web Audio API harmonic additive synthesizer & acoustic profiles
    ├── ui/
    │   ├── AssistantUI.js       # TerraAI conversational copilot drawer & voice assistant
    │   ├── BentoGrid.js         # Spotlight telemetry dashboard & live sparklines
    │   ├── CyberColorPicker.js  # Interactive hex color picker with 3D live preview
    │   ├── HUD.js               # Driving dashboard, tachometer, speedometer & radar minimap
    │   ├── LocationPicker.js    # Leaflet world map with Nominatim geocoder
    │   ├── MainMenu.js          # Next-gen 3D garage showroom, vehicle picker & neon map selector
    │   ├── NeonMapRenderer.js   # Canvas neon cartography renderer with glowing beacons
    │   ├── NeonTileProcessor.js # Dark OSM vector tile to electric neon road transformer
    │   ├── SettingsModal.js     # Comprehensive settings modal (Graphics, Audio, Camera, Traffic)
    │   ├── SoundPreview.js      # In-menu audio rev preview synthesizer
    │   ├── ThumbnailRenderer.js # Offscreen vehicle thumbnail snapshot generator
    │   ├── TourGuide.js         # Interactive Driver.js tour guide onboarding
    │   └── WorldMapBackground.js# Vector world map canvas with real-time country boundary highlight
    └── utils/
        └── GeoUtils.js          # WGS84 geodesy, Mercator meter projections & coordinate math

🚢 Deployment

Terravroom is a static client-side WebGL application that can be deployed to any static host, CDN, or cloud server (Render, Vercel, Netlify, Hostinger, Ubuntu VPS with Nginx, or Docker).

For complete, step-by-step deployment instructions, refer to DEPLOYMENT.md.

📄 License & Attribution

• Source Code: Released under the MIT License.
• Map Data: OpenStreetMap data is licensed under the Open Data Commons Open Database License (ODbL) © OpenStreetMap contributors.
• Map Tiles: CartoDB Dark Matter tiles © CARTO © OpenStreetMap contributors.