worldorbit

v3.0.5

Published

2 days ago

A text-based DSL and parser pipeline for orbital worldbuilding

Downloads

655

0High
0Medium
0Low

negurvulkan

worldbuilding orbit dsl parser

WorldOrbit

WorldOrbit is a text-first DSL, viewer, and optional editor platform for fictional orbital systems.

It is designed as a specialized Mermaid-like alternative for worldbuilding: you can describe stellar systems in plain text, embed them in Markdown, render them as static diagrams, or explore them interactively with pan, rotate, zoom, and object tooltips.

WorldOrbit is built for:

worldbuilding projects
Markdown-based lore repositories and CMS setups
fictional atlases and codices
interactive setting documentation
browser-based orbital diagram tooling

Why WorldOrbit?

Generic diagram tools can show relationships, but they are not built for fictional orbital systems.

WorldOrbit is designed specifically for:

stars, planets, moons, belts, structures, and phenomena
orbit-aware layouts instead of generic node graphs
Markdown-native embedding
optional interactivity
optional visual authoring through Studio

WorldOrbit is not intended to be a real-world astronomy simulator or a high-precision astrophysics engine. Its goal is clear, expressive orbital worldbuilding that works well in content workflows.

Quick Example

schema 2.5

system Iyath
  title "Iyath System"
  epoch "JY-0001.0"
  referencePlane ecliptic

defaults
  view orthographic
  scale presentation
  preset atlas-card
  theme atlas

group inner-system
  label "Inner System"
  color #d9b37a

viewpoint eclipse
  label "Eclipse View"
  projection perspective
  camera
    azimuth 36
    elevation 22
    distance 6
  layers background guides orbits-back events objects labels metadata
  events naar-eclipse

object star Iyath

object planet Naar
  orbit Iyath
  semiMajor 1.18au
  eccentricity 0.08
  angle 28deg
  inclination 24deg
  phase 42deg
  atmosphere nitrogen-oxygen
  groups inner-system

object moon Seyra
  orbit Naar
  distance 384400km

event naar-eclipse
  kind solar-eclipse
  target Naar
  participants Iyath Naar Seyra

Installation

npm

npm install worldorbit

What the `worldorbit` package contains

The published worldorbit package is the public entry point.

It includes:

the browser bundles
subpath exports for core modules
the packages used by the viewer, Markdown integration, and editor tooling

So for most users, this is enough:

npm install worldorbit

And then:

import { parse, loadWorldOrbitSource } from "worldorbit";
import * as Viewer from "worldorbit/viewer";

Browser / CDN Quick Setup

For direct browser usage, use the browser bundle:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      html, body {
        margin: 0;
        width: 100%;
        height: 100%;
      }

      #view {
        width: 100vw;
        height: 100vh;
      }
    </style>
  </head>
  <body>
    <div id="view"></div>

    <script type="module">
      import {
        createInteractiveViewer,
        loadWorldOrbitSource
      } from "https://unpkg.com/[email protected]/dist/unpkg/worldorbit.esm.js";

      const source = `
schema 2.5

system Iyath
  epoch "JY-0001.0"

object star Iyath
object planet Naar
  orbit Iyath
  semiMajor 1.18au
`.trim();

      const loaded = loadWorldOrbitSource(source);

      createInteractiveViewer(document.getElementById("view"), {
        document: loaded.document
      });
    </script>
  </body>
</html>

For browser usage today, prefer the ESM entry point worldorbit.esm.js.

Static and Interactive Rendering

WorldOrbit can be used in different ways from the same source:

as a static diagram
as an interactive SVG viewer
inside Markdown pipelines
inside the optional Studio editor

This means the same WorldOrbit document can be:

written in plain text
embedded in Markdown
rendered in a documentation page
explored interactively
edited visually if needed

Studio Editor

WorldOrbit includes an optional Studio editor for easier authoring and exploration.

Studio is useful when you want:

visual placement editing
source and preview side by side
inspector-based editing
faster onboarding for non-technical users

The editor is optional. The core format remains text-first.

Canonical Schema

New atlas authoring should start with:

schema 2.5

Example:

schema 2.5

system Iyath
  title "Iyath System"
  epoch "JY-0001.0"
  referencePlane ecliptic

defaults
  view orthographic
  scale presentation
  preset atlas-card
  theme atlas

group inner-system
  label "Inner System"
  summary "Naar and its inhabited infrastructure"
  color #d9b37a

viewpoint overview
  label "Atlas Overview"
  summary "Fit the whole system."
  projection orthographic
  camera
    azimuth 24
    elevation 18
  layers background guides orbits-back events objects labels metadata
  events naar-eclipse
  filter
    groups inner-system

annotation naar-notes
  label "Naar Notes"
  target Naar
  body "Heimatwelt der Enari."

object star Iyath
  mass 1.02sol

object planet Naar
  orbit Iyath
  semiMajor 1.18au
  eccentricity 0.08
  angle 28deg
  inclination 24deg
  phase 42deg
  groups inner-system
  image /demo/assets/naar-map.png
  atmosphere nitrogen-oxygen

object moon Seyra
  orbit Naar
  distance 384400km
  groups inner-system

event naar-eclipse
  kind solar-eclipse
  label "Naar Eclipse"
  target Naar
  participants Iyath Naar Seyra
  epoch "JY-0001.0"
  referencePlane ecliptic

  positions
    pose Naar
      orbit Iyath
      semiMajor 1.18au
      phase 90deg

    pose Seyra
      orbit Naar
      distance 384400km
      phase 90deg

What's New In Schema 2.5

Schema 2.5 keeps Schema 2.1 fully readable and adds a clearer 3D-ready authoring surface without turning WorldOrbit into a full 3D engine.

It adds:

new viewpoint projections: orthographic and perspective
a Schema-level camera block with azimuth, elevation, optional roll, and optional distance
clearer inheritance for epoch and referencePlane across system, object, event, and pose contexts
more stable event snapshots, where missing pose fields fall back to object, event, and system context instead of implying empty values
stronger validation around viewpoints, camera fields, event/pose consistency, and ambiguous authoring combinations

Schema 2.5 still does not add full 3D coordinates, meshes, materials, quaternions, lighting, or simulation-heavy orbital solving.

Schema 2.1 already added comments, semantic group and relation sections, declarative event sections with per-event positions/pose snapshots, viewpoint-linked events, object-level epoch and referencePlane, declarative resonance and validation hints, and optional structured lore blocks such as climate, habitability, and settlement.

Stable 1.0 source is still accepted. Canonical schema 2.0 source remains fully supported, and legacy schema 2.0-draft files stay readable as a compatibility path with a deprecation diagnostic.

Basic Usage

Parse and load source

import {
  loadWorldOrbitSource,
  parse,
} from "worldorbit";

const parsed = parse(`
system Iyath
star Iyath
planet Naar orbit Iyath distance 1.18au
`.trim());

const loaded = loadWorldOrbitSource(`
schema 2.5

system Iyath
object star Iyath
object planet Naar
  orbit Iyath
  semiMajor 1.18au
`.trim());

Render a scene

import {
  loadWorldOrbitSource,
  renderDocumentToScene,
} from "worldorbit";

const loaded = loadWorldOrbitSource(source);

const scene = renderDocumentToScene(loaded.document, {
  projection: "isometric",
  scaleModel: {
    orbitDistanceMultiplier: 1.1,
    bodyRadiusMultiplier: 1.15,
  },
});

Create an interactive viewer

import { loadWorldOrbitSource } from "worldorbit";
import { createInteractiveViewer } from "worldorbit/viewer";

const loaded = loadWorldOrbitSource(source);

createInteractiveViewer(document.getElementById("preview"), {
  document: loaded.document,
  projection: "isometric",
  theme: "atlas",
  viewMode: "3d",
});

Package Overview

WorldOrbit is organized internally as a small ecosystem.

`worldorbit`

Public package entry point with browser bundles and main exports.

`worldorbit/core`

Use this when you need:

parsing
normalization
validation
diagnostics
schema loading
canonical formatting
scene generation

`worldorbit/viewer`

Use this when you need:

static SVG rendering
interactive viewing
atlas-style exploration
themes and embeds

`worldorbit/markdown`

Use this when you want to transform fenced worldorbit blocks inside Markdown pipelines.

`worldorbit/editor`

Use this when you want browser-based visual authoring on top of the text format.

Core Example

import {
  formatDocument,
  loadWorldOrbitSource,
  parse,
  parseWorldOrbitAtlas,
  renderDocumentToScene,
  upgradeDocumentToV2,
} from "worldorbit/core";

const stable = parse(`
system Iyath
star Iyath
planet Naar orbit Iyath distance 1.18au
`.trim());

const atlasDocument = upgradeDocumentToV2(stable.document, {
  preset: "atlas-card",
});

const atlasSource = formatDocument(atlasDocument, { schema: "2.5" });
const loaded = loadWorldOrbitSource(atlasSource);
const parsedAtlas = parseWorldOrbitAtlas(atlasSource);
const scene = renderDocumentToScene(loaded.document, {
  projection: "isometric",
  scaleModel: {
    orbitDistanceMultiplier: 1.1,
    bodyRadiusMultiplier: 1.15,
  },
});

Viewer Capabilities

Viewer features in v3.0.5 include:

scene-based SVG rendering
renderer-neutral spatial scenes through renderDocumentToSpatialScene(...)
a full 3D viewer mode on the same documents and placements as 2D
deterministic orbit animation with play, pause, reset, and speed controls
projections: topdown, isometric, orthographic, and perspective
theme presets: atlas, nightglass, ember
layer controls for background, guides, orbits, events, objects, labels, metadata, and relations
selection, hover, focus, fit, pan, zoom, and rotate
tooltip cards and object detail payloads
viewpoints, filters, search, and bookmark capture
deep-linkable atlas state
embeddable viewer custom elements
semantic group filters, relation and event overlays, active event scenes, Schema 2.5 camera metadata, and event/object reference-context detail metadata

Markdown Integration

Use worldorbit/markdown to transform fenced worldorbit blocks into static output, interactive 2D output, or interactive 3D output.

import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";

import { remarkWorldOrbit } from "worldorbit/markdown";

const html = String(
  await unified()
    .use(remarkParse)
    .use(remarkWorldOrbit, { mode: "interactive-3d" })
    .use(remarkRehype, { allowDangerousHtml: true })
    .use(rehypeStringify, { allowDangerousHtml: true })
    .process(markdownSource),
);

In the browser:

import { mountWorldOrbitEmbeds } from "worldorbit/viewer";

mountWorldOrbitEmbeds(document, {
  mode: "interactive-3d",
});

Examples

Examples live in:

Browser-facing examples and demos live in the repository under demo/, studio/, and examples/.

Documentation

Development

npm install
npm run build
npm test

The workspace builds outputs into package-specific distribution folders and browser bundles.

Useful notes:

npm run build compiles all packages and refreshes local package shims
npm test rebuilds first, then runs the regression suite
the repository remains parser-first: rendering and atlas interaction stay downstream of parse, normalize, and validate

Project Direction

WorldOrbit is intended as a specialized Mermaid-like solution for fictional orbital systems.

The long-term focus is:

strong text-first authoring
clean Markdown embedding
rich static and interactive rendering
optional visual editing
stable schema evolution over time

License

MIT