Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

SolarSystem Lab

An interactive 3D physics laboratory for building planetary systems, changing their initial conditions, and watching gravity, collisions, climate, tides, and atmospheres evolve in real time.

SolarSystem Lab runs entirely in the browser. It combines an approachable educational interface with inspectable physical models and portable experiment files, making it useful both for exploration and repeatable sandbox experiments.

Highlights

  • Real-time Three.js scene with textured planets, atmospheric layers, clouds, rings, shadows, bloom, and a procedural starfield.
  • Newtonian N-body gravity in SI units with leapfrog and semi-implicit Euler integrators.
  • Play, pause, logarithmic time control, free camera, focus, zoom, pan, top view, trails, velocity vectors, acceleration vectors, and predicted trajectories.
  • Editable mass, radius, velocity, orbital distance, rotation period, axial tilt, material preset, ocean mass, and atmospheric CO₂.
  • Creation and launch of planets, moons, stars, comets, gas giants, and black holes.
  • General collision classification: mergers, absorption, hit-and-run encounters, catastrophic disruption, debris, and progressive Roche breakup.
  • Collision accounting for mass, linear momentum, angular momentum, spin, composition, deposited heat, and ejecta energy.
  • Local impact damage with physically scaled craters, surface shockwaves, ejecta deposits, water loss, and atmospheric erosion.
  • Layered body composition with cores, mantles, surfaces, oceans, and atmospheres.
  • Material properties including density, heat capacity, emissivity, phase changes, latent heat, and derived radii.
  • Dynamic stellar heating from one or more stars using inverse-square flux, albedo, emissivity, heat redistribution, and greenhouse forcing.
  • A 64×32 surface climate grid with day/night insolation, thermal diffusion, temperature, liquid water, ice, and persistent impact damage overlays.
  • Cell-level habitability scoring and overlay based on temperature, liquid water, atmospheric pressure, and local impact damage.
  • Tidal torque, spin-orbit exchange, tidal heating, synchronous locking, and progressive Roche stress.
  • Atmospheric condensation and evaporation of water and CO₂, plus species-aware Jeans escape for light gases.
  • Age- and metallicity-aware stellar evolution through main sequence, subgiant, red-giant mass loss, terminal events, and mass-dependent remnants.
  • Energy-limited comet sublimation and anti-stellar tails, deterministic stellar flares, pulsar beams, and black-hole accretion and lensing visualization.
  • Live diagnostics for energy, linear momentum, angular momentum, orbital period, temperature, material properties, atmosphere, and collision history.
  • Twelve reproducible scenarios, including the Solar System, Earth–Moon impact, binary stars, orbital resonance, a hot Jupiter, Roche disruption, and a comet.
  • Browser-local saves, versioned JSON import/export, automatic v1→v2 migration, telemetry charts, and CSV export.
  • Realtime and Precision policies, exact worker-based gravity for large systems, checkpoints, A/B comparison, and selected-body mass sweeps.

Pages

URL Purpose
/ Product landing page
/simulation.html Interactive 3D laboratory

The laboratory always includes a link back to the landing page.

Quick start

Requirements: a current Node.js release, npm, and a browser with WebGL support.

npm install
npm run dev

Open the URL printed by Webpack Dev Server. Source changes are rebuilt automatically and reflected through live reload.

Commands

npm run dev     # development server with rebuild and live reload
npm run build   # production-style static output in dist/
npm test        # Node test suite for physics, climate, pages, and persistence

There is currently no lint or static type-check script.

How to use the laboratory

  1. Choose a scenario from the toolbar or start with the complete Solar System.
  2. Select a body from the focus menu, its label, or directly in the 3D scene.
  3. Change time speed, pause the simulation, or compare the two integrators.
  4. Open Advanced controls to modify physical and orbital properties.
  5. Enable trails, prediction, vector overlays, or a surface climate layer.
  6. Use Add body and drag across the scene to define its launch velocity.
  7. Save locally, export the experiment as JSON, or export selected telemetry as CSV.

Changing orbital distance intentionally preserves current velocity, allowing the new gravitational acceleration to alter the orbit. Use Circularize when a balanced circular orbit is the desired result.

Included scenarios

  • Solar System
  • Earth–Moon laboratory
  • Moon impacts Earth
  • Binary stars
  • Hot Jupiter
  • Planetary collision
  • Rogue planet flyby
  • Comet flyby
  • 1:2:4 orbital resonance
  • Roche limit laboratory
  • Habitable-zone laboratory
  • Supernova laboratory

All scenarios use editable SI initial conditions and can be reset independently. See docs/SCENARIOS.md for details.

Physical model

Simulation state uses metres, kilograms, and seconds. Rendering uses a separate, compressed visual scale so planets remain visible while astronomical distances remain navigable. The Moon’s orbit is amplified visually only; its physical state is unchanged.

The default leapfrog integrator provides better long-term orbital stability. Semi-implicit Euler remains available for educational comparison. High time speeds use bounded adaptive substeps, so extreme experiments remain interactive but should not be treated as professional ephemerides.

Impact, atmosphere, climate, and tidal systems are generalized lightweight models. They preserve and expose the most important relationships and budgets, but they are not replacements for high-resolution hydrodynamic, geophysical, or weather solvers.

Architecture

src/
├── landing.html      Product landing page
├── app.html          WebGL laboratory host
├── index.js          Runtime orchestration and Three.js scene
├── physics.js        N-body dynamics, collision regimes, thermal physics
├── bodies.js         Body catalogue, presets, meshes, and textures
├── materials.js      Layered composition, material properties, energy ledger
├── climate.js        Surface grid and GPU-ready climate overlays
├── atmosphere.js     Phase exchange and Jeans escape
├── impacts.js        Crater, shockwave, ejecta, and atmosphere-loss scaling
├── stellar.js        Stellar lifetime, phases, mass loss, and remnants
├── phenomena.js      Comets, flares, pulsars, accretion, and lensing state
├── laboratory.js     Modes, checkpoints, comparisons, and parameter sweeps
├── worker-kernel.js  Transferable-array exact N-body integration
├── worker-client.js  Browser Worker lifecycle and state application
├── tides.js          Tidal torque, heating, locking, and Roche stress
├── scenarios.js      Reproducible initial conditions
├── persistence.js    Versioned experiment schema and migration
├── telemetry.js      Time-series collection and CSV export
└── ui.js             Toolbar, editors, panels, and charts

Webpack emits the static landing page, laboratory page, JavaScript bundle, and local texture assets into dist/. The dist/ directory is generated output and must not be edited as source.

Experiment data

Experiment JSON uses schema version 2 and stores body state, layered composition, energy reservoirs, climate grids, integration settings, and scenario metadata. Legacy version 1 saves are migrated automatically when imported.

No backend, account, remote API, or environment variable is required. Local saves use browser storage; JSON and CSV exports remain under the user’s control.

Testing

The test suite covers orbital stability, Kepler solving, continuous collision detection, collision conservation, thermal flux, material merging, climate grids, tides, atmospheric escape, impact damage, persistence migration, scenarios, telemetry, and landing/laboratory reachability.

npm test
npm run build

Browser end-to-end coverage and formal performance budgets remain roadmap items.

Assets and attribution

Local 2K equirectangular textures come from Solar System Scope and are distributed under CC BY 4.0. They are based on NASA and mission imagery. See docs/ASSET_ATTRIBUTION.md.

Documentation

All user-facing documentation and landing-page copy must be written in English.

Current roadmap status

Material and energy modeling, local climate, tides, impact damage, atmosphere, terraforming, local habitability, and first-generation stellar evolution are implemented. First-generation advanced phenomena, worker-based scaling, Precision mode, checkpoints, A/B comparison, and parameter sweeps are also available. See the roadmap for the authoritative status and future calibration work.

License

The source code is licensed under the ISC license. Third-party visual assets retain their respective attribution and license requirements.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages