🌌 Universe Simulation

A powerful JavaScript library for creating interactive universe simulations with Three.js

Live Demo | GitHub | NPM

📦 Installation

npm install universe-simulation

🚀 Quick Start

import UniverseSimulation from 'universe-simulation';

// Create simulation instance
const universe = new UniverseSimulation({
  container: document.getElementById('canvas-container'),
  width: window.innerWidth,
  height: window.innerHeight
});

// Initialize
await universe.init();

// Add a sun
await universe.addSun({
  radius: 10,
  position: new THREE.Vector3(0, 0, 0)
});

// Add Earth
await universe.addPlanet({
  name: 'earth',
  radius: 1,
  distance: 50,
  speed: 0.001,
  color: 0x2233ff
});

// Start the simulation
universe.start();

🎯 Features

• 🌟 Full Universe Scale: From planetary surfaces to the edge of the observable universe
• ⚡ High Performance: Optimized with Nanite-like LOD system and Web Workers
• 🎨 Stunning Visuals: JWST-inspired nebulae, HDR rendering, custom shaders
• 📱 Mobile Ready: Touch controls and performance optimizations
• 🔧 Fully Customizable: Complete API control over all simulation aspects

📖 API Documentation

Core Class: UniverseSimulation

Constructor Options

const universe = new UniverseSimulation({
  container: HTMLElement,     // DOM element to render to (default: document.body)
  width: Number,             // Canvas width (default: window.innerWidth)
  height: Number,            // Canvas height (default: window.innerHeight)
  mobile: Boolean,           // Force mobile mode (auto-detected by default)
  renderOptions: {           // Additional Three.js renderer options
    antialias: Boolean,
    logarithmicDepthBuffer: Boolean
  }
});

Methods

async init()

Initialize the simulation. Must be called before adding any objects.

await universe.init();

async addSun(options)

Add a star to the simulation.

await universe.addSun({
  name: 'sol',                          // Unique identifier
  position: new THREE.Vector3(0, 0, 0), // Position in space
  radius: 10,                           // Size of the sun
  color: STAR_COLORS['G'],              // Star color (G-type by default)
  intensity: 3                          // Light intensity
});

async addPlanet(options)

Add a planet to the simulation.

await universe.addPlanet({
  name: 'earth',
  radius: 1,
  distance: 50,        // Orbital distance from center
  speed: 0.001,        // Orbital speed
  texture: null,       // THREE.Texture for planet surface
  color: 0x4444ff      // Color if no texture provided
});

async addGalaxy(options)

Add a galaxy to the simulation.

await universe.addGalaxy({
  name: 'andromeda',
  position: new THREE.Vector3(1000, 0, 0),
  type: 'spiral',      // 'spiral', 'elliptical', or 'irregular'
  scale: 1,
  starCount: 50000     // Number of stars (auto-reduced on mobile)
});

addNebula(options)

Add a nebula with JWST-inspired visuals.

universe.addNebula({
  name: 'orion',
  position: new THREE.Vector3(100, 50, -200),
  scale: 100,
  type: 'emission'     // Visual style preset
});

createObservableUniverse()

Generate the entire observable universe with galaxies, clusters, and cosmic web.

universe.createObservableUniverse();

focusOn(name, options)

Smoothly focus the camera on a celestial object.

universe.focusOn('earth', {
  distance: 10,        // Distance from object
  duration: 2000       // Animation duration in ms
});

start() / stop()

Control simulation playback.

universe.start();  // Begin animation loop
universe.stop();   // Pause animation loop

togglePause()

Toggle simulation pause state.

const isPaused = universe.togglePause();

setTimeScale(scale)

Control simulation speed.

universe.setTimeScale(10);  // 10x speed

resize(width, height)

Handle window resizing.

window.addEventListener('resize', () => {
  universe.resize(window.innerWidth, window.innerHeight);
});

dispose()

Clean up all resources.

universe.dispose();

getInternals()

Access Three.js internals for advanced usage.

const { scene, camera, renderer, THREE } = universe.getInternals();

🎨 Visual Constants

Star Colors

import { STAR_COLORS } from 'universe-simulation';

// Available star types
STAR_COLORS['O']  // Blue
STAR_COLORS['B']  // Blue-white
STAR_COLORS['A']  // White
STAR_COLORS['F']  // Yellow-white
STAR_COLORS['G']  // Yellow (Sun-like)
STAR_COLORS['K']  // Orange
STAR_COLORS['M']  // Red

Nebula Colors

import { NEBULA_COLORS } from 'universe-simulation';

// Emission, reflection, and other nebula color presets

📚 Examples

Complete Solar System

import UniverseSimulation, { AU_SCALE } from 'universe-simulation';

async function createSolarSystem() {
  const universe = new UniverseSimulation({
    container: document.getElementById('universe')
  });
  
  await universe.init();
  
  // Add Sun
  await universe.addSun({
    name: 'sun',
    radius: 10
  });
  
  // Add planets
  const planets = [
    { name: 'mercury', radius: 0.4, distance: 0.39 * AU_SCALE, speed: 0.002 },
    { name: 'venus', radius: 0.9, distance: 0.72 * AU_SCALE, speed: 0.0015 },
    { name: 'earth', radius: 1, distance: 1 * AU_SCALE, speed: 0.001 },
    { name: 'mars', radius: 0.5, distance: 1.52 * AU_SCALE, speed: 0.0008 },
    { name: 'jupiter', radius: 11, distance: 5.2 * AU_SCALE, speed: 0.0004 },
    { name: 'saturn', radius: 9, distance: 9.5 * AU_SCALE, speed: 0.0003 },
    { name: 'uranus', radius: 4, distance: 19.2 * AU_SCALE, speed: 0.0002 },
    { name: 'neptune', radius: 3.8, distance: 30 * AU_SCALE, speed: 0.0001 }
  ];
  
  for (const planet of planets) {
    await universe.addPlanet(planet);
  }
  
  universe.start();
  
  // Focus on Earth after 2 seconds
  setTimeout(() => {
    universe.focusOn('earth', { distance: 20 });
  }, 2000);
}

createSolarSystem();

Galaxy Cluster Visualization

async function createGalaxyCluster() {
  const universe = new UniverseSimulation();
  await universe.init();
  
  // Create multiple galaxies
  for (let i = 0; i < 10; i++) {
    const angle = (i / 10) * Math.PI * 2;
    const distance = 5000 + Math.random() * 5000;
    
    await universe.addGalaxy({
      name: `galaxy-${i}`,
      position: new THREE.Vector3(
        Math.cos(angle) * distance,
        (Math.random() - 0.5) * 1000,
        Math.sin(angle) * distance
      ),
      type: ['spiral', 'elliptical', 'irregular'][Math.floor(Math.random() * 3)],
      scale: 0.5 + Math.random() * 1.5
    });
  }
  
  universe.start();
}

Using with React

import React, { useEffect, useRef } from 'react';
import UniverseSimulation from 'universe-simulation';

function UniverseComponent() {
  const containerRef = useRef();
  const universeRef = useRef();
  
  useEffect(() => {
    async function init() {
      const universe = new UniverseSimulation({
        container: containerRef.current
      });
      
      await universe.init();
      await universe.addSun();
      await universe.addPlanet({ name: 'earth', distance: 50 });
      
      universe.start();
      universeRef.current = universe;
    }
    
    init();
    
    return () => {
      if (universeRef.current) {
        universeRef.current.dispose();
      }
    };
  }, []);
  
  return <div ref={containerRef} style={{ width: '100vw', height: '100vh' }} />;
}

🎮 Controls

The simulation includes built-in navigation controls:

Desktop

• WASD - Movement
• Mouse - Look around
• Space/Shift - Up/Down
• Scroll - Adjust speed

Mobile

• Touch - Look around
• Pinch - Zoom
• Double tap - Move forward

⚡ Performance Optimization

Nanite-like LOD System

The library includes an advanced LOD system that automatically adjusts object detail based on distance.

Web Workers

Heavy computations are offloaded to Web Workers for smooth performance.

Mobile Optimization

// The library automatically detects and optimizes for mobile
const universe = new UniverseSimulation({
  mobile: true  // Force mobile optimizations
});

🛠️ Advanced Usage

Custom Shaders

const customMaterial = new THREE.ShaderMaterial({
  uniforms: {
    time: { value: 0 },
    color: { value: new THREE.Color(0xff0000) }
  },
  vertexShader: `...`,
  fragmentShader: `...`
});

await universe.addPlanet({
  name: 'custom-planet',
  radius: 2,
  distance: 100,
  material: customMaterial  // Use custom material
});

Accessing Three.js

const { scene, camera, renderer, THREE } = universe.getInternals();

// Add custom objects directly
const customMesh = new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshBasicMaterial({ color: 0xff0000 })
);
scene.add(customMesh);

🛠️ Development

Clone the repository

git clone https://github.com/champi-dev/universesim.git
cd universesim
npm install

Run the demo locally

npm start

Build the library

npm run build:lib

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request to the GitHub repository.

🐛 Issues

Found a bug or have a feature request? Please open an issue on GitHub.

🙏 Acknowledgments

• NASA for astronomical data
• Three.js community
• JWST team for visual inspiration

Build your own universe, one star at a time ⭐