🌌 Universe Simulation

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

Live Demo | GitHub | NPM

📦 Installation

bash npm install universe-simulation

🚀 Quick Start

```javascript 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

javascript 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.

javascript await universe.init();

async addSun(options)

Add a star to the simulation.

javascript 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.

javascript 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.

javascript 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.

javascript 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.

javascript universe.createObservableUniverse();

focusOn(name, options)

Smoothly focus the camera on a celestial object.

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

start() / stop()

Control simulation playback.

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

togglePause()

Toggle simulation pause state.

javascript const isPaused = universe.togglePause();

setTimeScale(scale)

Control simulation speed.

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

resize(width, height)

Handle window resizing.

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

dispose()

Clean up all resources.

javascript universe.dispose();

getInternals()

Access Three.js internals for advanced usage.

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

🎨 Visual Constants

Star Colors

```javascript import { STAR_COLORS } from 'universe-simulation';

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

Nebula Colors

```javascript import { NEBULA_COLORS } from 'universe-simulation';

// Emission, reflection, and other nebula color presets ```

📚 Examples

Complete Solar System

```javascript 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 * AUSCALE, speed: 0.002 }, { name: 'venus', radius: 0.9, distance: 0.72 * AUSCALE, speed: 0.0015 }, { name: 'earth', radius: 1, distance: 1 * AUSCALE, speed: 0.001 }, { name: 'mars', radius: 0.5, distance: 1.52 * AUSCALE, speed: 0.0008 }, { name: 'jupiter', radius: 11, distance: 5.2 * AUSCALE, speed: 0.0004 }, { name: 'saturn', radius: 9, distance: 9.5 * AUSCALE, speed: 0.0003 }, { name: 'uranus', radius: 4, distance: 19.2 * AUSCALE, speed: 0.0002 }, { name: 'neptune', radius: 3.8, distance: 30 * AUSCALE, 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

```javascript 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

```javascript 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