Cookbook

The visualization workbench

The same field can be drawn a dozen ways, and read several more. The surfaces are two tiers with genuinely different rules: one substrate behind your content, and any number of overlay readings in front of it. Knowing which is which is most of the API.

Shipped · demo runs live on this page

Two tiers, two rules

The substrate is the base layer: the same matter, drawn one way at a time. Picking trails replaces dots — there is only ever one base.

An overlay is a reading drawn on top, and readings compose: setOverlay takes an array and the engine draws them in order. So the substrate is a radio set and the overlays are checkboxes — a distinction the API makes structurally, not by convention.

TypeScript

// SUBSTRATE — the base layer, behind your content. One at a time.
field.setRender('streamlines');

// OVERLAY — diagnostic readings, drawn in FRONT. Additive: the engine takes an array,
// so these compose rather than replace each other.
field.setOverlay(['force-vectors', 'grid']);
field.setOverlay('off');            // clear the stack

JS ✓ Swift ✓ Kotlin ✓ JS ✓ Swift ✓ Kotlin ✓

The full vocabularies — 12 substrate modes and 9 overlay readings, each with the platforms that have it — are on the declarative reference. Two names look like exceptions and are worth stating here: field-lines is an overlay reading, and the heatmap is its own toggle (setHeatmap), not a render mode — which is why the RenderMode type and what setRender accepts are not the same list.

The overlay canvas — the silent no-op

An overlay draws in front of your content, so it needs a second canvas the engine can draw onto. If there isn't one, setOverlay does nothing and says nothing — the single most common "the API is broken" report, and it is a wiring gap rather than a bug.

<field-root> and the React component create that surface for you. A raw createField does not; createOverlaySurface is the one-call version, and it deliberately leaves the backing-store size to core so the DPR cap and quality tiers are honoured.

TypeScript

import { createOverlaySurface } from '@fundamental-engine/dom';

// An overlay reading needs a SECOND canvas in front of the page. Without one,
// setOverlay() is a silent no-op — the most common "why is nothing happening".
// <field-root> and the React binding create it for you; a raw createField does not.
const surface = createOverlaySurface(document);   // fixed, click-through, aria-hidden

const field = createField(canvas, {
  host,
  overlayCanvas: surface.canvas,   // core sizes it, honouring dprCap + quality tiers
});

The workbench, live

A contained field with the two tiers wired as they actually behave. Switch the substrate — one wins. Toggle the readings — they stack.

Substrate (pick one) · overlay (stack any) live on this page

a body to draw around

starting…

This demo has no overlay canvas of its own, so the overlay toggles record the stack the field is holding while the substrate is what you can see change — the no-op above, demonstrated rather than described.

The signal readout

The workbench's most useful panel is not a picture at all. Every frame the engine writes its measured channels onto each feedback body — density, load, lit, and the measured thermodynamics. Printing them next to the drawing is the moment the field stops looking like an effect and starts reading as an instrument.

CSS

/* The signal readout: the conversion moment. These are the values the
   engine writes onto a feedback body every frame — the field, in numbers. */
.readout::after {
  content: '--d ' var(--d, 0) ' · coherence ' var(--coherence, 0)
           ' · temperature ' var(--temperature, 0);
}

Every channel, its range and its cadence are on the declarative reference; the diagnostics page covers the explanatory overlays in depth.