The imperative API reference

Creating a field

Every entry point hands back the same handle. @fundamental-engine/core is host-agnostic and needs an explicit host; @fundamental-engine/vanilla, the React FieldField and <field-root> wire browserHost() for you. On <field-root> the handle is proxied onto the element, so the element is the handle.

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

// core is host-agnostic: it needs a host, and nothing else
const field = createField({ host: browserHost(), density: 1.2, render: 'dots' });

field.setFormation('wells');
field.setRender('links');
field.destroy();          // release the loop + listeners

import FundamentalCore

var opts = FieldOptions()
opts.density = 1.2
opts.render = .dots

let field = makeField(host: host, options: opts)

field.setFormation("wells")
field.setRender(.links)
field.destroy()

import com.fundamental.core.runtime.createField

// no FieldOptions struct on this plane: construction args + setters
val field = createField(host = host, particleCount = 300)

field.setFormation("wells")
field.setRender(RenderMode.LINKS)
field.destroy()

Read that honestly. Kotlin has no options struct at all — it configures at createField(host, …) and through the handle's setters, so its column counts both. That is an idiom difference. What the counts do show is a real spread: the web plane carries the whole visual-tuning vocabulary (the gradient, grid and wave lanes, the overlay-canvas seam) because the engine owns the draw there, while the ports hand drawing to a host and expose the physics knobs instead.

createField — the 41 options

Each option is also a kebab-case <field-root> attribute; setting the attribute after mount calls the matching setter on the live handle. The support row is for the capability — whether that plane can configure it at all, at construction or live.

Where the field lives

`createField` throws without a host. `@fundamental-engine/vanilla`, the React component and `<field-root>` all supply one for you — reach for a host directly when you are writing your own surface.

host FieldHost · default required JS ✓ Swift ✓ Kotlin ✓

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

bounds HTMLElement · default window web surface only

Contained fields (#540): scope the field to a single element instead of the viewport. A vanilla createField / new FieldField option — the field measures and renders inside the given element (a card, a panel), so a component can carry its own local field. Omit for the default full-window field. (containerHost() is the lower-level door.)

Matter and motion

How much matter there is, how it moves, and how it comes to rest.

density number · default 1 JS ✓ Swift ✓ Kotlin —

Particle-count multiplier.

depth number · default 0 JS ✓ Swift — Kotlin ✓

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.

depthFocal number · default 480 JS ✓ Swift — Kotlin —

DECLARED render reference point (Wallpaper Rule, #975): the perspective focal length (CSS px) of the depth mode's camera — larger flattens the perspective, smaller exaggerates it. Formerly a hardcoded FOCAL = 480; the default reproduces it exactly, so the depth render is byte-identical. Only affects the depth render mode (pairs with depth > 0). Experimental.

separation number · default 0 JS ✓ Swift ✓ Kotlin ✓

Strength of short-range particle-to-particle separation/repulsion force ∈ [0,1] to break up clumps in high-density areas. <field-root separation>.

mass boolean · default false JS ✓ Swift — Kotlin —

First-class mass: particle mass ∝ size and body forces accelerate by a = F/m; dynamic bodies also get inertial mass ∝ rendered area (#872).

integrator 'legacy' | 'fixed' | 'velocity-verlet' · default 'legacy' JS ✓ Swift ✓ Kotlin —

Integration scheme (substrate doc 04 §Step 3, #659). 'fixed' opts into the partially frame-rate-corrected integrator: the FRICTION/HEAT_DECAY decays scale with dt (FRICTION^dt), so damping is consistent across frame rates — but by design it does NOT yet dt-scale force impulses (unsound for pair forces that mutate a neighbour in the same pass; deferred to the force-contract change, integrator.ts applyForce / doc-04 §Step 3); at the reference rate (dt === 1, and every golden/conformance run) it is byte-identical to the default 'legacy' semi-implicit Euler, so opting in never moves the golden. 'velocity-verlet' opts into the second-order velocity-Verlet scheme: the position full-step uses the previous step's stored acceleration (x += v·dt + ½·a·dt²), the force pass evaluates a′ at the updated position, and the velocity takes the half-step average (v += ½·(a + a′)·dt); kinematic velocity-replacing forces (jet/wall/lens/gate/warp) bypass the average as discontinuities, and decays are dt-scaled like 'fixed'. Higher positional accuracy, NOT a conservation guarantee (energy/momentum stay non-conserved by design; the per-step decay keeps it non-symplectic) — trajectories differ from 'legacy' by design once opted in. The default path never engages either mode. <field-root integrator>. Experimental.

restingMotion { mode: 'thermal' | 'flow'; strength?: number } · default undefined (off) JS ✓ Swift ✓ Kotlin —

The resting-motion floor (DECLARED, default OFF). Signals-first defaults leave a DRAWN field (render: 'dots') settling into its attract wells and freezing when idle; this is the honest, global alternative to painting waves — a small per-particle impulse the field MEASURES as --temperature, with nothing drawn. 'thermal' is the thermal force's Langevin kick applied field-wide (Box–Muller through the injected rng, so a seeded run reproduces); 'flow' is a divergence-free curl (the stream function ψ = sin(kx+φ)·sin(ky−φ), one eddy ≈ 400px) with a slow phase drift so it never settles. strength multiplies the impulse (default 1; 0 = off). Both scale with dt, so reduced motion (dt = 0) contributes exactly nothing. Default-off ⇒ the cross-plane conformance golden is untouched. <field-root resting-motion="thermal"> / <field-root resting-motion="flow 0.5">. Mirrored on Swift (FieldOptions.restingMotion) and Kotlin (createField(restingMotion =)).

ambientOrbit number · default 0.1 JS ✓ Swift ✓ Kotlin —

DECLARED ambient bias (Wallpaper Rule, #978): the resting ambient formation's tangential swirl injected into attract bodies — the gentle spiral free matter traces around a well at rest. Formerly a hardcoded 0.1 painted into the default formation preset; now a documented dial defaulting to that value (resting behavior unchanged). Set 0 for a purely radial attract (no spiral). Applies to the ambient formation only. <field-root ambient-orbit>.

ambientWander number · default 1.0 JS ✓ Swift ✓ Kotlin —

DECLARED ambient bias (Wallpaper Rule, #978): the resting ambient formation's wander term — the per-particle drift that keeps resting matter alive rather than frozen. Formerly a hardcoded 1.0 in the default formation preset; now a documented dial defaulting to that value (behavior unchanged). Lower for a calmer rest, 0 to still the drift. Applies to the ambient formation only. <field-root ambient-wander>.

rng () => number · default Math.random JS ✓ Swift ✓ Kotlin —

Random source for ALL engine randomness — particle seeding, spawn scatter, jitter, release angles (#371). Supply a seeded generator to make a run reproducible (the record/replay seam).

now () => number · default performance.now JS ✓ Swift — Kotlin —

Wall-clock source for input-idle tracking (#371) — one of the three engine clocks (wall / frame / simulation). Defaults to performance.now; override in tests or replay harnesses.

Colour and the substrate

What the field is drawn with. The palette lane is tracked as its own parity dimension after a port collapsed it to a single accent (#1090).

accent string · default palette's first stop JS ✓ Swift ✓ Kotlin ✓

The travelling accent color (a hex string).

palette string | string[] · default 'ours' JS ✓ Swift ✓ Kotlin ✓

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

theme string · default 'warm' JS ✓ Swift — Kotlin —

Ambient theme preset — 'warm' | 'cool' | 'mono'. Sets the free-particle heat ramp and the background-wave baseline (distinct from the travelling accent). 'warm' reproduces the shipped default.

background 'opaque' | 'transparent' · default 'opaque' JS ✓ Swift ✓ Kotlin ✓

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.

gradientWarm string · default theme's JS ✓ Swift — Kotlin —

Hex for the warm (energized) end of the heat ramp — overrides the theme. <field-root gradient-warm>.

gradientCool string · default theme's JS ✓ Swift — Kotlin —

Hex for the cool (resting) end of the free-particle heat ramp — overrides the theme. <field-root gradient-cool>.

redshiftObserver { x: number; y: number } · default { x: 0.5, y: 0.5 } JS ✓ Swift — Kotlin —

DECLARED render reference point (Wallpaper Rule, #975): the observer the redshift mode measures each particle's radial velocity against (receding reddens, approaching blues), as viewport fractions ∈ [0,1]. Formerly a hardcoded (W/2, H/2); the default reproduces it exactly, so the redshift render is byte-identical. Only affects the redshift render mode. Experimental.

The draw layers

What is painted, and onto what. An overlay is a silent no-op without an overlay canvas — the single most common "nothing happened" in the imperative path.

render 'none' | 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'knockout' | 'redshift' | 'blackbody' | 'depth' · default 'none' JS ✓ Swift ✓ Kotlin ✓

Render mode for the underlay surface (behind content) — the same physics drawn differently. The default is 'none' (#538): the signals-only engine runs the full simulation + feedback (--d, --load, capture events) but draws nothing — the field is behavior first. Opt into a visible surface with 'dots' (particles) or another mode.

overlay OverlayMode | OverlayMode[] · default 'off' JS ✓ Swift ✓ Kotlin ✓

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.

overlayCanvas HTMLCanvasElement · default undefined JS ✓ Swift — Kotlin —

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 — createOverlaySurface() in @fundamental-engine/dom creates and places the same fixed, click-through, aria-hidden canvas (configurable blend / z-index) so you need not hand-roll it (#721).

overlayCanvasProvider () => HTMLCanvasElement | null · default undefined JS ✓ Swift — Kotlin —

Field Surfaces: a lazy alternative to overlayCanvas (#676). When no overlayCanvas is set, core calls this once — the first time an overlay reading actually goes active — to obtain the surface. Lets a host defer creating its full-viewport mix-blend canvas until an overlay is switched on, so the common overlay:off path never adds a canvas to the compositing tree at boot. <field-root> uses this internally; return null to decline. Ignored when overlayCanvas is set.

overlayBackend RenderBackend · default Canvas 2D JS ✓ Swift — Kotlin —

Drawing backend for the overlay surface (#373) — the structural seam a WebGL/WebGPU surface implements. Defaults to the Canvas 2D implementation over overlayCanvas. See render-backend.ts.

heatmap boolean · default false JS ✓ Swift ✓ Kotlin ✓

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

heatmapFade { start: number; span: number } · default { start: 0.3, span: 0.85 } JS ✓ Swift — Kotlin —

DECLARED page-layout reference (Wallpaper Rule, #975): how the density heatmap glow fades with scroll position — full above start·H, gone by (start+span)·H (H = viewport height). Formerly a hardcoded (1.15 - scrollY/H)/0.85 "content = first viewport" assumption; the default reproduces it exactly (full through 0.3 viewports, gone by 1.15), so the heatmap glow is byte-identical. Set a large span to disable the scroll fade. Only affects the density heatmap layer. Experimental.

heatCenter { x: number; y: number } · default { x: 0.5, y: 0.4 } JS ✓ Swift — Kotlin —

DECLARED render reference point (Wallpaper Rule, #975): the center of the cool→warm heat vignette the dots/depth swarm is tinted against, as viewport fractions ∈ [0,1] (resolved to px each frame). Formerly a hardcoded (W/2, H·0.4); the default reproduces it exactly, so the default render is byte-identical. Only affects the dots/depth render modes. Experimental.

gridIntensity number · default 0.16 JS ✓ Swift — Kotlin —

Stroke intensity (opacity) of the grid overlay lattice ∈ [0,1] — turns the warped grid from a faint diagnostic into a visual centerpiece (#552). 0.16 is the calibrated default; raise it (~0.4) to make the bending space the hero of a section. Only affects the grid overlay mode. <field-root grid-intensity>.

gridWarp number · default 1 JS ✓ Swift — Kotlin —

Distortion multiplier for the grid overlay (the reference lattice displaced by the field). 1 is the calibrated "legible, never chaotic" deflection; 2–3 exaggerates the deformation for demos; 0 flattens the lattice. Only affects the grid overlay mode. <field-root grid-warp>.

waves boolean · default false JS ✓ Swift ✓ Kotlin ✓

Draw the background Currents (the wave layers + bound shimmer). Opt-in (#979): a bare field has no carrier waves; pass true for the ambient resting structure.

waveStyle 'linear' | 'circular' · default 'linear' JS ✓ Swift ✓ Kotlin ✓

The wave current pattern. linear draws parallel horizontal waves; circular draws concentric orbits circling around the waveCenter or the star body. <field-root wave-style>.

waveCenter Vec2 | (() => Vec2) | null · default null JS ✓ Swift ✓ Kotlin ✓

The center coordinate (or coordinate-provider fn) for circular waves. Defaults to the first body tagged with star or vortex, or the center of the field. <field-root wave-center> (space-separated, e.g. "200 300").

waveBaseline string[] · default theme's JS ✓ Swift — Kotlin —

Hex stops for the background-wave baseline — overrides the theme. <field-root wave-baseline> (space-separated).

The two-way loop

Where the field writes its readings back to. The default DOM sink writes CSS custom properties; a `feedbackSink` takes the same readings as plain data, which is how a non-DOM host — or a test — consumes them.

feedbackSink FeedbackSink · default undefined JS ✓ Swift ✓ Kotlin —

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

reaction boolean · default false JS ✓ Swift — Kotlin —

Newtonian own-emission reaction (#873): a dynamic body feels the equal-and-opposite of the net impulse it imparts to nearby matter (a directional emitter recoils like a rocket). Best paired with mass. Experimental.

attention boolean · default false JS ✓ Swift ✓ Kotlin ✓

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

causality boolean · default false JS ✓ Swift ✓ Kotlin ✓

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

Cost, identity and permission

The three lanes that are about governance rather than looks.

dprCap number · default 2 JS ✓ Swift ✓ Kotlin ✓

Backing-store device-pixel-ratio ceiling (#410) — the dominant fill-rate lever. Effective DPR = min(devicePixelRatio, dprCap); capping at ~1.5 buys ~1.8× headroom on retina for a small perceptual softening. Runtime-settable via setDprCap. <field-root dpr-cap>.

identify (el: HTMLElement) => FieldBodyIdentity | undefined · default undefined JS ✓ Swift ✓ Kotlin ✓

First-class body identity resolver: derive a stable, structured FieldBodyIdentity ({ id, namespace?, kind?, host? }) from a DOM-scanned body's element, called once per body. The identity is surfaced on query()/snapshot() body readings and used as the stable key for diff/replay/relationships. Return undefined to fall back to the default derivation (the element DOM id, else a monotonic body-N). Purely additive — a field without identify behaves exactly as before.

policy FieldPolicy · default undefined JS ✓ Swift ✓ Kotlin ✓

Runtime FIELD POLICY — what THIS host/session/user/app PERMITS at runtime (distinct lane from governance, which is what doctrine allows via static lint). FieldPolicy { allowBodyDataInSnapshots?, allowMotionProjection?, maxMotionBudget? (0..1), budgets?: Partial<FieldBudgets> }; FieldBudgets bounds consumable resources: motion/force/attention/thermal/render/privacy/accessibility/agentRead. WIRED today: the motion budget folds (via min) with reduced-motion + perf pressure into the effective motion the integrator/easing reads — reduced-motion always wins (a policy can lower motion, never raise it); the privacy budget (+ allowBodyDataInSnapshots) gates body data in snapshot(). Other budgets are declared-not-yet-enforced. Change it live with setPolicy. Purely additive — a field with no policy behaves exactly as before.

The FieldHandle

55 entries covering the handle's 52 callable members and 4 properties — one entry documents setPolicy together with the policy it reads back. The handle is not at full parity across the planes, and it never was: the JS surface has grown faster than the ports. The numbers below are computed from the ports themselves.

Reading the field

The field is a source of state, not only of pixels — and the read paths are pure, headless and serializable, so they work under render: 'none' and in a test. There are three of them, at three grains.

1 · Probes — the field at a point

Synchronous, allocation-free, no snapshot involved. sampleScalar and sampleGradient read the diffused heatmap grid, so they need heatmap: true and return zero without it — that is the usual cause of a forage-by-gradient agent that will not steer.

// the pure probes — these work headless and under render: 'none'
field.setHeatmap(true);                             // sampleScalar/sampleGradient need the heatmap grid

const force   = field.sample(x, y);                  // { x, y } — net force a still test particle feels
const density = field.sampleScalar(x, y);            // 0..1, bilinear, non-degenerate at a source
const uphill  = field.sampleGradient(x, y);          // { x, y } in 1/px — steepest ascent

// bind your own data to the particles, then identify one under the pointer
field.seed(records);
const atom = field.atomAt(e.clientX, e.clientY);     // nearest seeded particle within ~24px, or null

2 · query() — a structured question about a region

Plain, serializable data about bodies, metrics, relationships and per-force influences, scoped to a point, a rect, or the whole field. at is DOMRect-shaped, so el.getBoundingClientRect() drops straight in.

// ask the live field a structured question — plain, serializable data
const answer = field.query({
  at: el.getBoundingClientRect(),          // a point, a DOMRect-shaped rect, or omit for the whole field
  radius: 240,
  include: ['bodies', 'metrics', 'relationships', 'influences'],
});

answer.bodies[0].metrics.density;          // what THIS body is gathering
answer.influences;                         // which force contributed what, at that point

3 · snapshot() → diff() → replay() — change over time

A snapshot captures what the field is doing at a frame. diff reports what changed between two captures, by lane; replay turns that diff into an ordered, narrated chain of causes. Both are pure — they read the two capture objects and never touch live state, so you can replay captures from another session, or from another machine.

// capture what the field is DOING this frame (not what it looked like)
const before = field.snapshot({ profile: 'agent' });
await userDoesSomething();
const after = field.snapshot({ profile: 'agent' });

// compare the two captures — pure, no live state involved
const changes = field.diff(before, after);

// and narrate the difference as an ordered chain of causes
for (const step of field.replay(before, after).steps) {
  console.log(step.cause, step.description);
  // "formation  Formation 'wells' activated"
  // "relationship  Relationship A→B strengthened 0.10→0.40"
}

Snapshot profiles

A profile is an inclusion preset. It composes with the explicit include* flags and the privacy budget and always resolves to the tightest result: a profile can never widen past what policy or an explicit deny allows.

debug JS ✓ Swift ✓ Kotlin ✓

Everything the call can legally include — body data still gated by the privacy budget. For a local inspector, not for export.

agent JS ✓ Swift ✓ Kotlin ✓

Ids, metrics, relationships, influences and projections; NO opaque body data. The shape meant to enter an agent turn.

bug-report JS ✓ Swift ✓ Kotlin ✓

Structural only — versions, formations, relationships, influences. No user data, so it can be attached to an issue.

public JS ✓ Swift ✓ Kotlin ✓

Minimal: ids and shape. No relationships, influences, metrics detail or data — safe to publish.

All four profiles ship on all three planes — this is one of the parts of the substrate that did port whole.

The agent view — forAgent

forAgent derives a read-only facade over the field. It is not a redacted copy of the handle: it has no mutators by shape — no addBody, no applyForce, no setPolicy — so "agent-readable" can never quietly become "agent-writable". Capabilities are an allow-list applied to every reading, then redactions strip dotted paths, and nothing can widen past the field's policy.

Three capabilities are shape gates rather than redactions: without read:snapshots the view has no snapshot, without read:replay no replay, and without read:focus no focusState. query is always present and is scoped from the inside instead — a denied agent is barred from the capture, never blinded.

// a read-only, capability-scoped view — agent-readable is NOT agent-writable
const view = field.forAgent({
  capabilities: ['read:metrics', 'read:relationships'],
  redactions: ['body.data'],               // stripped AFTER capability scoping
});

view.query({ include: ['metrics'] });      // scoped + redacted
view.snapshot({ profile: 'agent' });       // present, scoped to the grant
view.replay;                               // undefined — read:replay was not granted (a SHAPE gate)
view.addBody;                              // undefined — the facade has NO mutators, by shape

read:metrics WIRED JS ✓ Swift ✓ Kotlin ✓

Per-body and field metrics (density, load, temperature, salience, …). Without it every reading's metrics lane is stripped.

read:relationships WIRED JS ✓ Swift ✓ Kotlin ✓

The relationship graph — the edges between bodies, by id, with their strength and memory. Without it the lane is emptied and snapshots are forced to includeRelationships: false.

read:influences WIRED JS ✓ Swift ✓ Kotlin ✓

Per-force attribution at a point: which force contributed what, by channel (linear Δv or thermal heat), from the impulse accumulator.

read:body-data WIRED JS ✓ Swift ✓ Kotlin ✓

A body's opaque data record. Withheld even when a profile or includeData asked for it unless this is granted AND the privacy budget allows it.

read:projections WIRED JS ✓ Swift ✓ Kotlin ✓

The registered projections (substrate 05) reported by query() and snapshot() — metadata only, never a write seam.

read:replay WIRED (shape gate) JS ✓ Swift ✓ Kotlin ✓

The replay() method itself. One of the two members the facade omits entirely rather than redacting: without this grant, view.replay is undefined.

read:focus WIRED (shape gate) · JS only JS ✓ Swift — Kotlin —

EXPERIMENTAL. The focusState() digest and the per-source provenance split (WHO is focused) — the other shape gate: without it, view.focusState is undefined. The aggregate per-body salience still rides query()/snapshot() under the base grant. The Swift and Kotlin AgentCapability enums carry the other eight; this one is not ported.

read:snapshots WIRED (shape gate) JS ✓ Swift ✓ Kotlin ✓

The snapshot() method itself — the portable capture. Without this grant view.snapshot is undefined: the surface is CLOSED, not emptied, because an empty capture is indistinguishable from an empty field. query() is unaffected, so a denied agent is barred from the capture, never blinded. Mirrored on Swift and Kotlin, where the member returns nil/null instead — a protocol or class member cannot vanish.

read:diagnostics WIRED JS ✓ Swift ✓ Kotlin ✓

The raw particle pool inside a capture (includeParticles) — engine internal state rather than a modelled reading of bodies, relationships or metrics. Without it the pool is withheld even when an explicit flag or the debug profile asked for it (tightens, never widens). The port snapshots carry no particle lane yet, so on Swift and Kotlin the gate is wired at the option boundary and becomes observable when that lane lands.

All nine are wired. read:snapshots and read:diagnostics were part of the AgentCapability contract on all three planes while forAgent consulted neither, so withholding them granted access anyway; #1160 wired both, and each plane now carries a test asserting the deny direction. The status on each row above is read off the implementation, not assumed.

The one gap. One capability is JS-only today — read:focus — because the focus/attention substrate has not been ported yet. The other 8 grants exist verbatim, as the same read:* tokens, on all three planes.

Policy and budgets

FieldPolicy is the permission lane: what this host, session, user or app permits, evaluated live. It is a distinct lane from governance (what doctrine allows, checked statically by the lints). Policy can only tighten: reduced-motion always wins, so a policy may lower the motion allowance but never raise it.

// what THIS host/session/user permits — distinct from what doctrine allows
field.setPolicy({
  allowBodyDataInSnapshots: false,
  budgets: { motion: 0.4, privacy: 0.2 },
});

field.policy;                    // a frozen copy of the live policy
field.setPolicy({});             // REPLACES, not merges — {} clears to the unbounded default

setPolicy replaces rather than merges — {} clears to the unbounded default — and field.policy reads back a frozen copy. All 8 budget lanes exist on all three planes; what differs is how many are wired rather than declared, which the rows below state per lane rather than implying.

budgets.motion WIRED JS ✓ Swift ✓ Kotlin ✓

Cap on how much motion the field may express; 0 behaves as reduced-motion (frozen). Folds via min with the host reduced-motion state and perf pressure into the effective motion the integrator and easing read — reduced-motion always wins, so a policy can lower motion but never raise it.

budgets.privacy WIRED JS ✓ Swift ✓ Kotlin ✓

Below PRIVACY_DATA_THRESHOLD (0.5) snapshots withhold body data — regardless of includeData, the profile, or a read:body-data grant. The tightest-wins rule in one number.

budgets.force DECLARED JS ✓ Swift ✓ Kotlin ✓

Cap on applied force magnitude — the share of the impulse budget matter may absorb.

budgets.attention DECLARED JS ✓ Swift ✓ Kotlin ✓

Cap on conserved-attention spend — the finite focus budget allocateAttention divides.

budgets.thermal DECLARED JS ✓ Swift ✓ Kotlin ✓

Cap on thermal/heat accumulation the field may carry.

budgets.render DECLARED JS ✓ Swift ✓ Kotlin ✓

Cap on render cost the field may spend (draw layers / fill). The policy-lane sibling of dprCap and qualityTier, which ARE wired.

budgets.accessibility DECLARED JS ✓ Swift ✓ Kotlin ✓

Accessibility floor — the minimum non-motion legibility the field must preserve.

budgets.agentRead DECLARED (gate wired at 0) JS ✓ Swift ✓ Kotlin ✓

Cap on how much field state agent readers may consume. The fractional gradient is a declared seam; the zero case IS enforced — budgets.agentRead === 0 closes forAgent to the most-restricted view.

Identity — naming a body so a reading can refer to it

Snapshots, diff, replay, the relationship graph and focus() all address bodies by id, not by handle — otherwise a capture could not survive being serialized and read back somewhere else. Identity is therefore first-class rather than derived from the DOM.

BodySpec.identity JS ✓ Swift ✓ Kotlin ✓

A stable id (plus optional namespace / kind / host) supplied when you add the body. Give it the id your own domain already uses — file:src/auth.ts, a row key, a ticket number — and every later reading names the thing you care about.

FieldOptions.identify JS ✓ Swift ✓ Kotlin ✓

The resolver for bodies you did not add by hand — a scanned [data-body] element, a native view. Return an identity for the element and the same id flows through every read path. Return nothing and the engine derives a deterministic body-N.

Deriving an id is the fallback, not the design: a derived body-3 is stable within a session and meaningless across one. Supply an identity for anything you intend to diff, replay, focus or relate.

The body handle

addBody(spec) is the non-DOM half of the body contract — the same physics, the same forces, no element required. The declarative reference documents the spec; what comes back is documented here.

const body = field.addBody({
  tokens: 'attract swirl',
  strength: 0.8,
  rect: () => mesh.getBoundingBox(),        // the position source, sampled each frame
  identity: { id: 'file:src/auth.ts' },     // so snapshots/diff/replay can name it
  data: { path: 'src/auth.ts' },
  onFeedback: (ch) => (mesh.scale = 1 + ch.density * 0.5),
});

body.set({ strength: 0.2 });                // live, on the measure cadence — no rescan
body.channels.density;                      // this body's latest readings, updated in place
body.remove();

data JS ✓ Swift ✓ Kotlin ✓

The carried record (BodySpec.data), opaque to the engine. Mutable: assign to it and the next query()/snapshot() that includes data sees the new value.

channels JS ✓ Swift — Kotlin —

This body's latest feedback channels, updated IN PLACE each frame — the same seven readings the DOM sink writes to CSS variables, handed to a non-DOM host directly. Read it; do not hold a copy.

set JS ✓ Swift ✓ Kotlin ✓

Mutate force params live — { strength?, range?, angle? (degrees), spin?, color? } — applied within a frame on the measure cadence with no rescan(). Only the keys you pass change. A STRUCTURAL change (different tokens) still needs remove + addBody: tokens are classified once, not reactive.

remove JS ✓ Swift ✓ Kotlin ✓

Remove the body from the field. The handle is inert afterwards.

The ports carry two members the web does not. Swift and Kotlin body handles expose load (a sink's fill ∈ [0,1]) and drain() (take the accretion and reset the body) directly; on the web the same reading arrives through channels.load and the captured / released events instead. Kotlin additionally exposes the body's resolved identity on the handle. Those rows say so above rather than hiding it.

Discrete events

on(type, cb) is the host-agnostic push bus — for reacting to occurrences instead of polling the feedback channels every frame. It returns an unsubscribe function (a Subscription on the ports); subscribing to a type with no active bodies costs nothing. Events are thresholded, debounced, and coalesced per source per frame, so a same-frame fill-and-release delivers once.

const off = field.on('captured', ({ body, count }) => {
  // a sink body reached the rising edge of accretion
  badge.textContent = String(count);
});

field.on('met', ({ a, b }) => link(a, b));           // two bodies touched
off();                                                // unsubscribe

let sub = field.on(.captured) { payload in
    badge.text = String(Int(payload.count))
}
sub.cancel()

// the ports also carry lifecycle events the web bus does not expose:
field.on(.tick) { _ in /* after every simulation frame */ }

val sub = field.on(FieldEvent.CAPTURED) { payload ->
    badge.text = payload.count.toInt().toString()
}
sub.cancel()

field.on(FieldEvent.TICK) { /* after every simulation frame */ }

captured { body, count } JS ✓ Swift ✓ Kotlin ✓

A sink body captured matter — the rising edge of accretion. count is the matter held at that edge. Coalesced per (body, type) per frame, so a same-frame fill+release delivers once.

released { body, count } JS ✓ Swift ✓ Kotlin ✓

A sink body released what it held — the falling edge, or a supernova. count is what was held at the rising edge (or the number of particles ejected).

enter { body, other } JS ✓ Swift — Kotlin —

Another body crossed INTO this body's range (#441) — the “entered radius” trigger. Directed: the pair is keyed (body, other), so two counterparties in one frame stay distinct.

exit { body, other } JS ✓ Swift — Kotlin —

Another body crossed OUT of this body's range (#441). Thresholded and debounced, so hover jitter does not spam the bus.

met { a, b } JS ✓ Swift — Kotlin —

Two bodies came into contact — their boxes touched or overlapped (#441), delivered once on the rising edge. Keyed on the unordered pair.

focus FocusEvent JS ✓ Swift — Kotlin —

EXPERIMENTAL (focus/attention substrate). A focus() deposit landed — the write-back channel and its append-only provenance receipt. The payload is flat (no Body reference) so it serializes and mirrors 1:1 to the ports. Keyed by (target, source), so an operator and an agent deposit on the same body in one frame both survive.

This bus diverges on purpose, and in both directions. The web bus carries enter, exit, focus, met — the proximity trio and the focus write-back — which the ports have not taken yet. The ports carry body-add, body-remove, tick: lifecycle events a native host needs because it drives the frame loop itself, and which the web engine handles internally instead of publishing. captured and released are the shared pair, aligned across all three planes in #1020.

What each plane has that the others do not

The parity story is usually told as "the ports trail the web". On the handle that is only half true, and the lists below are computed from the port sources rather than asserted.

Web only 2 members

focus, focusState — the focus/attention substrate, whose ports are a batched follow-up.

Ports only 9 members

attach, effectiveMotion, feedReducedMotion, feedScrollV, pause, removeOverlay, resume, setWaves, tick — almost all of it is the seam a native host needs because it drives its own frame loop and owns its own input sources: loop control (pause / resume / tick / attach) and the feed methods (feedScrollV, feedReducedMotion, effectiveMotion). The remainder are idiom differences, not capability gaps: removeOverlay is the disposer registerOverlay already returns on the web, and setWaves is a live setter for what the web takes as the waves option.

Read-back Kotlin: 16 properties

Kotlin exposes a getter for nearly every setter (accent, renderMode, qualityTier, …) where the web and Swift handles are write-only. It does not expose version or guarantees, which the web does.

For the per-method table across Three.js as well, see the platform parity matrix; for the honest per-platform story, the Swift and Kotlin guides.