API reference

Conditions, global formation modes & render modes

The dimensions that shape the field independently of the forces themselves — when a force acts, a bias on every particle, how the field is drawn, and its color.

Conditions

Gate any force with data-when; it acts only while the condition holds.

active per body: Only while the body is engaged..
fast per particle: Only on fast-moving matter (v² > 0.9)..
slow per particle: Only on calm matter (v² < 0.22)..
hot per particle: Only on energized matter (heat > 0.3)..
cool per particle: Only on calm, un-energized matter (heat < 0.08)..
scrolling per body: Only while the page is scrolling..

Global formation modes

A global formation mode is a single whole-field bias applied to particles and field matter. Switch it live with field.setFormation(name). This is not a Field Pattern — a Field Pattern is an authored arrangement, represented by the FieldPattern type.

ambient resting drift: Ambient — the Hero state.
wells matter pools: Wells — the Work state.
lanes a current carries: Lanes — the Writing state.
scatter energy dispersed: Scatter — the Practice state.
accretion everything gathers: Accretion — the Contact state.

Render modes

The same physics, drawn differently. Set render or call field.setRender(mode).

dots: The default — each particle a soft dot, cool centre → warm edge → accent.
trails: Light-painting — particle history persists and fades.
links: Constellation — lines drawn between nearby particles.
metaballs: A liquid iso-surface — the swarm rendered as one molten skin via marching squares, not dots.
voronoi: Shattered glass — each particle owns a cell; the walls are the boundaries between nearest-neighbour regions.
streamlines: Draws the force field itself — a grid of arrows along the net push. A diagnostic view, REPLACES the dots.
flow: The dots AND the streamline arrows together in the one underlay canvas — particles drifting along the visible flow. No second blended surface, so it stays cheap.
knockout: Figure-ground inversion — the field paints a solid accent wash and matter is punched out as negative space (a print knockout). Clip the canvas to real type with a CSS mask for the field-inside-letters treatment; matter never assembles into letterforms.
redshift: Dots tinted by spectral shift instead of the heat ramp — Doppler from each particle's radial velocity (receding reds, approaching blues) plus a gravitational red near body wells. The relativistic accretion-disk look.
blackbody: Dots tinted by energy on a thermal ramp — near-black ember → deep red → orange → warm white → blue-white — with brightness rising with temperature. Physically-warm color, not radiometry.
depth: The z lane made visible (2.5D) — far-to-near painter's sorting so near matter occludes far, perspective parallax toward the viewport centre, and defocus with distance. Pairs with a depth > 0 field; identical geometry to dots when flat.

Overlay readings

Field Surfaces, the front layer — line-drawn diagnostics over the content. Set overlay or call field.setOverlay(reading); readings are additive — pass a stack (['grid','path'], or space-separated in the attribute) and they compose over whatever the underlay is drawing.

streamlines: Arrows along the net push a still probe would feel — vector flow, felt.
force-vectors: The same arrows scaled by raw magnitude — strong forces read strong, weak stay faint.
field-lines: Arrows along the structure-only field (dipoles / monopoles) — the geometry, not the felt push.
grid: A reference lattice displaced by the local field — space itself made visible, bending where the field is strong.
temperature: Iso-contour rings of accumulated particle heat — the thermal field, drawn as lines so it never paints over content.
energy: Iso-contour rings of kinetic energy (½m·|v|²) — where the motion is.
path: Streamline curves traced from seeded probes — where the field would carry a particle over distance.
data: A numeric density readout beside each measuring body — the --d measurement made legible.

Palettes

The color template the travelling accent journeys through. Swap with field.setPalette(name).

ours: #4da3ff #2dd4bf #a78bfa #ff6e9c #ff9d5c
heatmap: #2b3a8c #2d8fd4 #3fd07a #ffe14d #ff8a3d #e23b3b
infrared: #2a0a4a #8e24aa #e53935 #ff8f00 #ffd54f #fffde7
spectrum: #ff3b30 #ff9500 #ffcc00 #34c759 #00c7be #007aff #af52de