🌌 Skybox API

Space, gradient, solid-colour, and image-based skyboxes with animation control

📋 Overview

The Skybox API lets you set any kind of background for your 3D scene — procedural star fields, gradient skies, flat colours, or full cube-map images. Only one skybox is active at a time; calling a new create*Skybox function automatically replaces the previous one.

💡 Key Features

Space skybox – procedural stars, nebulae, optional galaxy spiral
Gradient skybox – any two-colour horizon gradient (daytime, sunset, underwater…)
Solid-colour skybox – single flat colour (caves, indoor scenes)
Image skybox – six cube-face textures for photorealistic environments; also sets IBL for PBR materials
Animation control – auto-animate, speed multiplier, pause, or reverse

🌟 Skybox Creation

createSpaceSkybox(options?)

Creates a procedural space background with stars and optional nebulae.

options.starCount number – Number of stars (default: 5000)

options.starSize number – Star point size (default: 1)

options.nebulae boolean – Include nebula clouds (default: true)

options.nebulaColor hex – Nebula colour tint (default: 0x8800ff)

Example

// Space combat scene
createSpaceSkybox({ starCount: 10000, nebulaColor: 0x4400ff });

createGradientSkybox(topColor, bottomColor)

Creates a smooth two-colour gradient sky — ideal for outdoor scenes.

topColor hex – Colour at the top of the sky

bottomColor hex – Colour at the horizon

Example

createGradientSkybox(0x1a6aa8, 0xf4a460); // warm sunset
createGradientSkybox(0x87ceeb, 0x228b22); // daytime with green ground tint

createSolidSkybox(color)

Sets the background to a single flat colour — useful for caves, indoor rooms, or stylised scenes.

color hex – Background colour

Example

createSolidSkybox(0x000000); // pitch-black cave
createSolidSkybox(0x1a1a2e); // deep navy interior

createImageSkybox([px, nx, py, ny, pz, nz])

Loads six cube-face images as the skybox. Also sets them as the scene's environment map, enabling image-based lighting (IBL) for PBR materials — reflections and light come from the sky.

urls string[6] – Paths to the +X, -X, +Y, -Y, +Z, -Z cube faces (in that order)

Returns: Promise<void> – resolves once all textures are loaded

⚠️ Use await in your init()

Loading is async — await the call so objects are fully lit before the first frame.

Example

export async function init() {
  await createImageSkybox([
    '/assets/sky/studio/px.png',
    '/assets/sky/studio/nx.png',
    '/assets/sky/studio/py.png',
    '/assets/sky/studio/ny.png',
    '/assets/sky/studio/pz.png',
    '/assets/sky/studio/nz.png',
  ]);
  // PBR spheres now receive correct reflections
  createSphere(1, 0xffffff, [0, 1, 0], { material: 'metallic', roughness: 0.1 });
}

clearSkybox()

Removes the active skybox, leaving a transparent/black background.

Example

clearSkybox();

🎬 Animation & Speed

animateSkybox(dt)

Advances the skybox rotation by dt seconds. Call this manually inside your update(dt) loop, or use enableSkyboxAutoAnimate() to let the engine do it automatically.

dt number – Delta time in seconds

Example

export function update(dt) {
  animateSkybox(dt); // manual control
}

enableSkyboxAutoAnimate(speed?)

Tells the engine to automatically call animateSkybox(dt) every frame, so you don't need to do it manually in update().

speed number – Speed multiplier (default: 1.0). Use 0 to pause, negative to reverse.

Example

enableSkyboxAutoAnimate();       // default speed
enableSkyboxAutoAnimate(0.25);  // slow drift
enableSkyboxAutoAnimate(-1);    // reverse

disableSkyboxAutoAnimate()

Stops the engine from automatically rotating the skybox each frame.

Example

disableSkyboxAutoAnimate();

setSkyboxSpeed(multiplier)

Changes the rotation speed of the active skybox animation without disabling/re-enabling it.

multiplier number – Speed multiplier: 0 = frozen, 1 = normal, 2 = double, -1 = reverse

Example

setSkyboxSpeed(0);   // freeze during a cutscene
setSkyboxSpeed(2);   // warp-speed effect
setSkyboxSpeed(1);   // restore normal speed

📚 Quick Reference

Function	Use case
`createSpaceSkybox(opts?)`	Space games, sci-fi
`createGradientSkybox(top, bottom)`	Outdoor, sunset, underwater
`createSolidSkybox(color)`	Caves, indoor, stylised
`createImageSkybox([6 urls])`	Photorealistic + IBL for PBR
`clearSkybox()`	Remove background
`animateSkybox(dt)`	Manual frame-by-frame rotation
`enableSkyboxAutoAnimate(speed?)`	Set-and-forget rotation
`disableSkyboxAutoAnimate()`	Stop auto rotation
`setSkyboxSpeed(mult)`	Adjust speed at runtime