skybox-studio-runtime

skybox-studio-runtime renders Skybox Studio manifests in Three.js. It supports live shader rendering and baked equirectangular textures from the same manifest evaluator.

Install

npm install skybox-studio-runtime three

three is a peer dependency. The package is ESM-only.

Basic Usage

import * as THREE from "three";
import { Skybox, type SkyboxManifestV2 } from "skybox-studio-runtime";

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.1, 100);

const manifest: SkyboxManifestV2 = {
  version: 2,
  composition: { mode: "alpha-over", order: "bottom-to-top" },
  geometry: { type: "sphere" },
  nodes: [
    {
      id: "base",
      name: "Base",
      type: "gradient",
      enabled: true,
      opacity: 100,
      blendMode: "normal",
      params: {
        mode: "linear",
        rotation: 0,
        stops: [
          { color: "#14213d", location: 0, opacity: 100 },
          { color: "#fca311", location: 100, opacity: 100 },
        ],
      },
    },
  ],
};

const skybox = new Skybox()
  .setRenderer(renderer)
  .setRenderMode("dynamic")
  .setGeometry({ type: "sphere" })
  .fromManifest(manifest)
  .load();

scene.add(skybox);

const start = performance.now();

renderer.setAnimationLoop(() => {
  skybox.setViewport({
    devicePixelRatio: renderer.getPixelRatio(),
    renderHeight: renderer.domElement.clientHeight,
    verticalFovRadians: THREE.MathUtils.degToRad(camera.fov),
  });

  // Ask the runtime whether anything actually animates instead of guessing.
  if (skybox.isAnimated()) {
    skybox.update((performance.now() - start) / 1000);
  }

  renderer.render(scene, camera);
});

Render Modes

Two modes, set with setRenderMode():

dynamic

The live layer composition. Animated layers (Dynamic Clouds, Sun) are driven by skybox.update(seconds), which you call once per frame. skybox.isAnimated() tells you whether an animation loop is needed at all — ask it rather than inspecting the manifest yourself.

static

The whole composition is GPU-baked once into an equirect texture and the dome swaps to a one-fetch sampler material. After that nothing touches the skybox per frame: update() is a no-op, starfield glint passes are freed, and no uniforms are pushed. Use it whenever the sky does not need to change — it removes the sky's per-frame cost almost entirely.

skybox.setRenderMode("static").setStaticQuality("high");
skybox.addEventListener("staticbakechange", () => {
  console.log(skybox.getStaticBakeInfo()); // size, bytes, texels/degree, why
});

Quality is a memory budget, not a resolution. low / medium / high map to 32 / 128 / 512 MiB. high does not mean "the biggest texture the GPU allows" — the solver computes the sharpest texture the current viewport can actually resolve (one texel per device pixel), then clamps that against the tier budget and maxTextureDimension2D. On a small canvas high allocates a small texture. Because the browser can change size or DPR at any moment, the layout is re-solved on setViewport() and re-baked only when the result changes materially.

getStaticBakeInfo() reports which constraint bound the result: screen-fit, budget-scaled, hardware-clamped, or budget-minimum.

Coverage restricts the bake to a band of sky, so texels are not spent where the camera never looks (typically everything below the horizon). Set it per instance with setStaticCoverage(...), or author it into the manifest as staticBake.coverage; SKYBOX_COVERAGE_PRESETS provides the usual bands. Outside a clipped band the sky falls back to a tiny full-sphere bake, cross-faded at the edge, so looking past the band still shows real sky.

Legacy mode strings still resolve: auto / live-webgpu / live-webgl → dynamic, baked-texture → static.

Geometry

Use geometry: { type: "box" } or geometry: { type: "sphere" } in Manifest V2, or override it fluently with setGeometry(...). Both primitives sample effects by world-space direction, so Gradient and Field Gradient layers render consistently across box and spherical sky geometry.

Baking

import { bakeSkyboxImageData, createBakedSkyboxTexture } from "skybox-studio-runtime";

const image = bakeSkyboxImageData(manifest, { width: 1024, cache: true });
const texture = createBakedSkyboxTexture(manifest, { width: 1024 });

The bake path uses the same color conversion, layer ordering, opacity, blend modes, and group composition as the live renderers.

GPU equirect bake (WebGPU)

When you have a WebGPURenderer, you can bake the live composition shader straight into an equirectangular render target (including HDR float targets) instead of evaluating on the CPU:

import { createSkyboxGpuBakeService } from "skybox-studio-runtime";

const bake = createSkyboxGpuBakeService(renderer);
const moonTextures = await bake.prepareMoonTextures(manifest, 1024);
const target = bake.bakeRenderTarget(manifest, {
  width: 2048,
  height: 1024,
  hdr: true,
  moonTextures,
});
// `bakeImageData` prepares Moon textures automatically.
const image = await bake.bakeImageData(manifest, { width: 2048, height: 1024 });

Moon Generation

Moon layers are procedural WebGPU resources included in the core runtime. The live Skybox generates and caches one texture per Moon layer; placement updates move the angular decal without regenerating its terrain. Call setViewport(...) when the viewport height or camera FOV changes so automatic Moon resolution can track its projected size.

Moon layers require a WebGPU renderer with compute support. The CPU baked-texture fallback (bakeSkyboxImageData) reports them as unsupported instead of silently omitting the layer; the static render mode bakes them correctly, because it goes through the GPU bake service rather than the CPU evaluator.

Starfield Generation

Procedural starfield generation (the star/nebula catalog, its GPU bake service, and the CPU sampler) lives behind a separate entry point, skybox-studio-runtime/starfield, so consumers that never use starfields don't pull that code into their core bundle. Import it once anywhere in your app to enable starfield layers:

// Side-effect import — registers the starfield GPU bake service + CPU sampler.
import "skybox-studio-runtime/starfield";

// …or import the helpers/params you need (also enables generation):
import {
  DEFAULT_STARFIELD_PARAMS,
  normalizeStarfieldParams,
} from "skybox-studio-runtime/starfield";

Without this import, starfield layers are a graceful no-op (they simply don't render/bake). With it imported, the live Skybox and the bakers generate starfield textures automatically from each layer's params.

Loading Bundles

Skybox Studio exports project bundles (a manifest.json plus hashed image assets). The loader rehydrates a bundle from a directory, URL, or zip and returns a ready manifest with its image textures:

import { loadSkyboxBundle, Skybox } from "skybox-studio-runtime";

const { manifest, imageTextures } = await loadSkyboxBundle(source);

const skybox = new Skybox()
  .setRenderer(renderer)
  .setImageTextures(imageTextures)
  .fromManifest(manifest)
  .load();

loadBundleFromUrl, loadBundleFromZip, and loadBundleFromDirectory cover the individual sources, and loadSkyboxImageTextures loads just the image layers for a manifest you already have.

Extending Layers

The runtime is registry-driven — there are no hardcoded layer.type branches. Register a custom layer adapter (its CPU sampleCpu plus optional WGSL/GLSL halves) with registerLayerRuntimeAdapter, and it composes end-to-end through both the live renderers and the bakers with no edits to the core.

Groups

Manifest V2 supports nested groups. A group is evaluated as an isolated subtree, then composited into its parent using the group's blendMode and opacity.

Use targetGroupId in bake options to bake a group subtree:

const groupImage = bakeSkyboxImageData(manifest, {
  targetGroupId: "atmosphere",
  width: 1024,
});

Color Management

Colors are authored as sRGB hex strings, evaluated in linear RGB, and encoded back to sRGB for baked textures. CMYK/ICC print profiles are not supported.