Installation

One package, no dependencies. If your project already builds TypeScript or modern JavaScript, there is nothing else to set up.

Install it#

bun add @industrieh/starmap

That is the whole installation. The package pulls nothing else in — you can check the lockfile afterwards and find it alone.

What it needs from you#

Very little, and deliberately so. The library is pure logic: it never touches the DOM, never reaches for window, and never calls Math.random().

• Any JavaScript runtime. Browser, Node, Bun, Deno, a Web Worker, a server, React Native, or inside a game engine. The same code runs everywhere.
• ES modules. The package ships ESM only, with type declarations alongside. There is no CommonJS build.
• TypeScript 5 or later, if you use TypeScript. It is optional — the library is plain JavaScript at runtime — but the types are most of what makes it pleasant, so it would be a shame.

Importing#

Everything comes from the package root. There are no sub-paths to remember, and the exports are named so your bundler can drop what you do not use.

import {
  createGalaxy,          // build a universe from a description
  validateGalaxy,        // check one you read back from disk
  indexGalaxy,           // id → object, for lookups
  findRoute,             // shortest path between two systems
  systemPositions,       // where everything is at time t
  createRng,             // deterministic randomness
  type Galaxy,           // the data contract
  type GalaxyInput,      // what you pass in
} from '@industrieh/starmap'

Types are exported next to the functions, so import type { Galaxy } works the same way. The two you will reach for most are GalaxyInput, which describes what you write, and Galaxy, which describes what you get back.

Without a bundler#

Because it is dependency-free ESM, the library also loads straight from a CDN — handy for a sketch, a CodePen, or a quick check that an idea holds.

<script type="module">
  import { createGalaxy } from 'https://esm.sh/@industrieh/starmap'

  const galaxy = createGalaxy({
    systems: [{ id: 'sol', name: 'Sol', x: 0, y: 0, star: { radius: 18 } }],
  })

  console.log(galaxy.meta.systemCount) // 1
</script>

Next step#

Installed. The Quickstart builds a small universe from nothing, then queries it — about fifteen minutes, and you will have touched every part of the library that matters.