# spacekit: a Three.js engine for 3D space scenes

> spacekit is a TypeScript library that turns a container element into an interactive 3D scene of the Earth, the Moon, a solar system or an asteroid belt, on top of Three.js r186. The honest framing is that it is a work in progress with an unstable API, that it needs WebGL 2, and that its asset files are hosted by default on the project's own site.

**typpo/spacekit** — Javascript library for 3D space visualizations

- Repository: https://github.com/typpo/spacekit
- Website: https://typpo.github.io/spacekit/
- Stars: 584 · Forks: 47
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/typpo-spacekit

## A generalisation of several one-off space visualisations

Spacekit is described as a JavaScript library for creating interactive 3D space visualisations, whether of the Earth and moon system, the solar system, or beyond. The README frames the project as generalising work that is currently used on several separate sites, including Asterank, Meteor Showers, Ancient Earth and others, into a single open source 3D engine for space that is both accurate and visually striking.

That origin story explains the shape of the API. The components are named after the things those sites each built for themselves: a Simulation that holds a camera and whatever you put in it, a Skybox for the background, Stars for a real star field, SpaceObject for anything that orbits or rotates, KeplerParticles for many small orbiting bodies, and a BlackHole. The project is MIT licensed, the npm package is spacekit.js, the default branch is master, and the last push to the repository was on 2026-10-12. There are no GitHub releases.

Two caveats appear early in the README and both matter. The library is a work in progress and the API might change, and it requires WebGL 2 and uses Three.js r186, with devices without WebGL 2 support receiving an error when creating a Simulation.

## Installing it and the three ways to load it

The install is an npm install.

```bash
npm install spacekit.js
```

And then you use it with require or import.

```js
const Spacekit = require('spacekit.js');
// or
import Spacekit from 'spacekit.js';
```

There is also a third route, a raw build in a script tag, which is what you would use if you are not using a bundler at all.

```html
<script src="https://typpo.github.io/spacekit/build/spacekit.js"></script>
```

The build output is a global named Spacekit, which is why the browser bundle in the package.json sets the esbuild global-name to Spacekit. The package also ships a CommonJS build at build/spacekit.cjs.js as its main entry, an ES module build at build/spacekit.esm.js as its module entry, and TypeScript declarations under build/typescript/index.d.ts, with the build script running tsc and then the three esbuild bundles. The declared packageManager is pnpm@7.33.5, and the build target for esbuild is es2015.

## The Simulation is the container everything goes into

A Simulation is the main container for a visualisation, made up of a Camera plus whatever you choose to put in it, and it takes the DOM element to render into as its first argument.

```javascript
const sim = new Spacekit.Simulation(document.getElementById('my-container'), {
 // Required
 basePath: '../path/to/asset',
 // Optional
 camera: {
   initialPosition: [0, -10, 5],
   enableDrift: false,
 },
 debug: {
   showAxes: false,
   showGrid: false,
   showStats: false,
 },
});
```

Three of the options are worth understanding before you start. basePath is where the image and data assets live, and the README is explicit that the default is to host them on the project's own site, so a self-hosted setup has to supply its own copy. camera.initialPosition sets where the viewer starts, and enableDrift controls whether the camera drifts on its own. The debug block toggles the axes, grid and statistics overlay, which are the tools you want while positioning a camera and not in a finished page.

The alternative to a skybox is the Stars class, which loads real star data and positions the stars accordingly in the simulation, and the README's judgement is that this is usually more performant but less visually striking. So the choice is a texture that looks good against a data-driven star field that is cheap.

## Orbits come from ephemerides, not from hand-placed coordinates

The orbital machinery is the reason to use this rather than a general 3D library, and it is built on Kepler ephemerides. An Ephem is a class representing Kepler ephemerides, which define the trajectory of astronomical objects as well as artificial satellites in the sky, in other words the position and possibly velocity over time. The example passes the six classical elements plus the epoch, in degrees.

```javascript
const ephem = new Spacekit.Ephem({
  epoch: 2458600.5,
  a: 5.38533,
  e: 0.19893,
  i: 22.11137,
  om: 294.42992,
  w: 314.28890,
  ma: 229.14238,
}, 'deg');

const asteroid = sim.createObject('Asteroid Aci', {
  ephem,
});
```

There are also presets for the well-known bodies.

```javascript
// Create objects using presets. The presets include scientific ephem params and/or position.
const sun = viz.createObject('sun', Spacekit.SpaceObjectPresets.SUN);
viz.createObject('mercury', Spacekit.SpaceObjectPresets.MERCURY);
viz.createObject('venus', Spacekit.SpaceObjectPresets.VENUS);
```

The SpaceObject class covers anything that can be added to the visualisation, sometimes referred to as simply Object, and the subclasses are RotatingObject with a defined spin axis, ShapeObject with a 3D shape file, and SphereObject, which is spherical like the Earth. Creating one at a fixed position is a matter of passing a position array.

```javascript
// Create a stationary object at [3, 1, -5] position.
// Create a stationary object at [3, 1, -5] position.
const obj = viz.createObject('myobj', {
  position: [3, 1, -5],
};
```

## Shape files, spheres and a black hole with a photon ring

Three specialised creation methods cover the cases the generic one does not. createShape takes a shape file, in the example an OBJ file, together with a rotation block that mixes angles, a period, a yorp and a jd0 epoch.

```javascript
const obj = viz.createShape('myobj', {
  position: [3, 1, -5],
  shape: {
    // Example shape file -
    // http://astro.troja.mff.cuni.cz/projects/asteroids3D/web.php?page=db_asteroid_detail&asteroid_id=1046
    shapeUrl: '../path/to/shape.obj', // Cacus
  },
  rotation: {
    lambdaDeg: 251,
    betaDeg: -63,
    period: 3.755067,
    yorp: 1.9e-8,
    phi0: 0,
    jd0: 2443568.0,
  },
  debug: {
    showAxes: true,
  },
});
```

createSphere is the Earth case, with a texture and a radius that defaults to 1.

```javascript
sim.createSphere('earth', {
  textureUrl: './earth_66mya.jpg',
  radius: 2 /* default to 1 */
  debug: {
    showAxes: true,
  },
});
```

The black hole is the most physically specific piece in the library. It is a stationary Schwarzschild black hole with mass-derived dimensions, traced light paths and an optional accretion disk, where positions are in AU and disk radii are in Schwarzschild radii.

```javascript
const hole = sim.createBlackHole('black-hole', {
  massSolar: 4e6,
  position: [0, 0, 0],
  accretionDisk: { outerRadius: 12, temperature: 10000 },
});
```

The README is careful about the limits of the model. It traces light around a non-rotating mass, and it does not change other objects' orbits, so a black hole in a scene is a visual object rather than a gravitational influence on the rest of the system. There is a separate guide for black holes with the physical model, the options and the limitations, and an interactive example.

## KeplerParticles for the asteroid belt, and the asset hosting question

KeplerParticles is an optimised class for creating many particles that follow Kepler orbits, and the particles do not have a specific shape or size, they share a 2D texture. The README says this is useful when you want to show many objects at once, such as the asteroid belt, which is the case where a separate Object per body would be the wrong structure.

The other thing to understand before shipping anything is the asset situation. Spacekit relies on some image and data assets that are not included in the JavaScript file, and by default these dependencies are hosted on the spacekit site. If you want to host them yourself, you set the Simulation's basePath parameter to a folder containing these files, and the README links the asset directory and the data directory in the repository. The example shows the shape of that override.

```javascript
const viz = new Spacekit.Simulation({
  basePath: 'https://mysite.com/static/spacekit',
});
```

The reason to care is availability and privacy. A page that silently depends on typpo.github.io for its textures works while that site is up, and it makes an outbound request to a third party on every load. Anyone deploying this in production should host the assets, and the cost is a copy of two directories.

## Where spacekit is the wrong choice

Three cases point elsewhere. The first is a production application that needs a stable contract. The README says plainly that the library is a work in progress and the API might change, and with no GitHub releases there is no tagged artefact to pin against, so an upgrade can break your page.

The second is a device or browser without WebGL 2. The library requires it, and devices without support get an error when a Simulation is created, which on a mobile page is a blank screen rather than a degraded one. There is no fallback rendering path described.

The third is a project that needs accurate physics rather than an accurate picture of it. The orbital model is Kepler, which is right for the solar system and for near-Earth satellites and wrong for anything else, and the black hole model is a Schwarzschild approximation that explicitly does not affect other objects' orbits. If your visualisation is about a system where those assumptions do not hold, the honest alternative is to compute the trajectories yourself and feed the library positions, using the fixed-position creation path, or to use a physics-oriented engine. The difference in approach between the two routes is that spacekit gives you a plausible sky quickly, while the other route gives you a correct one slowly, and the choice depends on whether the scene is a visualisation or a simulation.

## Conclusion

spacekit fits a developer building an interactive 3D space page, a data visualisation for an exoplanet catalogue or an educational solar system, and who is content to work with an API the README says might change. It does not fit a production application that needs a stable contract, and it does not fit a team that cannot serve its own assets. Before you adopt it, read the asset hosting section, because the default configuration points at typpo.github.io for images and data and a self-hosted setup needs basePath set to a folder holding the same files, and check the WebGL 2 requirement, since devices without it get an error when a Simulation is created.

## FAQ

### What is spacekit?

It is a JavaScript library for creating interactive 3D space visualisations, whether of the Earth and moon system, the solar system or beyond. The README describes it as generalising work used on Asterank, Meteor Showers, Ancient Earth and similar sites into a single open source 3D engine for space, and it is MIT licensed and published on npm as spacekit.js.

### How do I install and load spacekit?

With npm install spacekit.js, then require or import it. You can also use a raw build in a script tag pointing at https://typpo.github.io/spacekit/build/spacekit.js. The library requires WebGL 2 and uses Three.js r186, and devices without WebGL 2 support receive an error when creating a Simulation.

### How do objects orbit in spacekit?

Through Ephem objects, which are a class representing Kepler ephemerides defining the trajectory of astronomical objects and artificial satellites over time. You construct one with the classical orbital elements and an epoch, in degrees, and pass it to createObject. Presets such as SpaceObjectPresets.SUN and SpaceObjectPresets.MERCURY are provided for the well-known bodies.

### Where do the spacekit image and data assets come from?

They are not included in the JavaScript file and by default are hosted on the spacekit site. To host them yourself you set the Simulation's basePath parameter to a folder containing those files, using the asset directory and data directory in the repository, for example basePath: 'https://mysite.com/static/spacekit'.

### What does the spacekit black hole model actually do?

It is a stationary Schwarzschild black hole with mass-derived dimensions, traced light paths and an optional accretion disk, with positions in AU and disk radii in Schwarzschild radii. The model traces light around a non-rotating mass, and the README notes it does not change other objects' orbits, with the physical model, options and limitations described in a separate black holes guide.

## Sources

- [Issues](https://github.com/typpo/spacekit/issues)
- [License: MIT](https://github.com/typpo/spacekit/blob/master/LICENSE)
- [Project website](https://typpo.github.io/spacekit/)
- [README](https://github.com/typpo/spacekit/blob/master/README.md)
- [typpo/spacekit on GitHub](https://github.com/typpo/spacekit)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/typpo-spacekit