---
title: Adaptive Matter Continuum
description: The engine's persistent-matter stack: hierarchical packets, automatic fidelity, adaptive fluids, sparse fields, structural bonds, phase transcoding, evidence, conservation, and replay.
updated: 2026-09-21
---

# Adaptive Matter Continuum

The Adaptive Matter Continuum represents persistent matter with packets, fields, bonds, aggregates, and local surfaces. It is for engine developers who need physical detail to change with hardware and interaction risk without changing identity or conserved quantities.

## Core rule

A [Matter packet](../getting-started/glossary.md#matter) owns a bounded region of canonical matter. A split changes one packet into eight descendants. A merge reverses a compatible sibling set. Both operations emit conservation receipts and preserve mass, represented volume, momentum, angular momentum, and tracked energy. (Source: `engine/matter/codec/AdaptiveMatterPacketCodec.js`.)

Render samples, SPH transition-shell projections, local distance voxels, sparse-grid cells, and rigid aggregates are representations. They do not silently become additional mass owners. The code validates this boundary explicitly. (Sources: `engine/matter/fluid/AdaptiveFluidContracts.js`, `engine/matter/fluid/AdaptiveSphReference.js`, `engine/matter/fluid/SparseFluidBrickGrid.js`.)

## Module map

| Layer | Path | Responsibility |
| --- | --- | --- |
| Packet contract and codec | `engine/matter/codec/` | Finite paged storage, stable handles, hierarchical lineage, atomic split/merge, receipts, snapshots |
| GPU runtime | `engine/matter/runtime/` | Packet arena, stable spatial index, 17-stage frame contract, diagnostics, replay, device recreation |
| Automatic fidelity | `engine/matter/runtime/MatterFidelityGovernor.js` | Spatial level, physical tier, time bin, solver work, promotion limits, memory and frame budgets |
| Adaptive fluid | `engine/matter/fluid/` | Mixed-resolution SPH reference, deterministic neighbor broad phase, proxy-ray prediction, refinement controller, transition shells, sparse bricks, local distance tiles |
| Bond Fabric | `engine/matter/structural/` | XPBD constraints, material profiles, monotonic damage, real edge deletion, cracks, components, aggregates |
| Phase transcoding | `engine/matter/transcoding/` | Journaled phase-family changes with reservoir deltas and atomic structural policy |
| Realm Matter Fabric | `engine/matter/fabric/` | Definitions, observations, transformations, graph planning, conservation, lineage ledger, offline domain packs |
| Playground proof | `tests/playground/src/demos/matterContinuum/` | Continuous impact/water experiment plus the original 15-stage reference workbench |

The public engine namespace exposes these modules through `engine/matter/index.js` and `EngineBootstrap.js` as `Matter`. (Sources: `engine/matter/index.js`, `engine/EngineBootstrap.js`.)

## Automatic fidelity policy

`MatterFidelityGovernor` layers Matter policy over the shared `AdaptiveQualityGovernor` instead of replacing it. It consumes measured frame time, simulation time, VRAM pressure, error channels, visibility, time-to-impact, contact, fracture, phase, and selection flags. It returns revision-bound actions with finite packet, byte, simulation-time, and per-frame promotion budgets. (Source: `engine/matter/runtime/MatterFidelityGovernor.js`.)

The default Particle Storm, Matter Continuum reference-workbench, and SPH Fluid adaptive-Matter paths run in `auto` mode. Raw, Packet, Interactive, Bonded, and Hybrid controls in Particle Storm and Matter Continuum are inspection overrides. SPH Fluid exposes Auto, Uniform GPU PBF, Adaptive SPH, and Particle-Grid Hybrid controls through one fluid execution planner. Automatic selection remains the normal control authority and records the reason for each decision. An override cannot claim more physical work than the active budget permits. (Sources: `tests/playground/src/demos/particleStormCodecMode.js`, `tests/playground/src/demos/matterContinuum/model.js`, `tests/playground/src/demos/sphFluid/adaptiveMatterMode.js`.)

The policy never deletes canonical matter to meet a frame target. It can change representation, time bin, solver iterations, surface quality, secondary-detail quality, and presentation density. It applies hysteresis and cooldowns before spatial merges or splits.

The original high-count simulations keep their established authority. Particle Storm owns Storm motion, and the SPH Fluid GPU PBF lane owns the rendered water. Their Matter paths are bounded projections and differential probes; changing an automatic representation does not transfer ownership of those base simulations.

### Reading the live diagnostics

Particle Storm scopes every diagnostic explicitly. **Probe physical packets** counts the bounded Matter projection, while **Storm render samples** counts the separate high-count renderer. **Probe L3 equivalents** is conserved finest-level-equivalent coverage and includes the live packet-compression ratio; **probe domain volume** is the configured bounded region, not a measured Storm volume. **Session splits / merges** is operation history, not a descendant count. A current L0 packet with `7 / 7` therefore means that seven splits were later balanced by seven merges. The residual is the latest accepted conservation receipt and reads `NO RECEIPT` until one exists. The memory row separates estimated codec-store bytes, active/reserved overlay bytes, and active/allocated/maximum codec slots; none is total process RAM or total GPU memory. `AUTO → Raw Render` identifies the current automatic representation decision; it does not mean the codec history or canonical region ceased to exist. The overlay applies deterministic front-to-back screen-space decluttering and reports shown/hidden glyph counts. Its camera and actual canvas extent live in a dedicated 80-byte uniform, separate from the adaptively scaled Storm density target, and every glyph keeps a fixed 10-pixel presentation radius across FPS, density-bank, refinement-level, volume, and canvas-resize changes. This suppresses only overlapping diagnostic marks; it never deletes packets, skips physical work, or changes evidence. Storm's raw density renderer projects directly with the canvas-aspect MVP and does not reconstruct a per-fragment camera ray. Before decluttering, the packet overlay now rejects the same WebGPU clip-depth volume the GPU rejects (`0 <= z <= w`), so an invisible packet cannot reserve a screen bucket and suppress a visible one. (Source: `tests/playground/src/demos/particleStormCodecMode.js`.)

Particle Storm's automatic observer also takes a rotating, stratified sample of at most 64 live states from authoritative GPU ranges. It decodes the active 12-byte or 16-byte inertial layout through a nonblocking asynchronous readback ring, using the frame's caller-owned command encoder and sole queue submission. Particle Storm transactionally stages three 1 KiB buffers but starts with two active. Only a valid probe that finds both active slots occupied promotes the third slot for the rest of the session; if all three are occupied, the observer counts the deferral and retries without stalling or overwriting GPU work. This adaptive triple buffering applies only to bounded observer readback, not the authoritative multi-million-particle state, temporal history, or browser-owned canvas presentation. The readback ring is published only after nested validation and out-of-memory error scopes settle. A partial or rejected allocation destroys every staged buffer and disables only the optional observer with its exact reason; Storm and the codec remain available. Range extent, capacity, stride, and alignment are validated before any copy reaches the shared encoder, and asynchronous completions are accepted in generation order.

Each accepted sample becomes mass- and volume-conserved evidence proxies that cannot write Storm state or become canonical owners. One immutable normalized packet set, binned half-neighbor list, bond projection, and sparse field are built per evidence revision and shared by the Interactive, Bonded, and Hybrid observer views. Only the pointer forecast is refreshed each frame. Duplicate packet identities and neighbor-pair keys are processed once. The resolved physical adapters remain mutually exclusive: Interactive or Hybrid may run the bounded fluid adapter, Bonded may run XPBD, and observer consumers remain read-only. Sampling adapts to measured pressure at 8-, 30-, or 90-frame cadence, with a two-second wall-clock ceiling that keeps evidence inside its three-second freshness window even at a low frame rate. Diagnostics label unavailable work as `OFF`, warming work as `WAIT`, and generic never-measured work as `N/A`; the conservation field uses the more precise `NO RECEIPT`. (Sources: `tests/playground/src/demos/particleStorm.js`, `tests/playground/src/demos/particleStormLiveStateSampler.js`, `tests/playground/src/demos/particleStormCodecMode.js`.)

Particle Storm separates presentation quality from population capacity. State-First rendering continues to pursue 60 FPS and lowers deterministic render slots only to the exact 62.5% majority floor. After the 50-million calibration waypoint and that render floor, the population governor may use spare allocated slots toward a measured 30 FPS floor. It requires 60 stable headroom frames and two fresh GPU samples, grows by at most one 1/256 cohort per accepted window, holds between 30 and 35 ms, retires only after 60 frames above 35 ms, and uses a 12-frame emergency path above 40 ms. When timestamp queries are unavailable or become stale, frame time remains authoritative and growth requires a conservative 120-frame dwell instead of impossible GPU evidence. Every allocation, growth, demotion, or retirement resets the evidence dwell.

Density-bank calibration no longer deadlocks when the current bank reaches a stable hardware plateau below 50 million particles. After at least 180 mutation-free frames with fresh detailed GPU timing, stable presentation, no interaction or pending transition, and no available population-growth headroom, the governor freezes population only while it completes the 1/2/4/8 bank sweep. Locking a bank releases that hold and population qualification resumes. Raw timestamp boundaries must be finite, nonnegative, homogeneous, and monotonic before any cross-pass duration is subtracted; reset or inconsistent cohorts are discarded before they can reach the governor or tuner. Bank changes require at least a 0.1 ms absolute improvement so production timestamp quantization cannot cause churn.

The Adaptive Matter representation selector and its remaining physical-work budget use the same 30 FPS simulation budget, so an ordinary 25 ms high-population frame can retain Hybrid or Interactive work instead of independently cascading to Packet and Raw while the presentation governor is operating normally. Packet remains the bounded projection under sustained pressure, and Raw removes the optional projection only at the emergency boundary or after a codec failure; neither replaces the authoritative Storm renderer. Allocation failure and device loss remain hard ceilings because WebGPU does not expose a portable total-VRAM budget. (Sources: `tests/playground/src/demos/particleStorm.js`, `tests/playground/src/demos/particleStormTuning.js`, `tests/playground/src/demos/particleStormCodecMode.js`.)

SPH Fluid mounts both HUDs into one responsive vertical dock in either creation order. The Matter controls start collapsed. Destroying the panels removes their listeners, disconnects the dock observer, and retires the empty dock.

SPH Fluid's single execution plan includes the authoritative Uniform GPU lane and the bounded Matter projection. The existing render/quality controller supplies a measured GPU iteration request; the unified plan composes that request with representation, resource, and predictive-ray evidence and is the only value consumed by `simulation.encodeFrame()`. This keeps Uniform inside the same automatic system even when Matter exports or the optional projection are unavailable.

The live Uniform lane now implements one explicit simulation-backend contract. Its canonical range declares the `f32x4` position/velocity ABI, device generation, topology `sourceRevision`, presentation `representationRevision`, and an authority receipt. A telemetry sample ID never changes topology identity. Membership changes and resets advance `sourceRevision`; ordinary position and velocity updates do not. This prevents asynchronous readback cadence from repeatedly rebuilding adaptive topology. (Sources: `tests/playground/src/demos/sphFluid/simulationBackend.js`, `tests/playground/src/demos/sphFluid/liveStateSampler.js`.)

`AdaptiveSphGpuRuntime` is the persistent WebGPU execution lane for admitted mixed-resolution plans. It records density, pair-force, gather, and validation passes into the frame's caller-owned encoder, keeps its buffers resident, and reads only a 64-byte receipt through a bounded three-slot ring. `MixedResolutionFluidExecutionCertificate` binds each completed receipt to its exact plan digest, frame, source and target revisions, and device generation as an opaque one-use capability. Both contracts are `shadow-only`: they report `physicalAuthorityGranted: false`, never write the Uniform particle buffers, and cannot become the visible water authority. The SPH Fluid playground runs this shadow lane continuously beside Uniform and reports certified completions, pending receipts, and skipped backpressure samples in the Matter HUD. A full receipt ring skips optional shadow work without reporting a failed physical frame. A compile, allocation, validation, device-loss, or certificate failure disables only shadow evidence. (Sources: `engine/matter/fluid/AdaptiveSphGpuRuntime.js`, `engine/matter/fluid/MixedResolutionFluidExecutionCertificate.js`, `tests/playground/src/demos/sphFluid/adaptiveGpuShadow.js`, `tests/playground/src/demos/sphFluid/index.js`.)

Uniform performance samples come from the real GPU timestamp query for the full-water solve. An isolated round-robin shadow race restores private codec/system snapshots and samples only the Adaptive and Hybrid CPU projections. Their projected cost is added to the measured Uniform GPU baseline at the active time-bin cadence; it is not compared as though a 64-packet CPU sample could replace the full GPU simulation. CPU-only density and divergence observations remain labeled as projection evidence. Each candidate discards a settle sample, then contributes the same three-sample workload cohort. Selection compares medians, uses median absolute deviation to penalize volatility, and rejects unstable or more than 12% drifted workloads. The winner is held behind an 8% switching margin, 0.18-second confirmation, and 0.45-second minimum residency. Results are cached by adapter and workload only as provisional seeds, then measured again; a locked result is revalidated every 12 seconds. The quality governor's current solver-iteration request is also the execution-plan ceiling, so predictive assistance cannot silently restore an iteration that quality pressure removed. Shadow cadence expands from 0.18 to 0.75 seconds when a trial costs more. (Source: `tests/playground/src/demos/sphFluid/adaptiveMatterMode.js`.)

Allocator exhaustion, less than 8% headroom, or 1.5× frame pressure bypass normal dwell and immediately select the minimum Adaptive lane. A predicted proxy or domain impact within the 0.12-second horizon is also urgent: it bypasses normal dwell, wakes the live probe immediately, and pauses background challenger sampling until the contact window clears. A GPU timestamp sample is smoothed only when its sample ID advances.

Projection ownership has explicit tiers. Uniform and Particle-Grid Hybrid keep one canonical coarse projection owner, normal Adaptive SPH targets eight packets, and the bounded 64-packet tier requires an explicit Quality or Scientific profile. Auto can also admit the 64-packet tier after it reaches Scientific quality and repeated measured timing and allocator headroom admit the conservative projected work. Demotion is immediate; promotion requires 0.8 seconds of confirming evidence and residency. A hard resource demotion coarsens only complete compatible sibling octets, while split planning is independently clamped to the codec's live seven-slot capacity. These are differential packets, not the visible GPU PBF particle count. (Sources: `tests/playground/src/demos/sphFluid/index.js`, `tests/playground/src/demos/sphFluid/hudDock.js`, `tests/playground/src/demos/sphFluid/adaptiveMatterMode.js`.)

## Frame and GPU ownership

`MATTER_FRAME_STAGES` defines one deterministic order:

1. Validate device and source revisions.
2. Collect visibility, interaction, error, and timing evidence.
3. Produce the fidelity plan.
4. Apply bounded packet representation changes.
5. Build compact active work and the spatial index.
6. Run fluid, sparse-field, structural, phase, surface, and secondary-matter work.
7. Validate conservation, collect diagnostics, and prepare presentation.

The complete constant contains 17 named stages. A caller owns the `GPUCommandEncoder` and the only queue submission. A failed stage invalidates that frame encoder. (Source: `engine/matter/runtime/MatterRuntimeCoordinator.js`.)

`MatterDiagnostics.exportFrameReceipt()` exports an immutable versioned observation for one frame. It binds frame and device identity, authority boundaries, workload, admission, timing, quality, encoded-work evidence, and bounded errors to the current diagnostics snapshot. The receipt is observability-only and cannot grant simulation or presentation authority. Throwing diagnostic loggers are isolated from frame execution. (Source: `engine/matter/runtime/MatterRuntimeCoordinator.js`.)

`MatterGpuPacketArena` uses generation-checked handles, active bitsets, stable compaction, indirect dispatch, and explicit capacity failure. `GpuMatterSpatialIndex` performs a stable full-`u32` radix sort, counts valid cells, scans cell offsets, and reports invalid keys. Both accept caller-owned encoders and support two-phase device recreation. (Sources: `engine/matter/runtime/MatterGpuPacketArena.js`, `engine/matter/runtime/GpuMatterSpatialIndex.js`.)

`GpuBoundedU32FrontierQueue` is a reusable finite worklist primitive for future breadth-first, crack-front, and refinement kernels. Producers write deterministic candidate slots; a hierarchical scan stably compacts the selected slots into alternating frontier buffers. GPU metadata reports accepted, attempted, and overflow counts, status bits, and an indirect-dispatch tuple. Overflow truncates that round at the declared capacity; the queue does not retain or replay rejected candidates. A consumer must treat overflow as actionable backpressure and repopulate or retry from its canonical source under its own policy. Reset and device recreation also return an empty frontier. The primitive records into a caller-owned encoder and does not submit work. Each encode receipt holds finite workspace until the caller retires it after submitted work completes, and stale device generations are rejected. It is execution infrastructure, not evidence that a physical solver currently uses it. (Source: `engine/core/gpu/GpuBoundedFrontierQueue.js`.)

The Matter Continuum reference workbench uses those primitives through a bounded GPU mirror of the codec's canonical packet projection. The mirror deterministically reconciles lineage handles, records arena maintenance and spatial-index work into the renderer's caller-owned encoder, and retires temporary receipts only after that single submission completes. The CPU model and renderer remain authoritative; mirror initialization, capacity, encoding, or completion failure disables the mirror without changing canonical matter. This demo facade deliberately advertises no device-recreation support, so a new facade must be created by its owner after any device replacement. (Source: `tests/playground/src/demos/matterContinuum/gpuRuntime.js`.)

## Adaptive fluid

The adaptive SPH path uses a symmetric smoothing radius for mixed-resolution pairs. Its CPU reference broad phase places packets in a uniform cell-linked list whose cell size is the largest smoothing radius, then searches each packet's 27-cell neighborhood. Candidate indices are sorted and streamed immediately into exact distance tests, preserving deterministic pair order without materializing a global candidate-object array. Radius and neighbor maxima use iterative reductions so caller-approved large sparse populations do not hit JavaScript argument limits.

The analysis stores every exact interacting pair, distance, smoothing radius, and kernel gradient. The force pass reuses that trusted analysis after strict packet, quality-profile, and kernel validation instead of rebuilding the neighbor set. Candidate pruning changes only the broad phase; the symmetric pair forces and conservation receipt remain authoritative. Diagnostics separate candidate pairs from interacting pairs and report whether the analysis was reused.

Analysis also classifies bulk, near-surface, surface, spray, droplet, bubble, and boundary-contact packets. Refinement plans apply score, residency, hysteresis, and capacity checks before they call the packet codec. Transition shells provide support only and own zero canonical mass. (Sources: `engine/matter/fluid/AdaptiveSphReference.js`, `engine/matter/fluid/AdaptiveMatterFluidSystem.js`, `engine/matter/fluid/AdaptiveSphRefinementController.js`.)

`traceAdaptiveFluidProxyRays()` casts a deterministic six-axis ray fan for each canonical packet. Rays use the packet radius and the engine's `MathRay` AABB intersection against the fluid domain. A caller can also supply a function or an existing scene-query object with the `sweepSphere()` interface used by `GPUSceneQuery`. A nearer engine-proxy sweep replaces the domain hit, while a provider error is counted and falls back to the domain result.

The field writes nearest-distance and time-to-impact evidence for refinement and scheduling only. It does not replace SPH neighborhood forces or create a second physics authority. (Sources: `engine/matter/fluid/AdaptiveFluidProxyRayField.js`, `engine/core/math/MathRay.js`, `engine/sim/physics/gpu/GPUSceneQuery.js`.)

`SparseFluidBrickGrid` allocates only occupied finite bricks. Scatter preserves canonical packet ownership, the pressure/divergence solve operates on grid state, and gather returns a revision-checked packet projection. `LocalFluidSurfaceCache` builds bounded narrow-band signed-distance tiles from packets and analytic boundaries. Both reject stale source or representation revisions. (Sources: `engine/matter/fluid/SparseFluidBrickGrid.js`, `engine/matter/fluid/LocalFluidSurfaceCache.js`.)

`AdaptiveMatterFluidSystem` composes these pieces. Each solved frame commits packet kinematics atomically into the codec, and motion invalidates same-revision packet surface tiles before they can be reused. The current adaptive solver and sparse grid are deterministic CPU reference paths. The GPU packet arena, scan, sort, compaction, and spatial-index primitives provide the bounded GPU execution substrate; the reference path remains the differential oracle. (Sources: `engine/matter/fluid/AdaptiveMatterFluidSystem.js`, `engine/matter/fluid/LocalFluidSurfaceCache.js`.)

The SPH Fluid playground uses one automatic plan for the existing high-count GPU PBF authority and a conserved one-cubic-metre Matter projection. The plan consumes smoothed frame timing, fresh-ID GPU simulation timing, allocator headroom, interaction, membrane pressure and strain, prior projection density error, and the proxy-ray field. Its adaptive quality logic samples measured projection cost and resource pressure, while private shadow snapshots ensure challenger steps cannot advance or alter live projection state.

The GPU PBF broad phase combines its original dense chamber grid with a signed-cell hash for particles that leave that grid through the vent. Both indexes share one packed storage buffer: `C` dense IDs, `C` hash links, three `C`-entry immutable signed build-cell coordinates, `C` ownership flags, and a power-of-two hash-head table `B`, for `(6C + B) * 4` bytes. Packing keeps the solve inside the portable eight-storage-buffer-per-stage budget. Exact build-cell comparison rejects hash collisions. Dense origins query the dense index plus hash entries owned outside at build time; escaped origins query the hash plus dense entries that were not hash-owned at build time. This seam rule provides symmetric lambda, position-correction, and XSPH neighborhoods without evaluating the same pair through both indexes. (Sources: `tests/playground/src/demos/sphFluid/simulation.js`, `tests/playground/src/demos/sphFluid/shaders.js`.)

SPH surface billboards and fragment camera rays use the same canvas-camera aspect carried in the view uniform. The independently rounded offscreen target ratio no longer participates in ray reconstruction, preventing a fragment ray from missing the particle whose billboard produced it and creating false holes or edge culls. Particle Storm does not share this reconstruction path; its direct-MVP overlay correction is described above. (Sources: `tests/playground/src/demos/sphFluid/renderer.js`, `tests/playground/src/demos/sphFluid/shaders.js`.)

The CPU probe uses automatic multirate time bins. Performance advances every four nominal render steps, Balanced every two, and Quality or Scientific every step. Quiet render frames accumulate simulation delta without running neighbor analysis.

When the bin matures, or interaction, a mode change, emergency refinement, or an imminent ray impact wakes it, the probe consumes at most 0.1 seconds of accumulated time. It divides that time into no more than three substeps, each at most 1/30 second. Excess catch-up time is dropped and reported. This reduces repeated CPU neighbor work while keeping the simulated time explicit instead of silently slowing the probe. (Source: `tests/playground/src/demos/sphFluid/adaptiveMatterMode.js`.)

Missing Matter exports or a projection runtime failure disable only that projection. The same immutable execution-plan schema continues to govern the Uniform GPU authority, and a runtime failure is latched so the frame loop does not retry or log it continuously.

Near a predicted impact, the unified plan can raise the GPU authority's PBF iterations to the model's configured density-iteration count. The boost applies only below 1.1× measured pressure, with at least 10% allocator headroom when that measurement exists, and while allocation remains available. Fixed physics-quality selections also feed both the projection quality and the GPU plan. Resource pressure prevents predictive precision from adding work.

A failed shadow trial is reported in race diagnostics but does not disable the live projection or GPU authority. The HUD reports the physical authority, selected projection, Uniform GPU samples, CPU live/shadow samples, final GPU iteration plan, packet tier, neighbor candidates/interactions, time bin, proxy rays, and analysis reuse separately. This integration does not make the CPU projection the owner of GPU water. (Sources: `tests/playground/src/demos/sphFluid/index.js`, `tests/playground/src/demos/sphFluid/adaptiveMatterMode.js`.)

The HUD also reports the adaptive GPU shadow lane separately from the CPU challenger race. A completed adaptive GPU receipt certifies bounded operator execution only. It is not a physical handoff or a claim that the projected carriers replaced the canonical PBF state.

## Bond Fabric and fracture

`StructuralTopology` stores nodes, active bonds, persistent crack residuals, and derived rigid aggregates. `XpbdStructuralSolver` evaluates tension, compression, shear, and bend with material-specific compliance, yield, plasticity, fatigue, damage, recovery, thermal softening, and fracture thresholds. (Sources: `engine/matter/structural/StructuralTopology.js`, `engine/matter/structural/XpbdBondSolver.js`.)

Fracture calls `fractureBond()`. That method deletes the active edge and creates a durable crack record. Connected-component rebuilding therefore changes the force-transmission graph instead of adding only a visual crack. Predictive hooks can request local refinement before impact or ahead of a crack front.

`RigidAggregateBackendHandoff` projects each eligible connected component into an injected rigid-body backend through its existing `createBody`, `getBody`, and `removeBody` operations. The fine structural topology remains canonical. Each backend binding retains aggregate, node, source-bond, and crack identities plus conserved mass. The body starts at the aggregate center of mass with its linear and angular motion. Its collider is a minimum-thickness box around the node AABB, not a convex reconstruction. Motion collection rotates the stored node offsets and returns broad linear and angular motion to the fine nodes before refinement or fracture resumes them. The handoff does not synthesize replacement fine bonds. Synchronization stages replacement bodies and removes every staged body if creation fails; predictive impact releases overlapping proxies, and device recreation rebuilds them from the preserved topology. (Source: `engine/matter/structural/RigidAggregateBackendHandoff.js`.)

The starter structural catalog provides rubber, glass, steel, wood, ice, and soft-tissue profiles. These are engine profiles, not standards-grade material certificates. (Source: `engine/matter/structural/StructuralMaterialProfiles.js`.)

## Atomic phase transcoding

A [phase transcode](../getting-started/glossary.md#matter) changes a region between declared states in one phase family. Water supports ice, slush, liquid water, and steam. Metal supports solid, plastic, and melt. Soil-water supports soil and mud. Every edge declares temperature bounds, allowed reservoir deltas, and a structural policy of preserve, weaken, or delete. (Source: `engine/matter/transcoding/PhaseFamilyProfiles.js`.)

`AtomicPhaseTranscoder` validates and journals a request before it mutates structural or phase state. Commit is idempotent. Interrupted structural work rolls back. Recovery either finishes a valid transaction once or aborts a stale transaction. Snapshots retain the journal for save/reload. (Source: `engine/matter/transcoding/AtomicPhaseTranscoder.js`.)

`MatterPhaseRuntimeCoordinator` closes the representation-migration boundary for one region. It commits the structural phase policy, rebinds the exact codec packet set while retaining handles, lineage, definition, mass, momentum, and stored elastic detail, reconciles only the declared thermal-energy delta, and then activates or deactivates region-scoped fluid authority. Source and representation revisions advance once. A failed or interrupted stage restores every participant to the prepared snapshot, and the pending transaction can survive save/load before deterministic recovery. Codec packets carry the exact phase-family ID, such as `phase.water.ice` or `phase.water.steam`; they do not carry a coarse Fabric fraction token such as `solid` or `gas`. (Sources: `engine/matter/transcoding/MatterPhaseRuntimeCoordinator.js`, `engine/matter/codec/AdaptiveMatterPacketCodec.js`.)

## Realm Matter Fabric

The Realm Matter Fabric keeps scientific meaning separate from numerical representation. Its registry stores canonical definitions and aliases. Property observations retain units, conditions, uncertainty, method, evidence class, and conflicting sources. The transformation hypergraph performs bounded forward, reverse, and substitution searches. (Sources: `engine/matter/fabric/RealmMatterRegistry.js`, `engine/matter/fabric/RealmPropertyResolver.js`, `engine/matter/fabric/RealmTransformationGraph.js`.)

`RealmConservationValidator` checks mass, constituent coverage, elemental and isotopic amounts, charge, and explicit environmental reservoirs. `RealmProcessPlanner` turns bounded hypergraph routes into immutable, scaled work plans that retain conditions, equipment, reservoirs, byproducts, evidence, and estimated cost. `RealmMatterLedger` protects instance and Soul Seed identity with hash-bound deltas. Domain packs compile offline into deterministic dictionary-coded bytes and reject runtime network loading. (Sources: `engine/matter/fabric/RealmConservationValidator.js`, `engine/matter/fabric/RealmProcessPlanner.js`, `engine/matter/fabric/RealmMatterLedger.js`, `engine/matter/fabric/RealmMatterPack.js`.)

`RealmPacketRuntimeBridge` keeps composition, phase fractions, temperature, pressure, processing history, reaction progress, and charge in a bounded sparse sidecar while the packet codec remains authoritative for packet identity, phase-family ID, damage, mass, volume, motion, and energy. It rejects definition-incompatible composition, phase-envelope and microstructure mismatches, stale revisions, history rewrites, reaction regressions, unregistered or composition-unrelated transformations, and quantity or damage drift. Split and merge changes are reconciled by lineage. A phase change requires a Fabric phase profile explicitly declared for the same composition family; the bridge never infers that a generic `solid` fraction means ice. It refreshes only after the transactional phase coordinator has committed the codec rebind. The refreshed sidecar state must carry the packet source revision. Save records hash both every live projection and the complete binding set, so changed or removed bindings fail atomically on restore. (Source: `engine/matter/fabric/RealmMatterBridges.js`.)

The starter pack includes common elements, dry air, water phases, steel, glass, wood, concrete, quartz, sand, loam, mud, polyethylene, copper, fuel, stock forms, debris, recycling, manufacturing, soil hydration/drying, and combustion topology. Its numeric ranges are curated demonstrator data. They are not a replacement for an authoritative scientific database. (Source: `engine/matter/fabric/StarterMatterPack.js`.)

## Live impact and water storyboard

Open **Matter Continuum · Matter Journey** in the Playground and select **Launch & follow**. The default experiment advances one persistent native PhysX PE world at 1/240 s. Actual contact impulses feed `BlastScene.applyContacts`; native Blast graph splits create independent compound bodies. Gravity and collisions determine their subsequent motion. The mixed panel releases completely on launch; the legacy brittle/tough panels retain their anchored top row. Changing the panel-strength preset changes bond health, not a scripted fracture time. (Sources: `tests/playground/src/demos/matterContinuum/liveModel.js`, `engine/sim/destruction/BlastScene.js`.)

The treatment experiment starts with 1800 conserved water volumes (8843.4 kg, about 8843 litres). Fill presets range from 720 to 2880 volumes (3537–14149 litres); custom positive whole-number row counts can exceed those presets when the GPU admits the allocation. Reservoir walls, impact panel, density-volume extent and camera framing rise with the selected fill; disabling treatment restores the 360-volume impact tank. The default live lane owns its parcel state in persistent WebGPU storage buffers. GPU passes build spatial neighbor lists, compute SPH density and symmetric pressure/viscosity forces, integrate motion, resolve fluid contacts, and advance spatial enthalpy and electrolysis. The kernels are shared with `AdaptiveSphGpuExecutor`; the thermal shader functions come directly from Thermal Snow Globe. Acoustic/advection substeps preserve the native 1/240 s clock. The SPH smoothing radius is fixed; the phase-change carrier split is not adaptive fluid refinement or the SPH playground's PBF solver. (Sources: `tests/playground/src/demos/matterContinuum/gpuSimulation.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`.)

PhysX PE and Blast remain native WASM. Each native step uploads collider poses and velocities, then receives the GPU-computed body velocity changes. Parcel readback supplies measurements and recording, never a CPU fluid step. Static contacts execute per parcel; dynamic contact impulses retain ordered updates of shared native-body velocities. This bounded bridge synchronizes once per native step. Requested and measured rates can differ, particularly at high fill. The CPU implementation remains an explicit test reference when `createLiveMatterModel` is called without a device; the Playground supplies its WebGPU device and does not silently fall back.

Ordered solver dispatches use batches of at most 32 acoustic/advection substeps, awaiting each batch before submitting the next. Batching bounds each submission's work without truncating substeps or changing the native physical timestep. Contact receipts, thermal totals, parcel heating/collection and gas diagnostics use 64-thread workgroups and reductions. Parallel contact-candidate bitsets exclude parcels that cannot touch a dynamic collider; shared body-velocity updates still visit candidates in their original parcel order. A parallel reduction selects the first electrode-reaction candidate with the original score and index tie-break. Charge allocation, daughter creation and subsequent candidates retain their ordered owner. Gas-source deposition normalizes each parcel's bounded support, then lets grid cells gather nearby sources through the existing spatial buckets. Electrode expansion keeps its separate source positions and wall-occlusion checks. This removes serial accumulation without requiring floating-point atomics. The pressure iteration count remains unchanged; parallel reductions can change floating-point rounding. (Sources: `tests/playground/src/demos/matterContinuum/gpuSimulation.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/gasPressure.js`.)

The CPU bridge classifies water, gas and recording parcels in one traversal and reuses the completed step's thermal summary for subsequent reads. Control changes invalidate that summary; recordings copy its nested measurements so later steps cannot mutate older frames. The liquid density texture is rebuilt only after a completed solver step, so orbiting or drawing a paused world reuses it. These changes reduce specific work and submission overhead; they do not guarantee a fixed frame-rate or throughput multiplier. (Sources: `tests/playground/src/demos/matterContinuum/liveModel.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`.)

The GPU contact pass and its CPU reference `coupleFluidRigidContacts` project fluid volumes out of native sphere/box shapes and exchanges dissipative normal impulses with the bodies. Effective mass includes body inertia, and off-center contacts change angular velocity. Static-support reactions are accounted separately. This is coarse contact coupling, not a complete hydrodynamic boundary-density or pressure-integration method. No Flow gas simulation is claimed. (Source: `engine/matter/fluid/PhysXFluidContactCoupling.js`.)

The **Storyboard** mode pauses on measured impact, topology splitting, water contact and rising-water events. **Continuous** mode advances the same world without those pauses. After six seconds, treatment mode offers the filter gate; impact-only mode ends observation. Neither transition forces settling or fracture. Unobserved events never appear as completed stages. The slider and event buttons inspect recorded solver states; returning to live resumes the retained world at its latest state. Export downloads the recording and measurements, not a serialized native-world checkpoint. (Source: `tests/playground/src/demos/matterContinuum/liveExperiment.js`.)

WebGPU reconstructs and raymarches a filtered 3D density volume directly from resident live water state. Recorded replay reconstructs the same presentation from saved samples without advancing the live solver. Surface gradients, perspective depth, Fresnel reflection and directional lighting make the water and immersed fragments readable. This is a coarse particle-derived isosurface, not an additional fluid solver or a claim of volume-exact optical reconstruction. The particle checkbox exposes the underlying samples. Fragment meshes use full native quaternions; the tank uses the Playground's shared geometry and matrix helpers. Drag the scene to orbit, scroll to zoom, or focus it and use arrow keys and plus/minus. **Front view** and **3D view** restore useful camera positions. Requested and measured simulation rates are separate because a busy browser may advance more slowly while preserving the fixed timestep. (Sources: `tests/playground/src/demos/matterContinuum/liveRenderer.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

Gas presentation also reads resident parcels directly. Six-vertex soft sprites replace CPU-built gas spheres. The renderer uses Thermal Snow Globe's shared enthalpy-to-phase functions: latent heating reveals bubble markers as the water's vapor fraction grows, white tracers identify mobile water vapor, and cooling steam becomes blue condensate droplets. White vapor tracers explain transport; they do not claim that gaseous water is visible or resolve the droplet scattering of a steam cloud. Cold water produces no steam markers; a confirmed zero-vapor, zero-product, zero-condensate snapshot with no gas in transit skips those draws entirely. Partial vapor and cooling condensate remain visible. (Sources: `tests/playground/src/demos/matterContinuum/gasRenderer.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`.)

Parcel mass, phase and measured velocity control the displayed size, opacity and stretching; sprite centers remain at the parcel positions. Gas-marker radius follows an equivalent sphere of ideal-gas volume at ambient pressure, bounded to 0.045–0.28 m for presentation. Condensed droplets instead use their liquid-water volume. These are explanatory visual kernels, not resolved bubble surfaces or a volumetric optical model. Recorded playback uploads its saved parcel values to the same renderer without advancing physics; its liquid density reconstruction also weights each sample by remaining mass. Collected gas disappears from the transit display and remains in its inventory. (Sources: `tests/playground/src/demos/matterContinuum/gasRenderer.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`.)

Enable **Particles + gas flow** to inspect liquid samples and the live pressure grid. Sparse arrows sample the actual staggered gas velocities; their direction, length and phase animation derive from those samples. Blue indicates negative gauge pressure relative to ambient, orange positive gauge pressure, and neutral color pressure near ambient. These glyphs annotate the depth-averaged field, not additional gas particles or absolute pressure measurements. Their animation uses physical simulation time and stops when the world pauses. Recorded parcel playback does not fabricate a pressure field that was not saved. (Sources: `tests/playground/src/demos/matterContinuum/gasRenderer.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

Diagnostic liquid samples use a single 216-vertex sphere mesh instanced from the resident parcel buffer. Each active liquid carrier, including condensed steam carriers, keeps its own position and mass-scaled radius; real sphere geometry writes depth. The same path accepts recorded parcel snapshots and process-disabled impact recordings. No particle count is capped for presentation. Equipment geometry has a separate buffer that grows geometrically up to the device limit, so adding liquid carriers no longer expands the CPU equipment mesh. (Sources: `tests/playground/src/demos/matterContinuum/gasRenderer.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`.)

### Bricks, screening and water treatment

The default panel has 36 smaller bricks in three independently bonded strips: ceramic (2300 kg/m³), wood (600 kg/m³) and steel (7850 kg/m³). Each strip is a separate native Blast family with its own density and illustrative bond strength. There are no permanent pins on the mixed panel and no cross-material bonds. Measured projectile contact supplies a distance-attenuated native Blast damage pulse across the adjacent material families. It does not prescribe fragment velocities. The default projectile is 450 kg at 30 m/s (202.5 kJ), versus the earlier 45 kg at 10 m/s (2.25 kJ); controls support 45–1000 kg and 3–50 m/s through the model. This preserves the scene bridge’s homogeneous-density inertia contract. The old brittle and tough presets remain available. (Source: `tests/playground/src/demos/matterContinuum/liveModel.js`.)

All stages occupy one persistent vertical apparatus: impact reservoir, horizontal screen, sloped collector/downpipe, boiler/condenser, then lower electrolysis and gas collection. Opening the reservoir floor lets gravity draw water through native collision bars and down the collector slopes. Both rigid bodies and SPH use those same rotated collider poses. Fine and coarse openings measure 22 cm and 48 cm; **No screen** provides a control. The lower-water and passed-solid counters report actual positions below the filter. These are coarse debris screens, not micron filters, and they do not remove dissolved substances.

The treatment reservoir defaults to 20 rows, about 8,843 L. **Water fill → Custom…** accepts a positive whole number of rows instead of limiting fill to the presets. Each row adds 90 parcels at 0.17 m spacing, representing 442.17 L at the configured water density. The UI previews litres and applies the fill on **Reset experiment**. Admission checks the GPU's storage and dispatch limits before constructing the larger scene; unsupported allocations fail explicitly. (Sources: `tests/playground/src/demos/matterContinuum/liveUi.js`, `tests/playground/src/demos/matterContinuum/liveModel.js`, `tests/playground/src/demos/matterContinuum/gpuSimulation.js`.)

One canonical parcel inventory spans the entire apparatus. No sample is removed into an independent batch. The boiler feed valve closes above 650 kg of liquid and reopens below 450 kg, within a 1000 kg working capacity. Steam does not count toward liquid-level control. A raised steam takeoff, downward feed deflector and offset solid baffles reduce liquid carryover. Both phases collide with these baffles; separation depends on their resolved collision size and inertia, not a phase-selective switch. Native rigid contacts, parcel contacts and visible plumbing all use `waterProcessWalls()`. **Whole rig** shows the stack; **Impact layer**, **Filter layer**, and **Treatment layers** inspect regions of the same running world. **Follow stage** frames the filter when the reservoir floor opens, then focuses the treatment apparatus after the heater has deposited energy. **Inspect boiler & steam** directly selects that treatment view. **Condenser close-up** centers the exchanger and outlet with a narrower camera frame so physically small condensate droplets can be inspected. (Sources: `tests/playground/src/demos/matterContinuum/liveModel.js`, `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

The SPH playground's canonical-state/render separation and Thermal Snow Globe's persistent-parcel design provide the ownership model. `waterProcess.js` directly reuses the Snow Globe's specific-enthalpy and phase functions. The Playground starts with **200 MW constant** for both warming and boiling. Presets also include **20 MW constant**, **1,000 W · comparison**, **200 kW constant** and **2 MW constant**, while **Custom…** accepts a positive power in watts. The model API retains its 200 kW default. This apparatus heats hundreds of kilograms rather than a kettle-sized fill, so 1,000 W is a deliberately slow comparison. (Sources: `tests/playground/src/demos/matterContinuum/liveExperiment.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`, `tests/playground/src/demos/matterContinuum/liveModel.js`, `tests/playground/src/demos/matterContinuum/waterProcess.js`.)

The heater allocates the selected power between warming and boiling according to eligible water mass. Warming stops at the lower of 100 °C and the surface setpoint; latent heating uses the same selected power without a hidden 2 MW ceiling. With only boiling water eligible, the full selected rating is available for vaporization. The API still accepts an explicit boiling-power override for controlled comparisons; the UI labels a different boiling setting when it encounters one in a live state or recording. Heating off or no eligible mass gives zero commanded power, and deposited energy cannot exceed the requested power multiplied by the physical timestep. (Sources: `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`.)

The **Boiler · Heat** controls separate heater wattage, heater surface setpoint and actual water temperature. The surface setpoint defaults to 200 °C and accepts values at or above 25 °C; this source heats water and does not model refrigeration. Neither power nor temperature has a preset upper ceiling; values must remain finite and representable in the GPU calculation. It limits an ideal power source, not a calibrated heating element: a setpoint at or below 100 °C caps sensible heating at that temperature; above 100 °C it permits latent heating through saturated steam. Raising it from 200 °C to 300 °C does not multiply power, change atmospheric boiling temperature or simulate superheated liquid. Heat-transfer area, element heat capacity and temperature-dependent conductance are not modeled. **Condenser · Cooling** and **Electrolyzer · H₂ + O₂** are separate control groups; cell voltage operates the electrodes, not the boiler heater. (Sources: `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

The controls change physical heater power; they do not speed up thermal time. **Active heater setting** reports the command on the last physical substep, separately from selected power. **Heat received · last step** reports the actual increase in the `heatJ` ledger divided by that physical step duration; it can be lower than the command when water reaches a phase endpoint. Cumulative received energy is also shown in joules. Changing controls while paused preserves those historical measurements. GPU enthalpy updates carry rounding remainders between steps so small heat increments do not repeatedly disappear or grow through float32 rounding. The condenser has a separate 300 MW maximum cooling rating. Heater, cooler and electric switches independently stop their inputs. (Sources: `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

Motion, thermal transfer and electrode charge use the same physical timestep. **Simulation speed** requests ¼× through 600× for the whole world and recorded playback; the measured rate reports actual solver throughput. There is no independent heat or charge multiplier, and the browser cannot promise 600× throughput. For a fixed 650 kg batch receiving the full rated power, heating from 25 °C to 100 °C takes about 56.7 simulated hours at 1,000 W, 17 minutes at 200 kW, 10.2 seconds at 20 MW or 1.02 seconds at 200 MW. Vaporizing that batch requires a further 122 minutes at 200 kW, 12.2 minutes at 2 MW, 73.3 seconds at 20 MW or 7.33 seconds at 200 MW. These estimates isolate the two stages; the controller, flowing feed and changing boiler inventory alter actual times. Vaporization and condensation include the atmospheric 100 °C latent plateau. A condensing carrier becomes liquid once its latent heat has been removed at 100 °C; cooling that liquid to the 25 °C drain setpoint is a separate sensible-heat stage. (Sources: `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/thermal/model.js`, `tests/playground/src/demos/thermal/shaders.js`.)

The condenser is a water-cooled heat sink represented by a lumped fin-bank exchanger: 1 °C chilled-water inlet, 4,000 kg/s coolant and a 300 MW maximum cooling rating. Its modeled total fin/tube area is 25,000 m², with a 0.8 effective-area factor and an overall heat-transfer coefficient of 1,500 W/(m²·K). Their product gives 30 MW/K conductance (`UA`). These are explicit industrial-bank parameters, not properties inferred from the small on-screen geometry or a calibrated physical product. Fin conduction, individual coolant channels and chiller machinery are not resolved. (Sources: `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/waterProcess.js`.)

For coolant heat-capacity rate `C`, effective conductance is `C × (1 − exp(−UA/C))`. Cooling power is the minimum of the 300 MW rating, coolant capacity up to its 25 °C permitted return and effective conductance times the process/coolant temperature difference. The finite-UA bound is about 334 MW at a 25 °C process temperature before applying the 300 MW rating. Actual removal is also capped by eligible parcel enthalpy. A full 300 MW transfer would raise this coolant supply from 1 °C to about 18.9 °C; the UI derives the actual modeled return from the cooling ledger. It separately reports measured cooling duty, hot inventory still cooling and cooled water ready to drain. These are aggregate exchanger measurements, not resolved coolant particles or an additional conserved water inventory. (Sources: `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

The visible finned tube bank connects a cold inlet below the coolant return, opposite the descending process stream. Cylindrical pipes and thin fins show the heat-sink arrangement; their compact drawing is schematic and does not represent the industrial bank's physical dimensions. The return pipe color follows the modeled coolant temperature rise without inventing moving coolant parcels. The controlled drain retains vapor and liquid hotter than 25 °C; eligible cooled liquid can drain even if cooling is switched off. Swept parcel contacts prevent crossing the closed outlet, and the MAC grid closes gas flux and pressure coupling across the same drain face. Its valve behavior is an explicit ideal boundary condition, not mechanical valve CFD. The UI separates hot inventory still cooling from cooled inventory ready to drain, and reports any hot material found below the drain. **Liquid below outlet** reports the current remaining condensed water below the drain; **In drain pipe** is its subset in the vertical pipe. These are present inventories, not cumulative flow meters. The coolant inlet label reads the actual recorded or live setting, with the shared equipment setting as fallback. White vapor tracers and blue droplets continue to derive from parcel phase. Large vapor markers retained above the drain are clipped at its plane so their soft edges do not depict leakage; an actual carrier below the plane remains visible. (Sources: `tests/playground/src/demos/matterContinuum/processGeometry.js`, `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/gasPressure.js`, `tests/playground/src/demos/matterContinuum/gasRenderer.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

The condenser sump has two solid sides that slope down 0.25 m toward the central outlet. Gravity and contact forces guide cooled condensate, including the 20 g liquid carriers, into the downpipe instead of leaving it on a level ledge. These slopes are part of `waterProcessWalls()`, shared by visible plumbing, native contacts, parcel collisions and gas boundaries. Drainage follows the moving parcel state; the geometry does not transfer water directly to the cell or alter its mass and enthalpy. (Sources: `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/liveModel.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`.)

Closing a gas outlet does not turn the reduced low-Mach solver into a pressure-vessel model. Gas density and water phase thresholds still use atmospheric thermodynamics; pressure projection supplies a transport field, not a compressible equation of state. A sealed region with unmatched phase-volume sources can retain projection residuals, which remain exposed in the measurements. The demo does not predict sealed-vessel pressure rise, pressure-dependent boiling or relief-valve operation. (Sources: `tests/playground/src/demos/matterContinuum/gasPressure.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/thermal/shaders.js`.)

The independent heater and cooler ratings matter: with this model's water constants, 2 MW of latent boiling produces about 0.886 kg/s of vapor and requires about 2.28 MW to condense that stream and cool it from 100 °C to 25 °C. At 200 MW the corresponding duties are approximately 88.6 kg/s and 228 MW. The 300 MW bank has a higher nominal rating than the approximately 228 MW duty, while actual throughput still depends on steam reaching it, residence time and stored inventory. The UI shows this full-boil sizing estimate separately from measured cooling. Larger custom heater settings can exceed the bank rating; the controls identify that mismatch without automatically lowering the heater. Vapor inventory grows whenever evaporation exceeds actual condensation. [BÜCHI's distillation explanation](https://www.buchi.com/en/knowledge/technologies/rotary-evaporation) describes latent-heat removal and the need to balance evaporation with condensation. [Alfa Laval's exchanger explanation](https://energy.alfalaval.com/alfa-laval-steam-heater-gasketed) shows opposing steam and coolant routes. [Spirax Sarco's condensate guidance](https://www.spiraxsarco.com/learn-about-steam/condensate-recovery/layout-of-condensate-return-lines?sc_lang=en-GB) explains subcooled discharge and why retaining condensate can impair a real exchanger. The demo's controlled outlet is a reduced model, not a validated trap selection or installation design.

The GPU separates approximately 20 g saturated-steam carriers once the parent has supplied their sensible and latent energy. Each carrier inherits the parent's position, velocity and source lineage; its mass and enthalpy are deducted from that parent. This lets vapor leave while a coarse water parcel is still boiling. Separation does not inject phase expansion into the pressure grid twice. Liquid surface density uses the remaining parcel mass, and small condensed carriers retain a droplet marker when they are too small to make an independent isosurface. (Sources: `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/gpuSimulation.js`, `tests/playground/src/demos/matterContinuum/gasRenderer.js`, `tests/playground/src/demos/matterContinuum/liveRenderer.js`.)

Steam storage grows on demand instead of stopping carrier creation at 1,024 slots. Before advancing GPU parcels, the runtime reserves enough slots for their possible steam release, expands capacity geometrically when useful, and copies parcel history, gas-grid state and enthalpy carry into the new buffers. Existing carriers retain their identity after condensation or reaction. **Measurements & implementation** reports used and currently allocated slots; those counts describe storage, not a boiling limit. The enabled WebGPU device still imposes real buffer, binding and dispatch limits. An unsupported or failed allocation reports an error before the GPU parcel advance and preserves the prior GPU buffers; it does not silently discard mass or reduce heater power. PhysX has already advanced at that point, so this is not a rollback of the entire world. **Vapor-equivalent mass** includes partial vapor paid for inside liquid parcels, while **Moving steam** counts actual mobile water-vapor carriers and their carried mass; cooling carriers can contain partially condensed water. Steam forming in the boiler, crossing the header and reaching the condenser are separate observed milestones. (Sources: `tests/playground/src/demos/matterContinuum/gpuSimulation.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/liveModel.js`, `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

Steam stays in the same GPU parcel inventory. A 104 × 90 staggered MAC grid at 5 cm spacing computes depth-averaged gas flow: semi-Lagrangian advection, buoyancy, phase-volume sources, solid-wall constraints and pressure projection. The divergence and pressure-gradient stencils match; before/after divergence residuals are exposed in measurements. Gas carriers gather solved MAC velocities over the same normalized 7 × 7 cell neighborhood and 0.18 m support used to deposit their represented gas cloud. Solid walls and the closed condensate outlet exclude blocked samples. This aligns carrier motion with the surrounding cloud near walls, where sampling only the carrier center could leave oxygen stationary inside local recirculation. Grid advection retains its MAC interpolation; the carrier gather changes no collision radius and adds no force or direct transport. Outside the bounded treatment grid, gas retains momentum with ambient buoyancy and drag. Native rigid contacts, gas boundaries and rendering use the same walls. Separate collection extractors impose −50 Pa gauge only inside the physical collector walls, using the same `PROCESS_GAS_PORTS` dimensions as the risers. Their pressure boundaries leave the exterior gas path unaffected; collected species enter the separate atmospheric holders. This external pressure boundary supplies mechanical work; it is not part of the cell-only electrical/chemical energy ledger. Carrier air and gas purity are not tracked. There is no destination-attraction force. This is a reduced low-Mach transport model, not NVIDIA Flow, compressible multiphase CFD, a bubble-interface solver or a gas-purity calculation. The CPU reference covers SPH, contacts and thermal/chemical operators; its local gas buoyancy is not an equivalent pressure-grid implementation. (Sources: `tests/playground/src/demos/matterContinuum/gasPressure.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/processLayout.js`.)

The current 300 MW fin bank removes heat and produces liquid, but continuous operation with the 200 MW heater remains limited by gas transport. The native UI run reached 9.5833 simulated seconds before its 360-second wall-time deadline, with 638.938 MJ received and 425.322 MJ removed. Its mass residual was 3.69 × 10⁻¹³ kg and thermal energy residual −4.87 J, with no reported browser or WebGPU error. Those balances do not validate the flow: the gas field reached 2,665.661 m/s, far outside this low-Mach model's validity. The existing demister passage narrows to about 0.06 m × 0.64 m, so increasing the heat sink alone does not make this apparatus suitable for the selected steam production. Smaller numerical substeps do not supply compressible physics or adequate pipe capacity. (Evidence: `artifacts/matter-live-report.json`; sources: `tests/playground/src/demos/matterContinuum/processLayout.js`, `tests/playground/src/demos/matterContinuum/gasPressure.js`, `tests/playground/src/demos/matterContinuum/gpuSimulation.js`.)

The full acceptance check for five seconds of continuous heated condensation is incomplete, and neither gas holder had collected product when that run timed out. The successful heat rejection, visible liquid drainage and conservation measurements must not be reported as successful continuous transport or both-holder collection. The earlier 3 MW configuration also exceeded the low-Mach range; the stronger bank addresses cooling capacity without resolving this transport limitation. (Evidence: `artifacts/matter-live-report.json`, `artifacts/matter-high-power-performance-optimized.json`.)

Only cooled, previously vaporized and condensed water near the electrodes can react. Electrolysis rearranges molecules; it does not split atomic nuclei. The interface shows `2H₂O → 2H₂ + O₂`, both PEM half-reactions, proton transport through the membrane and electrons through the external DC circuit. The explanatory molecule diagram is not a molecular-dynamics simulation.

Cell voltage is selectable from 0 to 2.4 V, with a 20, 100 or 200 kA current limit. Current follows Nernst reversible voltage using local gas pressure, symmetric Butler–Volmer activation losses at both electrodes, and hydrated-membrane plus contact resistance. The equivalent active area is 10 m² at 25 °C. `PEM_CELL` exposes membrane thickness, hydration, exchange current densities and contact resistance; these effective inputs are not calibrated commercial-cell data. The membrane conductivity follows the Springer relation. At zero current and atmospheric product pressure the reversible voltage is 1.229 V. Actual current also requires eligible water and remaining storage capacity. Faraday's law gives `n(H₂) = η Q / (2 F)` and `n(O₂) = n(H₂) / 2`, with 95% efficiency. Electrical energy integrates each charge increment at the voltage then applied. The temperature-control bath supplies or rejects the difference between electrical input and chemical enthalpy. (Sources: `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`; [Springer membrane model](https://doi.org/10.1149/1.2085971), [SPE electrolysis model](https://www.sciencedirect.com/science/article/abs/pii/S0167273804006423).)

A reacting coarse parcel tracks water and product fractions. Once converted, two product daughters replace it at the respective electrode faces with the parent velocity, with conserved mass and source lineage. A physical wall separates the electrode chambers; each has its own pressure-controlled collection port. Product release still occurs in coarse batches when a parent finishes converting, so the markers do not resolve continuous bubble nucleation. Cyan identifies hydrogen and pink oxygen; both real gases are colorless. Crossing the correct collection port retains the parcel in a separate collected inventory. Meters report collected mass and ideal-gas volume at 25 °C and 1 atm in external constant-pressure holders: 1000 m³ H₂ and 500 m³ O₂. These are aggregate storage meters, not sealed vessels represented at tank scale. Production reserves capacity for gas still in transit or partially reacting and stops when storage is full. Electrical input, chemical enthalpy, bath heat, atom residuals and thermal energy remain separate measurements. (Sources: `tests/playground/src/demos/matterContinuum/waterProcess.js`, `tests/playground/src/demos/matterContinuum/gpuShaders.js`, `tests/playground/src/demos/matterContinuum/liveUi.js`.)

Screening → distillation → electrolysis is a coherent educational sequence, but distillation is optional pretreatment rather than a prerequisite for electrolysis. The model does not measure dissolved contaminants or certify the water's suitability for a PEM cell. Pressure-vessel behavior, dissolved-contaminant chemistry, bubble-scale interfaces and molecular kinetics remain outside its scope. [Steam-separator guidance](https://www.spiraxsarco.com/learn-about-steam/pipeline-ancillaries/separators) explains the physical role of droplet separation; the demo resolves offset solid baffles at a coarse parcel scale.

Recorded chapters come from observed spatial and material events. First gas collection is a milestone, not the end of treatment: the apparatus continues processing its remaining water. Recording periodically thins ordinary frames while preserving chapter transitions, the initial state and the latest state. Export serializes every retained frame into bounded JSON chunks and assembles a Blob, yielding between chunks instead of creating one recording-sized JavaScript string. Export does not discard additional history; browser memory and download capacity still apply. (Sources: `tests/playground/src/demos/matterContinuum/liveExperiment.js`, `tests/playground/src/demos/matterContinuum/index.js`.)

The [DOE electrolysis description](https://www.energy.gov/cmei/fuels/hydrogen-production-electrolysis) supplies the separated anode/cathode reactions. [EPA’s treatment overview](https://www.epa.gov/sdwa/overview-drinking-water-treatment-technologies) distinguishes treatment mechanisms and contaminants. [NIST water thermodynamics](https://janaf.nist.gov/tables/H-063.html) supplies the 285.830 kJ/mol liquid-water formation enthalpy used for the reverse reaction’s energy inventory. The Faraday constant is the product of the exact SI Avogadro constant and elementary charge.

Run `python tests/run_matter_gpu.py` for native WebGPU operator comparisons and the cold reservoir-to-boiler route, including mass, momentum, physical power limits, one-clock timing, lineage and shader validation. Use `--water-rows 32` for the largest preset, `--operators-only` for spatial thermal/electrical fixtures, and `--transport-only` for a prepared electrode-feed transport fixture in the actual plumbing. The runner's fill choices are presets; the Playground also accepts custom row counts. Operator fixtures deliberately isolate stages; they do not prove the hours-long cold-start journey. The CPU `python tests/run_matter_process.py` gate covers thermal and chemical balances plus gravity-screen and impact comparisons, not GPU gas transport. Float32 tolerances are measured; bit-identical CPU/GPU output is not claimed.

### Research basis and implementation choices

- [Bridson and Müller-Fischer fluid notes](https://www.cs.ubc.ca/~rbridson/fluidsimulation/fluids_notes.pdf) describe the staggered MAC grid, solid boundaries and matching pressure projection used by the gas transport operator.

- NVIDIA's [Blast documentation](https://nvidia-omniverse.github.io/PhysX/blast/index.html) distinguishes graph damage/splitting from the physics and graphics representations. The experiment therefore uses the existing Blast-to-PhysX scene bridge rather than moving disconnected pieces in a drawing routine.
- [Particle-Based Fluid Simulation for Interactive Applications](https://matthias-research.github.io/pages/publications/sca03.pdf) describes particle density, symmetric pressure/viscosity forces and surface reconstruction. The continuous lane reuses the engine's SPH implementation and measures momentum residuals.
- The [SPH boundary-coupling reference](https://learn.physics-simulation.org/examples/iisph.html) describes hydrodynamic boundary contributions. It identifies the additional work needed for higher-fidelity pressure coupling; the present implementation explicitly reports its contact-coupling scope.
- [PhysX simulation documentation](https://nvidia-omniverse.github.io/PhysX/physx/5.8.0/docs/Simulation.html) explains repeatability's dependence on scene ordering and stepping. The storyboard preserves actual sampled states rather than claiming cross-platform bit-identical reconstruction.
- [Position Based Fluids](https://mmacklin.com/pbf_sig_preprint.pdf) is an alternative incompressibility approach. The existing GPU PBF demo remains available separately; this experiment uses GPU SPH with explicit native-body contact exchange and retains a CPU oracle for tests.

Run `python tests/run_matter_live.py` for quiet/impact/strong/high-speed scenarios, conservation, native-actor momentum and dissipative off-center contact, real event progression, recorded replay, export, camera controls, surface/particle switching, responsive controls and remount checks.

## Original reference vertical slice

Open **Measurements & implementation → Open the original reference workbench**, or add `lab=reference` to the Matter Continuum URL. Its scrubber deterministically reconstructs these bounded, solver-backed phases; it is an inspectable capstone scenario, not a claim that fifty million canonical packets are stepped sequentially:

1. Establish codec-owned water and a coarse bonded aggregate.
2. Add the high-count Particle Storm field and an inbound projectile.
3. Request predictive impact refinement and expose fine bonds.
4. Run XPBD work, accumulate damage, delete fractured edges, and rebuild components.
5. Couple debris to water, build a local distance tile, and run the sparse pressure path.
6. Reveal pre-split physical spray descendants and plan quiet-region recompression.
7. Validate conservation, hold the selected hardware target, and hash a replay checkpoint.

The UI reports Storm logical population and actual bounded draw samples separately. Pattern, symbol, numeric, high-contrast, and reduced-motion options keep state readable without color alone. The Realm Matter Workbench runs live graph queries for water phase changes, steel manufacturing, conductor substitution, glass fracture, and salvage. (Sources: `tests/playground/src/demos/matterContinuum/model.js`, `tests/playground/src/demos/matterContinuum/ui.js`.)

## Minimal use

```javascript
import {
  createAdaptiveMatterPacketCodec,
  createMatterFidelityGovernor,
  StructuralTopology,
} from './engine/matter/index.js';

const codec = createAdaptiveMatterPacketCodec({ pageSize: 256, maxPages: 16 });
const governor = createMatterFidelityGovernor({ qualityMode: 'auto' });
const topology = new StructuralTopology({ topologyId: 'topology:example' });
```

Create packets through the codec. Register fluid metadata against active codec handles. Apply fidelity actions only after checking their source and representation revisions. Submit GPU work once through the owning frame loop.

## Verification

Run the focused gates from the repository root:

```bash
python tests/run_matter_foundation.py
python tests/run_matter_packet_codec.py
python tests/adaptive-matter-fluid-runner.py
python tests/run_matter_structural_transcoding.py
python tests/run_matter_fabric.py
python tests/gpu/run_gpu_data_primitives_tests.py
python tests/gpu/run_matter_runtime_gpu_tests.py
python tests/run_particle_storm_codec_modes.py
python tests/run_matter_continuum.py
```

The suites include deterministic replay, hostile contract input, capacity exhaustion, stale revisions, split rollback, interrupted phase transactions with full participant rollback, real topology disconnection, transactional rigid-backend handoff, stable frontier ordering and saturation, mixed-resolution fluid seams, unified GPU/CPU algorithm races, emergency 64 → 8 → 1 coarsening, GPU sample identity, projection-tier hysteresis, both HUD mount orders, fail-closed projection isolation, Fabric sidecar tamper rejection, and save/reload checks. (Sources: `tests/matter-packet-codec.test.js`, `tests/adaptive-matter-fluid-reference.test.js`, `tests/matter-structural-transcoding.test.js`, `tests/matter-fabric.test.js`, `tests/gpu/gpu-data-primitives.test.js`, `tests/gpu/matter-runtime-gpu.test.js`.)

## See also

- [Particle System](particles.md)
- [Physics and Simulation](physics.md)
- [GPU Physics Engine](gpu-physics.md)
- [Particle Long-Range Solvers](particle-long-range.md)
- [Glossary](../getting-started/glossary.md#matter)