# Metaballs

Aperveil / Light, shaped for the web.

Soft, merging metaballs with a pointer-driven blob. Tune the field, halo and colors, then export a free WebGPU background for React.

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

## What it does

Metaballs sums a procedural blob field and shapes its threshold into merging forms. A pointer blob joins the field; ball size, threshold, halo and rim define the result.

## Choose it for

Bring a playful but controlled organic accent to a creative-tool launch. Use generous margins around a compact headline so the merging forms remain readable.

## Limits

The current editor does not expose blob count. These are implicit shapes, not simulated liquid particles or draggable independent objects.

## Current look

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

[Open editor](https://www.aperveil.com/shaders/metaballs/edit?look=default)

## 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 Metaballs from "./Metaballs";

export default function Hero() {
  return (
    <Metaballs
      className="hero-shader"
      ballSize={0.135} background="#0a0d17ff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

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

Component props: `background`, `colorA`, `colorB`, `colorC`, `colorD`, `accentColor`, `ballSize`, `threshold`, `halo`, `rim`, `flowSpeed`, `cursorSize`, `opacity`, `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

- Background (`background`, color): Colour behind the blobs.
- Blob 1 (`colorA`, color): Colour of the first blob.
- Blob 2 (`colorB`, color): Colour of the second blob.
- Blob 3 (`colorC`, color): Colour of the third blob.
- Blob 4 (`colorD`, color): Colour of the fourth blob.
- Cursor (`accentColor`, color): Colour of the blob that follows the cursor.
- Blob size (`ballSize`, slider): Size of the blobs.
- Merge threshold (`threshold`, slider): Lower makes the blobs fatter and merge sooner.
- Halo (`halo`, slider): A softer second threshold that keeps the edges from looking like cut vinyl.
- Rim light (`rim`, slider): Bright rim where each blob's surface turns over.
- Flow speed (`flowSpeed`, slider): How fast the blobs move; 0 holds them still.
- Cursor blob (`cursorSize`, slider): Zero removes the cursor from the field entirely.
- Opacity (`opacity`, slider): Opacity of the complete effect, including its background.

## 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

0.444 ms legacy timing (method not recorded; not a pure GPU measurement). 1440x900 @ dpr 1.5; Metal driver on macOS Version 26.6.2 (Build 25G83); measured 2026-09-03. This is a recorded headless sample, not a browser FPS or mobile-performance guarantee.

## Questions

### Can I add and remove individual blobs?

Not in the current shader. You can adjust ball size, field threshold and the pointer blob size, but the number of animated field sources is fixed in the source.

### What should I not use Metaballs for?

The current editor does not expose blob count. These are implicit shapes, not simulated liquid particles or draggable independent objects.

### 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

- [Plasma Field](https://www.aperveil.com/shaders/plasma-field)
- [Petal Glass](https://www.aperveil.com/shaders/petal-glass)
- [Mesh Gradient](https://www.aperveil.com/shaders/mesh-gradient)