solanapolis 1.0.0

package/README.md

@@ -0,0 +1,518 @@
+# SOLANApolis
+
+**powered by Heliopolis and Helius on Solana**
+
+A real-time 3D city built from Solana wallet activity — claim your building, earn your plane, drive your car, explore the globe, and fly anywhere on Earth.
+
+## What is this?
+
+SOLANApolis visualizes the Solana blockchain as a living city. Every wallet that has ever swapped tokens on Solana becomes a building. The more you've traded, the taller and more elaborate your building. Sign in with Phantom, and your building appears on the skyline — along with your personal plane or car if you claimed a slot early enough. Then zoom out to an interactive 3D globe, pick any location on Earth, and explore it with real satellite terrain and OSM Buildings — all rendered in your browser or streamed from an Unreal Engine 5 backend.
+
+## City Slots
+
+SOLANApolis has a **limited** economy. There are only **1,000 total wallet slots** in the city, and the first to claim get the best perks:
+
+| Slot Type | Capacity | Perk |
+|-----------|----------|------|
+| ✈ **Planes** | 100 | First 100 wallets each get a personal plane that circles above their building |
+| 🚗 **Cars** | 250 | First 250 wallets each get a resident car that drives the city streets |
+| 🏢 **Buildings** | 1,000 | All wallets get a unique building sized by their on-chain activity |
+
+- **Planes** orbit above their owner's building at unique altitudes, speeds, and colors
+- **Cars** continuously cruise the streets near their owner's block, each with a distinct color from a 20-color palette
+- **Clicking** any plane or car focuses the camera on the owner's building and shows their wallet info
+- The **UI badge** in the top-left corner shows real-time slot fill progress for wallets, planes, and cars
+
+## Features
+
+### 3D Solana City
+- Every Solana wallet address with swap history generates a unique building
+- Building height, width, and detail scale with trading volume and transaction count
+- Buildings are deterministically colored from wallet address — no two look alike
+- Five **skyscraper types** for downtown buildings: Setback (Art Deco), Twin Peaks, Cantilever, Spire, and standard Box — each with multi-tier geometry and procedural windows
+- **Procedural window shader** with per-window color variation (warm yellow, cool white, amber, blue TV glow), per-window on/off state based on time of day, slow pulsing, and day/night transitions
+- Day/night cycle with dynamic lighting, fog, atmospheric haze, and stars
+- Instanced mesh rendering for thousands of buildings at 60fps
+- Parks, trees, lamp posts, road dashes, and sidewalks — all instanced
+- **Beach scene** with animated ocean, waves, seagulls, and boats along the southern shoreline
+
+### 🌍 Globe View (NEW)
+- **Interactive 3D Earth** powered by CesiumJS with real satellite imagery and terrain
+- **OSM Buildings 3D Tiles** (Cesium Ion asset #96188) — millions of real-world buildings with height-based color coding:
+  - 🔴 Red: 200m+ (skyscrapers)
+  - 🟠 Orange: 100–200m (major towers)
+  - 🟡 Yellow: 50–100m (tall buildings)
+  - 🟢 Teal: 20–50m (mid-rise)
+  - 🔵 Blue: under 20m (low-rise)
+- **Per-building metadata popovers** — hover over any building to see its name, address, type, floor count, and height (adapted from Cesium's dynamic metadata UI patterns)
+- **📍 Locations** — instant fly-to for 9 world cities: New York, London, Tokyo, Dubai, Paris, San Francisco, Sydney, Giza, Solana Beach
+- **🌏 Earth View** — zoom out to see the full planet from space
+- **Double-click** any location to transition directly to the Cesium flight simulator there
+- **Shift+click** — Google Street View panel via Cesium Ion's experimental `/experimental/panoramas/google` endpoint
+- **Live HUD** showing real-time LAT / LON / ALT as you navigate
+- **B** toggle buildings on/off, **L** toggle locations panel, **Esc** return to city
+
+### Cesium Flight Simulator
+- Full-screen flight simulator powered by Cesium.js with real satellite imagery and 3D terrain
+- Spawns at London (51.5074°N, 0.1278°W) at 500m altitude, or at coordinates selected from the Globe view
+- Aircraft physics with realistic banking:
+  - Throttle controls (W/S) with realistic acceleration
+  - Roll-induced yaw for realistic banking turns (A/D keys)
+  - Climb rate tied to pitch (Space/E)
+  - Gravity and stall simulation
+  - Crash detection when altitude < 5m
+- Follow camera positioned correctly **behind** the aircraft with banking tilt and dynamic FOV
+- Camera toggle (C) between follow and orbit views
+- HUD showing speed (km/h), altitude (m), and heading (°)
+- Crash screen with instant restart
+- Error handling with retry/exit UI when initialization fails
+
+### Resident Planes (100 slots)
+- First 100 wallets each get a 3D plane (fuselage, wings, tail fin) rendered via instanced meshes
+- Each plane circles above its owner's building with unique orbit radius (8–26 units), altitude, angular speed, and warm color tint
+- Planes bank gently into turns and oscillate in altitude
+- Hover to see wallet info tooltip; click to navigate to the building
+
+### Resident Cars (250 slots)
+- First 250 wallets each get a detailed 3D car (body, glass cabin, 4 wheels, floating diamond marker)
+- Cars continuously drive city streets following paths generated from their building's block
+- Each car has a unique color from a curated 20-color palette
+- Cars automatically regenerate new routes when they reach the end of a path
+- Hover to see wallet info; click to zoom to the owner's building
+
+### Swap Cars (AI Traffic)
+- Live swap events from the database spawn AI-driven cars that drive through the city
+- Up to 60 concurrent swap cars with fade-in/drive/fade-out lifecycle
+- Each car carries swap metadata (token in/out, SOL amount)
+- Click any swap car to open the swap info panel and follow it with the camera
+- **Swap particles**: GPU-accelerated particle bursts fire at buildings when their wallet's swap car spawns — frame-rate independent physics
+
+### New Building Spotlight
+- When a new wallet connects, a gold pulsing spotlight beam appears on their building
+- Animated ring + point light effect that fades out after 8 seconds
+- Triggered by new Phantom wallet connections in real time
+
+### Phantom Connect
+- Sign in with your Solana wallet via Phantom Connect SDK
+- Supports Google, Apple, and injected wallet providers
+- OAuth redirect flow works on both `heliopolis-main.vercel.app` and `heliopolis.ngrok.app`
+- Your wallet address auto-generates your building the moment you connect
+- If you're among the first 100/250, your plane or car appears automatically
+
+### Three.js Plane Mode
+- In-city flight with a detailed plane model (capsule fuselage, swept wings, winglets, under-wing engines with intake rings, afterburner cones, and engine glow lights)
+- YXZ Euler rotation order for proper heading/pitch/roll (standard aircraft convention)
+- WASD + Q/E controls with pointer-lock mouse look
+- Chase camera follows behind and above the plane
+
+### Mapbox Mini-Map
+- Live 180×180px Mapbox GL mini-map in the flight simulator overlay
+- Dark map style with an orange aircraft marker that rotates to match your heading
+- Smooth `easeTo()` camera following at ~10fps updates
+
+### Multiplayer Flying
+- Two separate Supabase Realtime broadcast channels:
+  - `heliopolis-planes` — Three.js city fly-through mode (XYZ coordinates)
+  - `heliopolis-cesium-planes` — Cesium flight simulator mode (lat/lon/alt/heading)
+- See other connected wallets flying as 3D plane meshes in real time
+- Remote planes use smooth lerp/slerp interpolation for fluid motion
+- Plane color is deterministically derived from wallet address
+
+### Player Car Mode
+- Drive a car through the city streets in third-person
+- Bicycle-model physics with acceleration, braking, and steering
+- AABB collision detection against all buildings and houses
+- Chase camera follows behind and above the car
+- WASD + Space controls
+- **Combat-ready** — fire projectiles with F or left-click while driving
+
+### Combat System
+- **Available in both car and plane modes** — enter Drive or Fly mode to start shooting
+- Press **F** or **left-click** to fire projectiles
+- Projectiles travel at 120 units/sec with slight gravity drop
+- Fire rate: ~6.6 shots/sec (0.15s cooldown), up to 50 active projectiles
+- **Hit detection**: sphere-based collision against all 100 resident planes and 250 resident cars
+- **Scoring**: 50 points per plane hit, 25 points per car hit
+- **Visual effects**:
+  - Glowing orange bullet heads (sphere geometry)
+  - Velocity-aligned stretch trails behind each projectile
+  - Expanding icosahedron explosions at hit locations (1 second lifetime)
+  - Muzzle flash point light when firing
+  - On-screen hit marker (✕) flash on successful hits
+
+### Game HUD & Minimap
+- **Real-time tactical minimap** (200×200px canvas, top-right corner)
+  - All buildings shown as gray dots
+  - Resident planes as amber dots
+  - Resident cars as indigo dots
+  - Active projectiles as red dots
+  - Hit locations as expanding red rings (2 second fadeout)
+  - Player position as an orange triangle with heading indicator
+  - FOV cone showing player's field of view
+  - Pulsing ring around the player position
+  - Grid overlay for spatial reference
+  - Legend showing dot color meanings
+- **Score bar** (top-center) showing:
+  - Current mode (✈ AIR / 🚗 GROUND)
+  - Live score counter (smooth animation)
+  - Hit count
+  - Active projectile count
+  - Fire key hint
+- **Crosshair** (center screen) — bracket-style with orange center dot
+- All HUD elements auto-show when entering car/plane mode, auto-hide when exiting
+
+### Day/Night Cycle
+- 8-keyframe system covering dawn, sunrise, day, golden hour, sunset, dusk, night, and late night
+- Smooth interpolation of sky color, fog, ambient/directional/hemisphere/accent lights, sun position, and star opacity
+- Procedural window illumination that responds to time — windows turn on at sunset, glow through the night, and switch off at dawn
+- Lamp posts illuminate at night with emissive glow decals
+
+### Building Interaction
+- Click any building to open the wallet info panel (transaction count, volume, age, fees, token list)
+- Hover windows on selected buildings to see per-window token tooltips
+- Selection beam highlight with animated glow
+- Window hover detection uses the same UV math as the shader for pixel-perfect accuracy
+
+### Network Stats HUD
+- Live Solana network stats: TPS (with color-coded delta), slot number, and epoch progress bar
+- Polls every 10 seconds
+- Gradient progress bar from indigo → orange
+
+### Twitter Auth
+- Sign in with Twitter/X via Supabase OAuth
+- Auth state persists across sessions
+- Citizen ID Card modal for authenticated wallets
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js 16 (App Router, Turbopack) |
+| 3D City | React Three Fiber + drei + Three.js |
+| Shaders | Custom GLSL (PBR building shader, house shader, headlight decals, GPU particles) |
+| Globe & Flight | Cesium.js v1.139 + Cesium Ion (3D terrain + OSM Buildings) |
+| Street View | Cesium Ion Experimental API (`/experimental/panoramas/google`) |
+| Mini-Map | Mapbox GL v3 |
+| Wallet Auth | @phantom/react-sdk |
+| OAuth | Supabase Auth (Twitter) |
+| Multiplayer | Supabase Realtime Broadcast |
+| Blockchain Data | Helius API (Solana) |
+| Token Prices | BirdEye API |
+| Styling | Tailwind CSS |
+| Deployment | Vercel |
+| UE5 Backend | Unreal Engine 5.7 + CesiumForUnreal + SolanaSDK + Pixel Streaming |
+| Solana Runtime | .NET 9 + Solnet 5.x (SOLANApolisRuntime) |
+
+## Controls
+
+### 🌍 Globe View
+| Input | Action |
+|-------|--------|
+| Left-click drag | Rotate globe |
+| Right-click drag | Pan |
+| Scroll | Zoom |
+| Middle-click | Tilt |
+| Double-click | Fly to location (opens Cesium flight) |
+| Shift+click | Open Street View panel |
+| B | Toggle OSM buildings |
+| L | Toggle locations panel |
+| 📍 Locations | Quick-jump to 9 world cities |
+| 🌏 Earth | Zoom out to full Earth |
+| Esc | Return to city |
+
+### Cesium Flight Simulator
+| Key | Action |
+|-----|--------|
+| W | Increase throttle |
+| S | Decrease throttle |
+| A | Bank left |
+| D | Bank right |
+| Space | Climb |
+| Q | Roll left |
+| E | Roll right / Descend |
+| C | Toggle camera mode |
+| Esc | Exit flight simulator |
+
+### Three.js Plane Mode
+| Key | Action |
+|-----|--------|
+| W / ↑ | Throttle up |
+| S / ↓ | Throttle down |
+| A / ← | Bank left |
+| D / → | Bank right |
+| Q / Space | Climb |
+| E | Descend |
+| F / Left-click | Fire projectile |
+| Esc | Exit plane mode |
+
+### Car Mode
+| Key | Action |
+|-----|--------|
+| W / ↑ | Accelerate |
+| S / ↓ | Brake / Reverse |
+| A / ← | Steer left |
+| D / → | Steer right |
+| Space | Brake |
+| F / Left-click | Fire projectile |
+| Esc | Exit car mode |
+
+### City View
+| Input | Action |
+|-------|--------|
+| Left-click + drag | Pan / Orbit |
+| Right-click + drag | Rotate / Pan |
+| Scroll | Zoom |
+| Click building | Select wallet |
+| Click car | Follow car |
+
+## Setup
+
+### Prerequisites
+- Node.js 18+
+- A Vercel account (for deployment)
+- .NET 9 (for SOLANApolisRuntime, optional)
+- Unreal Engine 5.7 (for UE5 backend, optional)
+
+### Environment Variables
+
+Create `.env.local`:
+
+```env
+# Helius (Solana RPC)
+HELIUS_API_KEY=your_helius_api_key
+HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your_key
+HELIUS_WSS_URL=wss://mainnet.helius-rpc.com/?api-key=your_key
+HELIUS_WEBHOOK_SECRET=your_webhook_secret
+HELIUS_WEBHOOK_ID=your_webhook_id
+
+# Supabase
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+
+# Phantom Connect
+PHANTOM_APP_ID=your_phantom_app_id
+
+# BirdEye
+BIRDEYE_API_KEY=your_birdeye_api_key
+BIRDEYE_WSS_URL=wss://public-api.birdeye.so/socket/solana?x-api-key=your_key
+
+# Cesium Ion (required for Globe + Flight)
+NEXT_PUBLIC_CESIUM_ION_TOKEN=your_cesium_ion_token
+
+# Mapbox
+NEXT_PUBLIC_MAPBOX_TOKEN=your_mapbox_token
+
+# Pixel Streaming (optional, for UE5 backend)
+NEXT_PUBLIC_PIXEL_STREAMING_URL=ws://localhost:8888
+```
+
+### Install & Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+### Build
+
+```bash
+npm run build
+npm start
+```
+
+### UE5 Backend Setup (Optional)
+
+The UE5 backend provides high-fidelity rendering streamed via Pixel Streaming:
+
+```bash
+# 1. Link plugins into the UE5 project
+cd SOLANApolis-UE5
+./setup-plugins.sh
+
+# 2. Build the Solana runtime (.NET 9)
+./build-solanakit.sh
+
+# 3. Open in Unreal Engine 5.7.x
+#    SOLANApolis-UE5/SOLANApolis.uproject
+
+# 4. Configure Cesium Ion token in Project Settings → Plugins → Cesium
+
+# 5. Launch with Pixel Streaming
+SOLANApolis -PixelStreamingIP=0.0.0.0 -PixelStreamingPort=8888
+
+# 6. Set NEXT_PUBLIC_PIXEL_STREAMING_URL=ws://your-server:8888 in .env.local
+```
+
+## Architecture
+
+```
+src/
+├── app/
+│   ├── layout.tsx                  # PhantomWrapper + AuthProvider
+│   ├── page.tsx                    # Main entry — dynamic import of CityScene
+│   ├── globals.css                 # Tailwind + activity animation keyframes
+│   ├── auth/callback/page.tsx      # Phantom OAuth redirect handler
+│   └── api/
+│       ├── wallets/route.ts        # GET all placed wallets with identity data
+│       ├── wallet/[address]/       # Wallet lookup, balances, identity, tokens
+│       ├── network-stats/route.ts  # Solana TPS, slot, epoch progress
+│       ├── webhooks/helius/        # Helius webhook receiver
+│       └── auth/                   # Phantom auth, callback, link-wallet
+├── components/
+│   ├── CityScene.tsx               # Root 3D scene — orchestrates all components
+│   ├── CityGrid.tsx                # City layout: roads, sidewalks, blocks, parks
+│   ├── CesiumGlobe.tsx             # 🌍 Interactive 3D Earth + OSM Buildings + metadata
+│   ├── CesiumFlight.tsx            # ✈ Full Cesium flight simulator
+│   ├── PixelStreamViewer.tsx       # UE5 Pixel Streaming WebRTC viewer
+│   ├── InstancedBuildings.tsx      # Plain box buildings (instanced mesh + PBR shader)
+│   ├── InstancedSkyscrapers.tsx    # Multi-tier skyscrapers (setback, twin, cantilever, spire)
+│   ├── InstancedCityPlanes.tsx     # 100 resident planes circling owner buildings
+│   ├── InstancedResidentCars.tsx   # 250 resident cars driving city streets
+│   ├── InstancedCars.tsx           # AI swap-event cars (up to 60)
+│   ├── InstancedHouses.tsx         # Low-rise placeholder houses
+│   ├── InstancedTrees.tsx          # Park + sidewalk trees
+│   ├── InstancedLampPosts.tsx      # Street lamps with night glow
+│   ├── InstancedRoadDashes.tsx     # Road center-line dashes
+│   ├── FlightMiniMap.tsx           # Mapbox mini-map overlay
+│   ├── PlaneMode.tsx               # Three.js in-city plane mode
+│   ├── PlayerPlane.tsx             # Player-controlled plane (detailed 3D mesh)
+│   ├── PlayerCar.tsx               # Player-controlled car with collision
+│   ├── MultiplayerPlanes.tsx       # Supabase Realtime multiplayer
+│   ├── BeachScene.tsx              # Animated ocean, waves, seagulls, boats
+│   ├── SceneLighting.tsx           # 5-light rig + stars + fog
+│   ├── SelectionBeam.tsx           # Building selection glow beam
+│   ├── SwapParticles.tsx           # GPU particle bursts on swap events
+│   ├── NewBuildingSpotlight.tsx    # Gold spotlight on new buildings
+│   ├── ProjectileRenderer.tsx      # Instanced projectile bullets + explosions
+│   ├── GameHUD.tsx                 # Real-time minimap + score bar + crosshair
+│   ├── CitySlotsBadge.tsx          # UI: wallet/plane/car slot counters
+│   ├── WalletPanel.tsx             # Wallet info side panel
+│   ├── SwapPanel.tsx               # Swap car info panel
+│   ├── WindowTooltip.tsx           # Building/token hover tooltip
+│   ├── WalletSearch.tsx            # Top search bar with autocomplete
+│   ├── ActivityFeed.tsx            # Left-side activity stream
+│   ├── NetworkStats.tsx            # Bottom-right TPS/slot/epoch HUD
+│   ├── AuthPanel.tsx               # Wallet + Twitter auth UI
+│   ├── HowItWorksModal.tsx         # Info modal
+│   ├── CitizenCardModal.tsx        # Citizen ID card (lazy loaded)
+│   ├── Ground.tsx                  # Ground plane mesh
+│   ├── Park.tsx                    # Park block with grass
+│   ├── LeaderboardPanel.tsx        # Combat leaderboard
+│   ├── GameChat.tsx                # In-game chat
+│   └── PhantomWrapper.tsx          # Client-side PhantomProvider wrapper
+├── context/
+│   └── AuthContext.tsx              # Auth state (Supabase + Phantom)
+├── lib/
+│   ├── city-slots.ts               # Slot constants (1000 wallets, 100 planes, 250 cars)
+│   ├── city-constants.ts           # Grid layout: block size, road positions, park blocks
+│   ├── city-zoning.ts              # Zone classification: downtown, midrise, lowrise, park
+│   ├── building-math.ts            # Building dimensions, colors, window attributes
+│   ├── building-shader.ts          # Custom GLSL PBR shader with procedural windows
+│   ├── house-shader.ts             # House PBR shader with day/night tinting
+│   ├── skyscraper-types.ts         # Skyscraper tier definitions (setback, twin, etc.)
+│   ├── player-plane.ts             # Plane physics engine (speed, heading, pitch, roll)
+│   ├── player-car.ts               # Car physics engine (bicycle model + collision)
+│   ├── collision-map.ts            # AABB spatial hash collision detection
+│   ├── car-system.ts               # AI car lifecycle manager (spawn, update, despawn)
+│   ├── car-paths.ts                # City path generation for AI cars
+│   ├── day-night.ts                # 8-keyframe day/night interpolation system
+│   ├── swap-events.ts              # Swap event polling from Supabase
+│   ├── projectile-system.ts        # Projectile physics, lifecycle, and hit detection
+│   ├── multiplayer-manager.ts      # Supabase Realtime multiplayer sync
+│   ├── sound-engine.ts             # Audio engine: plane engine, clicks
+│   ├── supabase.ts                 # Supabase client (browser)
+│   └── supabase-admin.ts           # Supabase admin client (server)
+├── types/
+│   └── wallet.ts                   # WalletBuilding + PlacedWallet interfaces
+
+SOLANApolis-UE5/                    # Unreal Engine 5.7 project (optional)
+├── SOLANApolis.uproject            # Project file (CesiumForUnreal + SolanaSDK + PixelStreaming)
+├── setup-plugins.sh                # Symlink plugins into the UE5 project
+├── build-solanakit.sh              # Build .NET 9 Solana runtime
+├── Source/
+│   ├── SOLANApolis.Target.cs       # Game target rules
+│   ├── SOLANApolisEditor.Target.cs # Editor target rules
+│   └── SOLANApolis/
+│       ├── SOLANApolis.Build.cs    # Module build rules
+│       ├── SOLANApolisFlightPawn.h/.cpp  # Flight pawn with Cesium globe anchor, Solana wallet, combat
+│       └── SOLANApolisChainBridge.h/.cpp # Solana → UE5 bridge (balance, skins, kills)
+├── SolanaKit/
+│   └── SOLANApolisRuntime.csproj   # .NET 9 Solana runtime (Solnet 5.x)
+└── Plugins/ (symlinked)
+    ├── CesiumForUnreal → cesium-unreal-main
+    └── SolanaSDK → Solana-Unreal-SDK-main
+
+Solana-Unreal-SDK-main/             # Solana SDK for UE5
+├── SolanaSDK.uplugin              # Plugin descriptor (UnrealSOLNET + LinkStream)
+└── ...
+
+public/
+├── plane.glb                       # Aircraft 3D model
+├── helius-icon.svg                 # Helius logo icon
+└── helius-logo.svg                 # Helius logo full
+```
+
+## Deployment
+
+The web app is deployed to Vercel:
+
+```bash
+vercel --prod
+```
+
+**Required Vercel environment variables** — add all variables from `.env.local` in the Vercel dashboard under Project Settings → Environment Variables.
+
+### UE5 Pixel Streaming Deployment
+
+For production UE5 streaming, deploy the built UE5 project to a GPU instance (AWS g4dn, Azure NV, etc.) with:
+
+```bash
+SOLANApolis -RenderOffscreen -PixelStreamingIP=0.0.0.0 -PixelStreamingPort=8888 -ForceRes -ResX=1920 -ResY=1080
+```
+
+Then set `NEXT_PUBLIC_PIXEL_STREAMING_URL` to the WebSocket URL of the signaling server.
+
+## Phantom Connect Configuration
+
+In the [Phantom developer portal](https://developer.phantom.com), configure your app with these redirect URLs:
+- `https://heliopolis-main.vercel.app/auth/callback`
+- `https://heliopolis.ngrok.app/auth/callback`
+- `http://localhost:3000/auth/callback` (for local dev)
+
+## Supabase Configuration
+
+Enable the following in your Supabase project:
+- **Auth → Providers**: Enable Twitter/X OAuth with your API keys
+- **Realtime**: Enable broadcast on the `public` schema
+- **Database**: The app reads wallet addresses from the `wallets` table
+- **RPC function**: `get_random_swaps(n)` returns random swap events for car traffic
+- **RPC function**: `repair_unplaced_wallets()` self-heals unplaced complete wallets
+
+## Performance
+
+SOLANApolis is engineered for 60fps even with thousands of objects:
+
+- **Instanced rendering** for all repeated geometry (buildings, skyscrapers, trees, lamp posts, cars, planes, road dashes)
+- **Custom GLSL shaders** injected into Three.js standard PBR — no `onBeforeCompile` (avoids program cache invalidation)
+- **GPU particle system** for swap burst effects with custom vertex/fragment shaders
+- **Frame-rate independent physics** — all physics simulations use actual frame delta, never hardcoded timesteps
+- **Ref-based state** for high-frequency updates (time, car positions, camera) to avoid React re-renders
+- **Lazy loading** for heavy components (CesiumFlight, CesiumGlobe, CitizenCardModal)
+- **Spatial hash** collision detection for O(1) car-building collision queries
+- **Cesium Ion streaming** — terrain and building tiles loaded on-demand, not preloaded
+- **Pixel Streaming** (optional) — stream UE5 rendering over WebRTC for high-fidelity clients
+
+## Credits
+
+- Flight simulator physics adapted from [cesium-flight-simulator](https://github.com/nicktarnold/cesium-flight-simulator)
+- Globe architecture inspired by [Cesium VR tutorials](https://cesium.com/learn/) (Viewing the Globe, Dynamic Metadata UI)
+- Blockchain data powered by [Helius](https://helius.dev)
+- Token prices from [BirdEye](https://birdeye.so)
+- Maps by [Mapbox](https://mapbox.com)
+- Satellite imagery via [Cesium](https://cesium.com) + OpenStreetMap
+- OSM Buildings 3D Tiles via [Cesium Ion](https://ion.cesium.com) asset #96188
+- Solana SDK for UE5 by [Bifrost Technologies](https://github.com/Bifrost-Technologies/Solana-Unreal-SDK)
+- Google Street View via [Cesium Ion experimental API](https://cesium.com/docs/rest-api/)