Diagnostic overlays
The diagnostics module computes the data; these overlays draw it. Every diagnostic mode now ships — contours, potential, force and velocity vectors, energy, topology, inspector, causality, and prediction. Toggle a layer — each reads field state and never mutates it.
Runtime observables
Beyond the canvas overlays above, the engine exposes pull-based data surfaces through
FieldHandle and @fundamental-engine/core:
| API | Returns | Source |
|---|---|---|
handle.particleCount() | number | Live pool size (store.size). No particle-array walk. |
handle.energy() | { kinetic, thermal, total, count } | Per-frame energy snapshot. Forwards to energyReport() from diagnostics/energy. |
inspectBudget(counts) | BudgetFinding[] | Checks supplied counts against DEFAULT_BUDGET. Partial-safe. |
systemReport() | SystemReport | Force/passport/contract/agent counts + missing-passport list. Stable after mount. |
causalityAt(x, y) | CausalContribution[] | Per-force Δv decomposition at a point. Powers the causality overlay above. |
All are pure — they read state, they do not mutate physics. particleCount() and
energy() are shipped-but-unfrozen; inspectBudget /
systemReport / causalityAt are the same. See the
performance docs for the full observable surface and the
FieldPerf design direction.
Render-mode status
| Mode | Type | Shows | Status |
|---|---|---|---|
dots | matter | particle positions and heat | shipped |
trails | motion | path history | shipped |
links | topology | connector lines between bodies | shipped |
streamlines | structure | continuous field paths | shipped |
metaballs | matter | liquid density surface | shipped |
voronoi | matter | nearest-site cells | shipped |
field-lines | structure | field() geometry | shipped |
heatmap | scalar | density accumulation | shipped |
force-vectors | debug | actual cause from apply() | shipped |
contours | scalar | equal-value isolines | shipped |
potential | scalar | wells and gradients | shipped |
energy | scalar | kinetic / potential / thermal | shipped |
topology | graph | threads, flux links | shipped |
inspector | debug | bodies, agents, metrics, contracts | shipped |
causality | debug | contribution sources | shipped |
prediction | debug | ghost trajectory | shipped |