createField & options frozen · @fundamental-engine/core

Signature

import { createField } from '@fundamental-engine/core';
import { browserHost } from '@fundamental-engine/platform';

const field = createField(canvas, { host: browserHost(), ...options });   // → FieldHandle

// browser convenience — @fundamental-engine/vanilla re-exports a createField that wires browserHost() for you:
import { createField } from '@fundamental-engine/vanilla';
const field2 = createField(canvas, options);                              // host wired internally

FieldOptions

Every field is optional. Defaults keep the live field unchanged until you opt in.

host frozen · @fundamental-engine/core FieldHost · default required

The environment seam (viewport, scroll, rAF, canvas). createField throws without it — pass browserHost() from @fundamental-engine/platform, or use @fundamental-engine/vanilla / the web component, which wire it for you.

accent string · default palette's first stop

The travelling accent color (a hex string).

density number · default 1

Particle-count multiplier.

waves boolean · default true

Draw the background Currents (the wave layers).

background 'opaque' | 'transparent' · default 'opaque'

Substrate background. 'transparent' clears to transparent instead of painting the near-black substrate, so the underlay composites over light content (an image, a 3D scene, a light page) — trails fade to transparent rather than to black. Also a <field-root background> attribute and live via setBackground.

depth number · default 0

Optional z volume. 0 (the default) is the flat field, byte-identical to the 2D engine; > 0 opens a shallow depth the matter drifts through, projected as a size/alpha recession. Purely additive — no API requires z.

render 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' · default 'dots'

Render mode for the underlay surface (behind content) — the same physics drawn differently.

overlay OverlayMode | OverlayMode[] · default 'off'

Field Surfaces: the overlay READING(S) drawn in front of content (see the overlay-readings table) — one reading or an additive stack. Set alongside render. <field-root> manages the front canvas (space-separated tokens in the attribute); for createField directly, pass overlayCanvas.

mass boolean · default false

First-class mass: particle mass ∝ size and body forces accelerate by a = F/m.

palette string | string[] · default 'ours'

Accent template — a built-in name or custom hex stops.

attention boolean · default false

Conserved attention — one finite strength budget; engaging a body starves the others.

causality boolean · default false

Cross-boundary causality — a saturated body spills density to its neighbours.

heatmap boolean · default false

Density heatmap — a glow layer of where matter pools, sampled back to bodies as --field-heatmap-density.

overlayCanvas HTMLCanvasElement · default undefined

Field Surfaces: a caller-provided canvas for the overlay surface (drawn in front of content). The web component creates/manages this for you; pass it only when calling createField directly.

feedbackSink FeedbackSink · default undefined

Advanced: route per-body density/feedback writes to the platform FeedbackRegistry instead of letting the engine write the DOM (Phase D3).

Common configurations

Every option is optional and the defaults keep the field calm. These are the combinations worth knowing — each is the whole options object (the host is omitted; wire it per the signature above, or use @fundamental-engine/vanilla). Switch tabs to compare.

// the resting field — an accent and a palette, nothing else
createField(canvas, { accent: '#4da3ff', palette: 'ours' });

// draw the force field itself as arrows — a diagnostic view
createField(canvas, { render: 'streamlines' });

// focus one thing at a time — one finite strength budget,
// so engaging a body starves the others
createField(canvas, { attention: true });

// a large or low-power surface — half the particles, no wave layer
createField(canvas, { density: 0.5, waves: false });

// first-class mass — particle mass ∝ size, bodies accelerate by a = F/m
createField(canvas, { mass: true });