Platform parity matrix

FieldHandle coverage

Platform notes

All three platforms briefly shipped the full 44-method surface as of June 2026 (#822 Swift, #823 Kotlin) — the JS-side surface has grown since (now 52 methods; see the live counts above), and the ports have not fully caught up. Some methods behave differently across platforms by design:

Three.js — 52/52, host-context notes

@fundamental-engine/three delegates all 52 methods to the wrapped FieldHandle. Some are contextually different in a 3D scene: setRender / setOverlay / setBackground are owned by the Three.js renderer — use threeBackend() for diagnostic overlays. scrollV returns 0 (no DOM scroll). scan / rescan are called internally; in Three.js register bodies via layer.addBody(mesh, spec).

sample — force probe

Swift delegates to forceAt(bodies:forces:env:at:) in Streamlines.swift. Kotlin delegates to FieldController.sample() which calls the same forceAt() function used by the streamlines overlay. Both are safe to call between ticks.

on — event bus

Both platforms use a UUID-keyed subscriber registry (not closure equality, which doesn't hold across captures). FieldEvent.tick fires after every simulation step via an onAfterTick hook. bodyAdd / bodyRemove fire from the addBody / remove path. Returns a Subscription; call .cancel() to unsubscribe.

addAgent — autonomous consumers

AgentSpec carries a position closure sampled each tick; onInfluence receives the net force vector at that point. Agents are ticked via the same onAfterTick hook as the event bus, after each force step.

readParticleIds / readParticleChannels

Particle.id is assigned by FieldStore.add() via a monotonically increasing counter — stable for the lifetime of the pool. readParticleChannels samples each named ScalarGrid at each particle's position; the output stride equals the number of channel names.

registerOverlay

OverlayRenderer is a protocol (Swift) / interface (Kotlin). The FieldHandle keeps a [String: OverlayRenderer] registry the platform host frame loop reads to call render() after the underlay draw each frame. No deep engine integration — pure registry delegation.