Universe Lab

Universe Lab is a collection of interactive simulations of spacetime, black holes, and gravitational lensing.

Simulations

• Event Horizon (/descent): Fall through a supermassive black hole with a freely controlled cockpit camera, a live 3D ship view, flight-stage guidance, and music that follows the descent at its original tempo.

• Spacetime Curvature (/spacetime): Drag stellar objects across a rubber-sheet spacetime grid warped by the Schwarzschild metric.

• Black Holes (/black-hole): Orbit a Schwarzschild black hole with an event horizon, photon sphere, Doppler-beamed accretion disk, and screen-space gravitational lensing of the background stars.

• Gravitational Lensing (/lensing): Move a distant source behind a foreground galaxy to form multiple images, luminous arcs, and Einstein rings with GPU inverse ray shooting through stars, dark matter, tidal shear, and satellite substructure.

Features

• Authentic Physics: Uses true Schwarzschild metric h(r) = rs/r where rs = 2GM/c²
• Interactive Masses: Drag and drop solar mass objects (0.5-10 M☉)
• Real-time Visualization: GPU-accelerated GLSL shaders for smooth 60fps+ performance
• Collision Detection: Prevents mass overlap with dynamic radius calculation
• Responsive Design: Works on desktop and mobile devices, with device-adaptive quality
• Natural Units: Uses G=1, c=1 scaling standard in theoretical physics

Tech Stack

• Framework: Next.js 16 with App Router
• 3D Graphics: Three.js with react-three-fiber
• Shaders: Custom GLSL vertex/fragment shaders
• Styling: Tailwind CSS v4
• State Management: Zustand
• Language: TypeScript
• Lint/Format: Biome
• Git Hooks: Lefthook

Getting Started

Prerequisites

• Node.js 20.9+
• npm

Installation

1. Clone the repository:

   git clone https://github.com/stephenw310/universe-lab universe-lab
   cd universe-lab

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

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

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run typecheck - Type check with tsc --noEmit
• npm run test:descent - Check descent physics, planet tracking, and music timing
• npm run lint - Lint and check formatting with Biome
• npm run lint:fix - Apply Biome fixes, including Tailwind class sorting
• npm run format - Format code with Biome

Git hooks are managed by Lefthook and installed automatically by npm install. On commit, Biome formats and fixes staged files and tsc type checks the project.

How to Use

1. View the Grid: The warped grid represents spacetime curvature
2. Drag Masses: Click and drag the colored spheres to move them
3. Adjust Mass: Use the control panel to change mass values (0.5-10 solar masses)
4. Add/Remove: Use buttons to add new masses or remove existing ones
5. Navigate:
   • Left click + drag: Rotate camera
   • Right click + drag: Pan camera
   • Scroll wheel: Zoom in/out

Physics Implementation

The visualization uses the Schwarzschild metric for gravitational curvature:

// Schwarzschild radius: rs = 2GM/c²
float schwarzschildRadius = 2.0 * G * mass / (c * c);
// Height displacement: h = rs/r
float height = schwarzschildRadius / distance;

• G = 1.0: Gravitational constant (scaled for visualization)
• c = 1.0: Speed of light (natural units)
• Mass range: 0.5-10 solar masses for realistic curvature

License

MIT License