@genart-dev/plugin-particles

Depth-aware atmospheric particle layers for genart.dev — falling, floating, scatter, mist, and trailing effects. 34 presets across 5 categories, with 9 MCP tools for AI-agent control.

Part of genart.dev — a generative art platform with an MCP server, desktop app, and IDE extensions.

Install

npm install @genart-dev/plugin-particles

Usage

import particlesPlugin from "@genart-dev/plugin-particles";
import { createDefaultRegistry } from "@genart-dev/core";

const registry = createDefaultRegistry();
registry.registerPlugin(particlesPlugin);

// Or access individual exports
import {
  ALL_PRESETS,
  getPreset,
  filterPresets,
  searchPresets,
  fallingLayerType,
  floatingLayerType,
  scatterLayerType,
  mistLayerType,
} from "@genart-dev/plugin-particles";

Layer Types (5)

Presets (34)

Falling (9)

Preview	ID	Name	Description
	snow	Snow	Gentle snowfall with depth-scaled flakes drifting in light wind
	rain	Rain	Streaking raindrops falling at a steep angle with subtle wind
	autumn-leaves	Autumn Leaves	Warm-toned leaves tumbling through the air with varied rotation
	petals	Cherry Blossom Petals	Delicate pink petals drifting and swirling on a spring breeze
	embers	Embers	Glowing hot embers rising and drifting from a fire
	ash-fall	Ash Fall	Grey volcanic ash drifting down in still air
	cherry-blossoms	Cherry Blossoms	Dense shower of cherry blossoms in a spring storm
	confetti	Confetti	Colorful confetti pieces tumbling chaotically through the air
	pine-needles	Pine Needles	Thin pine needles falling from conifers in autumn wind

Floating (8)

Preview	ID	Name	Description
	dust-motes	Dust Motes	Tiny dust particles catching light as they drift in still air
	fireflies	Fireflies	Warm glowing fireflies hovering in the dark with radial glow
	fog-wisps	Fog Wisps	Thin curving wisps of fog drifting at mid-height
	pollen	Pollen	Drifting pollen grains floating in warm sunlight
	dandelion-seeds	Dandelion Seeds	Wispy dandelion seeds floating on gentle currents
	butterflies	Butterflies	Colorful butterflies fluttering through a meadow
	bubbles	Bubbles	Translucent soap bubbles drifting upward with highlights
	sparkles	Sparkles	Bright sparkle points twinkling in the air

Scatter (6)

Preview	ID	Name	Description
	fallen-leaves	Fallen Leaves	Autumn leaves scattered on the ground with warm color variation
	pebbles	Pebbles	Small stones scattered across a ground plane with natural clustering
	wildflowers	Wildflowers	Colorful wildflowers dotting a meadow with center-weighted density
	shells	Shells	Seashells scattered along a beach shore
	acorns	Acorns	Acorns scattered beneath oak trees in clustered groups
	sea-foam	Sea Foam	Foamy bubbles along a shoreline edge

Mist (6)

Preview	ID	Name	Description
	morning-mist	Morning Mist	Soft mist hovering low in morning light, cool-white top fading to warm gold
	valley-fog	Valley Fog	Dense fog filling a valley floor with layered depth and soft edges
	mountain-haze	Mountain Haze	Thin atmospheric haze across a wide elevation range
	ground-steam	Ground Steam	Rising steam from warm ground with tight low band and vertical drift
	ground-steam-thick	Ground Steam (Thick)	Dense billowing steam rising from hot ground with heavy layering
	smoke-wisps	Smoke Wisps	Thin wisps of smoke curling upward with organic noise patterns

Trailing (5)

Preview	ID	Name	Description
	meteor-shower	Meteor Shower	Blue-white meteors streaking across a night sky with glowing heads
	speed-rain	Speed Rain	Dense near-vertical rain streaks with depth
	shooting-stars	Shooting Stars	Warm golden shooting stars arcing with soft glowing heads
	light-trails	Light Trails	Horizontal warm light streaks — long exposure bokeh effect
	rising-sparks	Rising Sparks	Orange-red sparks and embers rising upward in a spreading fan

Shared Depth System

All particle layers share a common depth model that controls how particles recede into the scene:

• DepthEasing — linear, quadratic, cubic, exponential curves for size and opacity falloff
• DepthDistribution — uniform, foreground-heavy, background-heavy, midground control particle density placement
• computeDepth() — Returns 0..1 depth value for a particle based on its position and the horizon line
• applyDepthToParticle() — Scales size and opacity for a particle given its depth value and easing curve
• sampleDepthDistribution() — Samples a random depth value biased by the chosen distribution mode

import {
  applyDepthEasing,
  computeDepth,
  applyDepthToParticle,
  sampleDepthDistribution,
} from "@genart-dev/plugin-particles";

22 Shape Renderers

Each particle type has a dedicated canvas2d shape renderer:

import {
  getFallingShape,
  getFloatingShape,
  getScatterShape,
  drawSnowflake,
  drawFirefly,
  drawStone,
} from "@genart-dev/plugin-particles";

MCP Tools (9)

Exposed to AI agents through the MCP server when this plugin is registered:

Atmosphere Recipes (6)

The create_atmosphere tool composes multi-layer scenes from curated preset combinations:

Preview	Recipe	Layers	Description
	winter-storm	snow + fog-wisps + mountain-haze	Heavy snowfall with obscuring mist and distant haze
	autumn-forest	autumn-leaves + fallen-leaves + morning-mist	Falling and fallen leaves in a misty forest
	misty-morning	morning-mist + dust-motes	Soft low mist with sunlit dust particles
	firefly-night	fireflies + fog-wisps	Glowing fireflies drifting through night fog
	spring-meadow	petals + pollen + wildflowers	Drifting petals and pollen above a wildflower meadow
	dusty-ruins	dust-motes + pebbles + ground-steam	Dust and steam rising among scattered rubble

Rendering

Each layer type renders via canvas2d:

• Falling — Seed-deterministic positions with depth-scaled size and opacity; 7 shape renderers (snowflake, raindrop, leaf, petal, ash, dust, circle)
• Floating — Fractal noise drift per particle (no grid sync artifacts); driftPhase offsets the noise field; verticalBias skews the Y distribution; glowRadius controls halo size
• Scatter — Elements scattered between groundY and canvas bottom with perspective depth scaling size and opacity
• Mist — Fractal noise sampled into a 1/4-resolution buffer, then scaled up for soft fog bands with configurable edge softness

Utilities

Shared utilities exported for advanced use:

import {
  mulberry32,                          // Deterministic PRNG
  createValueNoise, createFractalNoise, // Procedural noise generators
  parseHex, toHex, lerpColor, varyColor, // Color interpolation and variation
  applyDepthEasing,                    // Depth curve functions
} from "@genart-dev/plugin-particles";

Preset Discovery

import { ALL_PRESETS, filterPresets, searchPresets, getPreset } from "@genart-dev/plugin-particles";

// All 34 presets
console.log(ALL_PRESETS.length); // 34

// Filter by category
const falling = filterPresets({ category: "falling" });   // 9 presets
const mist = filterPresets({ category: "mist" });         // 6 presets

// Full-text search
const results = searchPresets("fire"); // fireflies

// Look up by ID
const preset = getPreset("snow");

Examples

The examples/ directory contains 40 .genart files (34 individual presets + 6 atmosphere recipes) with rendered PNG thumbnails.

# Generate .genart example files
node generate-examples.cjs

# Render all examples to PNG (requires @genart-dev/cli)
node render-examples.cjs

# Generate per-category gallery montages
bash generate-galleries.sh

A workspace file at examples/particles-gallery.genart-workspace lays out all examples in a grid for browsing in the desktop app.

Related Packages

Support

Questions, bugs, or feedback — support@genart.dev or open an issue.

License

MIT