WebGL/Canvas 2D procedural celestial body renderer. Generates planets, stars, black holes, galaxies, and nebulae in real-time with deterministic seeded output.

Built for Abyssal Rift — a 2D space exploration MMORPG.

Live Demo

Features

• 12 celestial types: Terrain (wet/dry), Aquatic, Barren, Gas Giant (plain/ringed), Molten, Ice, Star, Black Hole, Galaxy, Nebula
• Deterministic: Same seed always produces the same result
• Real-time animation: All types except Nebula animate via WebGL shaders
• Customizable palettes: Override any color slot per type
• Composable shader architecture: Shared features (base planet, clouds, craters, atmosphere, etc.) compose into type-specific shaders
• Configurable visuals: Tune FBM octaves, cloud cover, noise scale, and more per instance
• Precompilation API: Compile shaders during loading screen to avoid runtime stutter
• Built-in fallback noise: Procedurally generated — no external assets required
• Zero dependencies

Install

npm install @eluvade/cosmos

Quick Start

import { CelestialGenerator, CelestialType } from '@eluvade/cosmos';

const gen = new CelestialGenerator();

// Optional: load high-quality noise texture for black hole detail
await gen.loadNoiseTexture('radial-noise.png');

// Optional: precompile shaders during loading screen
await gen.precompile();

// Render a star
const canvas = gen.render({
  type: CelestialType.Star,
  seed: 9000,
  resolution: 256,
}, 0);

document.body.appendChild(canvas);

// Animate
function loop(time) {
  gen.render({ type: CelestialType.Star, seed: 42 }, time / 1000);
  requestAnimationFrame(loop);
}
requestAnimationFrame(loop);

Render a Nebula

Nebulae use Canvas 2D (static, rendered once):

import { renderNebula } from '@eluvade/cosmos';

const canvas = renderNebula(9000, 512);
document.body.appendChild(canvas);

API

CelestialGenerator

const gen = new CelestialGenerator(canvas?: HTMLCanvasElement);

| Method | Description | |--------|-------------| | render(params, time) | Render a celestial body. Returns HTMLCanvasElement. | | renderToImageData(params, time) | Render and return pixel data as ImageData. | | precompile(types?) | Precompile shaders. Async, yields between compilations. | | loadNoiseTexture(src) | Load external noise texture for black hole detail. | | setNoiseTexture(source) | Set noise from an already-loaded TexImageSource. | | getCanvas() | Get the underlying canvas element. | | getLoopDuration(type, speed?) | Get seamless loop duration in seconds. | | dispose() | Release all WebGL resources. |

Static methods:

| Method | Description | |--------|-------------| | CelestialGenerator.getCelestialTypes() | All CelestialType enum values. | | CelestialGenerator.getColorSlots(type) | Named color slot list for a type. | | CelestialGenerator.getDefaultPalette(type) | Default RGBA palette for a type. |

CelestialParams

interface CelestialParams {
  type: CelestialType;
  seed: number;
  resolution?: number;        // Default: 512
  rotationAngle?: number;     // Radians, default: 0
  timeSpeed?: number;         // Default: 0.1
  lightPos?: [number, number]; // UV [0-1], default: [0.39, 0.7]
  colors?: Record<string, RGBA>; // Override palette colors
  config?: Partial<CelestialConfig>; // Visual tuning overrides
}

CelestialConfig

Tunable visual parameters (all optional, sensible defaults per type):

| Parameter | Default | Description | |-----------|---------|-------------| | fbmOctaves | 6 | FBM octave count for base layers | | noiseScale | 10 | Base noise scale | | cloudCover | 0.546 | Cloud cover threshold (0-1) | | cloudScale | 4 | Cloud noise scale | | landCutoff | 0.5 | Land visibility threshold | | craterScale | 5 | Crater noise scale | | flowCutoff | 0.6 | Lava/ice flow threshold | | flowOctaves | 5 | Flow layer FBM octaves | | flowScale | 10 | Flow layer noise scale |

CelestialType

enum CelestialType {
  TerrainWet, TerrainDry, Aquatic, Barren,
  GasGiant, GasGiantRinged, Molten, Ice,
  Star, BlackHole, Galaxy, Nebula
}

renderNebula(seed, size?, colors?)

Standalone Canvas 2D nebula renderer. Returns HTMLCanvasElement.

function renderNebula(
  seed: number,
  size?: number,          // Default: 512
  colors?: NebulaColors,  // Optional color overrides
): HTMLCanvasElement;

Custom Palettes

Override any color slot by name:

gen.render({
  type: CelestialType.Star,
  seed: 9000,
  colors: {
    star1: [0.2, 0.5, 1.0, 1],  // RGBA [0-1]
    star2: [0.1, 0.3, 0.8, 1],
    glow:  [0.3, 0.4, 1.0, 1],
  },
}, 0);

Use CelestialGenerator.getColorSlots(type) to see available slot names.

Architecture

src/
  index.ts              Public API
  types.ts              Type definitions
  seed.ts               Integer hash seed derivation
  palettes.ts           Default color palettes
  webgl.ts              WebGL utilities
  noise.ts              Procedural fallback noise

  glsl/
    header.glsl.ts      Vertex shader + fragment header
    common.glsl.ts      Shared GLSL functions (branchless)
    composer.ts          Feature composition engine
    features/            6 composable GLSL features
    standalone/          5 standalone type shaders

  profiles/             12 render profiles (feature configs)
  renderers/
    shader-renderer.ts  Generic GLSL renderer
    black-hole.ts       Multi-pass black hole pipeline
    nebula.ts           Canvas 2D nebula renderer

Browser Support

Requires WebGL 1.0. Works in all modern browsers.

Credits

This project builds on the work of several talented creators:

• Deep-Fold — Planet shaders ported from PixelPlanets (Godot → WebGL)
• Cas van den Elzen (@cas-van-den-elzen) — Black hole renderer based on this CodePen
• Sophia / Fractal Kitty (@fractalkitty) — Nebula renderer based on this CodePen

License

MIT