# Starfield

Aperveil / Light, shaped for the web.

A WebGPU galaxy background with a moving nebula volume, fine stars and depth-dependent parallax. Tune its palette, travel depth and speed, then export for React.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

Deep Sky moves through a colored three-dimensional density field sampled along perspective rays. Fine stars approach at different depths, while near and far nebula features shift at different rates. Travel depth blends this spatial view with the quieter flat galaxy field; Star Flight retains the clear outward-travelling stars.

## Choose it for

Give an exploration or developer-tool page a quiet sense of depth. Keep star size small and place a concise heading against the darkest area.

## Limits

Star positions are procedural, not astronomical data. It is a decorative field rather than a planetarium or a particle system with individually addressable stars.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/starfield/edit?look=default&scene=landing)

## Landing scene

This preview uses `flowSpeed`: 0.2, `steer`: 0.06, `twinkle`: 0.08. The editor link carries these settings with your Look. Direct editor visits use the product defaults; Reset all restores those defaults.

## Install

Download the Export Kit from the editor. No shader-specific npm package or CLI is published yet.

```sh
npm install ./vendor/aperveil-runtime-0.1.0.tgz ./vendor/aperveil-react-0.1.0.tgz
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import Starfield from "./Starfield";

export default function Hero() {
  return (
    <Starfield
      className="hero-shader"
      layers={12} background="#05070fff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `variant`, `background`, `starColor`, `tintColor`, `layers`, `density`, `starChance`, `starSize`, `glow`, `twinkle`, `flowSpeed`, `streak`, `steer`, `opacity`, `backgroundOpacity`, `nebulaAmount`, `dust`, `nebulaColorA`, `nebulaColorB`, `travelDepth`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Variant (`variant`, select): Deep Sky drifts through stars and a nebula; Star Flight flies forward through layered stars.
- Background (`background`, color): Colour of empty space.
- Stars (`starColor`, color): Colour of most stars.
- Warm stars (`tintColor`, color): Colour of the warmer stars mixed among them.
- Depth layers (`layers`, slider): Number of depth layers of stars; more layers give a deeper field.
- Density (`density`, slider): Stars per layer. Higher fills the sky; the cost is one cell lookup either way.
- Star chance (`starChance`, slider): Fraction of cells holding a star. Sky is mostly empty, and skipping the rest is what keeps twenty layers affordable.
- Star size (`starSize`, slider): Core radius in CSS pixels, independent of screen size and DPR.
- Glow (`glow`, slider): Halo around the stars, and how many rare bright stars appear.
- Twinkle (`twinkle`, slider): How much the stars flicker.
- Drift / travel speed (`flowSpeed`, slider): Speed of the drift or of the flight.
- Streak (`streak`, slider): Stretches each star along its direction of travel.
- Cursor steer (`steer`, slider): How much the cursor steers the view.
- Opacity (`opacity`, slider): Opacity of the complete effect, including its background.
- Background opacity (`backgroundOpacity`, slider): Fade the background independently for transparent overlays.
- Nebula intensity (`nebulaAmount`, slider): Colored gas in Deep Sky; Star Flight retains the original clear starfield.
- Dust lanes (`dust`, slider): Dark absorption lanes through the Deep Sky band.
- Nebula cool (`nebulaColorA`, color): Cool colour of the nebula in Deep Sky.
- Nebula warm (`nebulaColorB`, color): Warm colour of the nebula in Deep Sky.
- Travel depth (`travelDepth`, slider): In Deep Sky, blends from a flat drifting galaxy (0) to flying through a 3D nebula (1).

## Compatibility

WebGPU rendering requires a supported browser and secure context. The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout. Text exports also retain readable HTML typography.

## Performance

No published timing sample. Profile this effect on your target devices.

## Questions

### Can I keep the stars without the nebula?

Set Nebula intensity to zero in Deep Sky, or choose Star Flight for the original clear, travelling starfield. Dust lanes and both nebula colors are independent controls.

### How do I get more stars without making them bigger?

Adjust Density and Star chance while leaving Star size low. Depth layers changes depth structure; Glow and Twinkle change how the existing stars read.

### Can the stars appear over my own page background?

The editor separates Background opacity from the overall Opacity control. Lower Background opacity to reveal the layer beneath the stars. Keep readable text and navigation in HTML rather than drawing them into the starfield.

### What should I not use Starfield for?

Star positions are procedural, not astronomical data. It is a decorative field rather than a planetarium or a particle system with individually addressable stars.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## Related shaders

- [Grid Horizon](https://www.aperveil.com/shaders/grid-horizon)
- [God Rays](https://www.aperveil.com/shaders/god-rays)
- [Ether Flow](https://www.aperveil.com/shaders/ether-veil)