Particles Designer

ABSOLUMONT / Particles Designer — author luminous GPU particle fields in the browser: 1k–200k procedural WebGL2 points forming built-in, baked or AI-invented shapes, with light, ribbons, attractors, motion, shockwaves, a collapse → explode → reform cycle and audio reactivity. Every factory look is ready to perform: audio, ripples and the cycle are all available. Browse eight banks of looks (P1–P8) and shapes (S1–S8), save your own, describe a field in words (optionally with an inspiration photo), and play it all from a ROTO-CONTROL. Then drop any look into a web page with the embed kit.

Originally built inside LUMEN; this repository is the standalone tool.

Live: Designer · embed examples · Mac app (the .dmg on each release; see docs/ELECTRON.md for the first launch). The hosted Designer runs fully in the browser: saved slots stay in that browser, and AI generation needs the local host (below) or the Mac app.

Quick start

npm install
npm run dev          # http://localhost:5180/

Chrome or Edge is recommended (Web MIDI for ROTO-CONTROL; WebGL2 required).

AI design generation (optional)

The prompt bar calls the local dev host at /api/generate, which talks to OpenAI server-side. Copy .env.example to .env.local, fill in OPENAI_API_KEY, and restart npm run dev. The key is never sent to the browser, and generation only accepts loopback requests.

Saved slots

Saved presets and shapes are written by the dev host to one JSON library (~/Library/Application Support/Particles Designer/slots.json on macOS; override with PARTICLES_DESIGNER_DATA_DIR), so every device that opens the dev server shares them. Browser storage is the fallback when no host is available. npm run bake turns saved work into factory code (see docs).

Slot badges tell them apart: a hollow ring is built-in, a filled dot is saved. Hover a saved slot for × (or press Delete) to remove it; a built-in it covered comes back. On touch screens the × is always shown, and a long-press on any slot offers Replace (the Shift+click equivalent) and Delete. Export library / Import… (above Presets) back up and move saved work between browsers, or into your local copy; Import also accepts a single look downloaded from Embed.

ROTO-CONTROL

Three setups (MIDI channels 9–11) play every page of the Designer: download them (also linked from the Designer), find them in roto/, or on the CDN. See the map and guide.

Embed a look in any web page

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@absolumont/[email protected]/dist-embed/particles-designer.js"
></script>
<particle-field look="deep-sea" style="width: 100%; height: 480px"></particle-field>

// npm install @absolumont/particles-designer
import { ParticleField } from "@absolumont/particles-designer";
const field = new ParticleField("#hero", {
  look: "galaxy-drift",
  audio: "microphone",
  audioDepth: 1,
});

In the Designer, Embed copies a ready-to-paste snippet of the current look or downloads it as JSON. The kit is about 37 KB gzipped with no dependencies, and it adapts its quality to each visitor's device so it stays smooth on phones. It is on npm as @absolumont/particles-designer and on jsDelivr. See docs/EMBED.md and the live examples.

Scripts

| Command | What it does | | -------------------------- | --------------------------------------------------------------------- | | npm run dev | Vite dev server with the Designer host APIs (LAN-exposed) | | npm run build | Typecheck + static build in dist/ | | npm run preview | Serve the build with the host APIs | | npm test | Unit tests (Vitest) | | npm run build:embed | Build the embed kit into dist-embed/ (ESM, IIFE, types) | | npm run build:site | App + kit + examples as one static site in dist/ (GitHub Pages) | | npm run examples | Build the kit and open the embed examples | | npm run verify | Format check, typecheck, tests, app and embed builds | | npm run bake | Bake the saved slot library into factory shapes/looks | | npm run roto:presets | Regenerate the ROTO-CONTROL setup files in roto/ | | npm run rehearse:roto | Browser rehearsal with simulated Web MIDI (needs npm run dev) | | npm run rehearse:embed | Browser rehearsal of every embed example (needs npm run dev) | | npm run rehearse:boot | Reload check: no unstyled flash, splash removed (needs npm run dev) | | npm run rehearse:quality | Adaptive quality on a deliberately slow device (needs npm run dev) | | npm run electron:dev | Build the site and the Electron shell, then launch the desktop app | | npm run dist:mac | Package the Mac app (universal, ad-hoc signed) into release/ | | npm run icon | Regenerate the app icon (electron/icon.png, icon.icns) |

Releasing

npm version patch && git push --follow-tags

The version tag runs .github/workflows/publish.yml: checks, npm publish via trusted publishing (with provenance; jsDelivr follows), then a GitHub Release with the commits since the previous tag and the kit builds + ROTO-SETUP files attached; a macOS job then builds the desktop app and attaches its .dmg. Installed apps offer the new version on their next launch (see docs/ELECTRON.md). Preview the notes with DRY_RUN=1 scripts/github-release.sh v0.1.1.

Layout

index.html            Designer page
src/engine/           WebGL2 particle renderer, custom geometry compiler, baked shapes, cycle
src/looks/            Factory catalog: looks, studies, baked looks, 4×16 factory slots
src/designer/         Designer UI: main loop, design schema, banks, dialogs, history, ROTO layout
src/roto/             ROTO-CONTROL Web MIDI driver and setup parser
src/embed/            Embed kit: ParticleField runtime, audio, <particle-field>, snippets
examples/             Embed sample pages (+ a custom design JSON)
server/               Dev-host APIs: AI generation (/api/generate), saved slots (/api/slots)
electron/             Mac app: shell, loopback host serving dist/ + the APIs, update check
scripts/              Bake, ROTO presets, rehearsals, site/Electron builds, Vectrex wordmark
roto/                 ROTO-SETUP files (MIDI channels 9–11)
docs/                 DESIGNER.md (reference), EMBED.md (embed kit), ROTO-CONTROL.md (hardware),
                      ELECTRON.md (Mac app)
tests/                Vitest suites

Below the embed kit, ParticleRenderer (src/engine/renderer.ts) is the raw seam: render(timeMs, drive) every frame and dispose() when done. It owns no loop, clock, DOM or audio.

Roadmap

• Documentation site
• Signed and notarized Mac app (Apple Developer ID), with automatic updates

License

MIT © 2026 Reza Kalfane, Absolumont Collective