Fluids: water, fire and smoke beside Jolt

[pasquelin]

Current scope — backlog reconciliation, 28 September

This is the fluids programme, not a second coding queue. The earlier comment “only S1 is done” is historical.

Foundation/spike	Recorded delivery	Remaining boundary
#395	Closed physics foundation	Reuse it.
#418 (S0)	Closed, PR #744	Read its published measurements/decisions; no automatic new campaign.
#419 (S1)	Closed, PR #442	Wave/buoyancy foundation, not a finished water surface.
#420 (S2)	Closed, PR #776	Drawing, temporal integration and GO/NO-GO follow-ups are #844/#756/#423.
#421 (S3)	Open	Ripple/smoke costs and tiers still owed.
#422–#425	Open	Production fluids and budget work remain.

floating-crates remains tracked by #522 with #573/#357 prerequisites. Closed spikes do not waive the original demonstrations, budgets, proofs or maintainer decisions below. Preserve the existing priority/order decisions; do not repeat S0/S1/S2 implementation.

Why

Trillion3D must handle water, fire and smoke natively, with a complete and fast base that stays inside a browser's limits. Jolt has no fluid solver, so this work adds a fluids layer beside it. It starts once the physics foundation #395 is merged.

These issues are the reference. The source brief (24 Sept. 2026) is closed. Its corrections, agreed with the maintainer, are built into the text below.

For the user, fluids are options of the existing API. There is no new concept:

• object.water(...), object.fire(...), object.smoke(...);
• buoyancy lives in obj.physics. A body floats on its own when its material's density is below the water's.

Guiding principle (not negotiable)

Keep what affects the game apart from what is only seen.

• Game: buoyancy, current, drag, and the "in water" and "on fire" states.
  • Computed on the CPU and applied through Jolt, in Jolt's thread (Physics 1/6: Jolt in a worker, world and object options, budgets, measured #395).
  • Identical on both renderers, and identical on one core and on several.
• Visual: waves, ripples, splashes, foam, flames, smoke.
  • Computed on the GPU, one way only, from physics to visual.
  • Never read back.

A third-party engine may be cited only as a point of comparison with numbers (costs, resolutions, particle counts). It is never the model this work follows.

Optimisation and performance rules (apply to every lot)

1. Fixed budgets. Fluids have their own GPU, CPU and memory budgets (budget.fluids), in three tiers: performance, balanced, high.
   • Exceeding a budget is reported, never silent.
   • A tier drop is the only automatic reaction allowed, and only for fluids. This is the AGENTS.md exception, written by the transversal lot.
2. Zero allocation per frame in steady state.
   • Every pool has a fixed capacity: particles, injection splats, fire lights.
   • Jolt objects are pre-allocated and reused in the physics thread.
3. No synchronous GPU → CPU read.
   • This covers readPixels, getBufferSubData, and mapAsync awaited inside the frame.
   • An asynchronous read is opt-in only, with at least one frame of latency.
4. Buoyancy is batched in C++.
   • The single wave model, written in TypeScript and running in the physics worker, computes one water plane per body. It adds those planes to the step's command batch.
   • One C++ function in our Jolt build walks the batch and calls ApplyBuoyancyImpulse, with Jolt's exact submerged volume.
   • No call per body, no work on the render thread.
5. One wave model. It is a pure maths module (TypeScript) used by buoyancy. It also generates the uniforms and the WGSL code, which are never written twice by hand. The previous frame's wave position (for temporal antialiasing) is the same formula at t - dt, so nothing is stored.
6. Zero cost outside the active zone.
   • Water and emitters reuse the physics active zone and regions (Physics 1/6: Jolt in a worker, world and object options, budgets, measured #395, Physics 2/6: colliders cooked by the compiler, streamed, exact raycast #396).
   • Visible water animates, like a playing clip. animate: false freezes it.
   • Far water updates its ripples less often.
7. Tier drops use the frame envelope, never a per-pass GPU duration. On tile-based GPUs, passes overlap (AGENTS.md).
   • Drop one tier only when the whole frame stays above its target for a full sliding window while fluids are visible.
   • Raise one tier only after a full window below the target, with a margin (hysteresis), so the tier does not oscillate.
   • Fluids' own share of the frame is measured at the bench, not in play.
   • Per-pass timestamps (WebGPU timestamp queries) only say where the time goes.
8. Pipelines compiled asynchronously and warmed up at load (createRenderPipelineAsync).
   • No frame over 33 ms the first time a body enters water or a fire is lit.
   • dt is clamped, and the renderer recovers cleanly after device.lost.
9. Temporal antialiasing integration.
   • Waves write motion vectors (t - dt).
   • Ripples and particles keep their previous state; for particles, that is one extra position.
   • A reactive mask limits history on fire and particles.
   • Scene depth comes from the existing visibility buffer.
10. Existing engine paths only.
    • Fire lights are light.point, inside the existing shadow budget; flicker only modulates intensity.
    • One lighting model for every surface.
    • Search before writing: reuse any engine sprite or particle path; the open world's rain and particles (moving to pasquelin/Trillion3D-openworld) may be read as prior art, never imported.
11. Designed for WebGPU default limits.
    • Storage buffers ≤ 128 MB, 256 invocations per workgroup, 16 KB of workgroup storage, 8 storage buffers per stage.
    • Larger limits are a bonus detected at runtime.
12. One renderer.
    • Every feature exists in WebGPU (WGSL).
    • Three.js and TSL are forbidden in the engine.
13. Own assets only. Flipbooks, caustics and VAT are generated by our own tool; nothing is taken from elsewhere.

Budgets (starting ceilings, confirmed or corrected by the S0 spike)

Parameter	performance	balanced	high
Total fluids GPU time (ms, measured at the bench on the envelope)	≤ 0.8	≤ 1.5	≤ 2.5
Fluids + buoyancy CPU time (ms)	≤ 0.3	≤ 0.4	≤ 0.5
Fluids VRAM (MB)	≤ 24	≤ 48	≤ 96
Gerstner waves	4	6	8
Local ripples	256²	384²	512²
Particles (total capacity)	16k	48k	128k
Simultaneous fire lights	2	4	8
Volumetric smoke grid	—	32³	64³
Active local simulations	1	2	4

Bench. scripts/mesure/banc, on the repository's public scenes, plus a fluids scene (one ocean, 100 floating bodies, 20 fires, 5 smoke volumes), on both renderers.

Acceptance criteria (MUST)

• The budgets above hold at the bench, in every tier and on both renderers.
• Water height differs by less than 1 cm between the CPU (buoyancy) and the GPU (render), at every sampled point.
• No allocation per frame in steady state: the heap snapshot stays stable over 60 s.
• No synchronous GPU read in the frame, checked by an instrumented wrapper in debug.
• No frame over 33 ms the first time a body enters water or a fire is lit.
• Buoyancy is bit-identical between one core and several: the same input gives the same Jolt trajectory. Safari and hosts without COOP/COEP run on one core.
• Buoyancy runs entirely in Jolt's thread and adds no work to the render thread.
• Nothing costs anything outside the physics active zone.
• Under an exceeded budget, fluids drop one tier within 2 s, with a sliding window and hysteresis, no visible jolt and no oscillation. Only fluids are affected.

Lots

The four spikes come first. Their measurements are published as comments on their issues, with no report file and no dedicated branch. Then comes a STOP: the maintainer reviews S0–S3 before any production code. Every lot also ends with an explicit stop, awaiting validation.

Lot	Issue	Content	Decision
S0	#418	Capabilities, budgets, refraction source, envelope method	Budget table confirmed
S1	#419	One wave model, batched buoyancy in C++	CPU/GPU gap < 1 cm, CPU ≤ 0.3 ms
S2	#420	GPU particles on both renderers	GO / NO-GO single API
S3	#421	Ripples and volumetric smoke costs	Tiers and resolutions
STOP	—	Maintainer reviews S0–S3	GO final architecture
P1	#422	Water: surfaces, buoyancy, boat, ripples, splashes, foam	Water MUST
P2	#423	Particles, fire, smoke flipbooks, heat distortion, wind API	Fire MUST
P3	#424	Budget manager, active zone, tiers, AGENTS.md exception	Transversal MUST
P4	#425	SHOULD / NICE items, one by one on decision	Per item

The order P1 → P2 → P3 is imposed. Water comes first, because it fixes the wave model and the contract with the renderers that everything else reuses.

Every lot ships its docs, its lesson and a live example, in every language. Every lot also carries its unit tests:

• the wave model (height, fixed point, steepness normalisation);
• buoyancy (immersed, emerged, partly immersed, material density, compound bodies);
• pools (saturation without allocation);
• the budget manager (tier switch, hysteresis).

Out of scope

• Fluid simulation inside Jolt, and general two-way coupling.
• Deformable water at the scale of a whole world.
• Network synchronisation of visual simulations; only game states count.

Links

• Physics parent Physics in the engine: Jolt built in, as options of the existing API #354; foundation Physics 1/6: Jolt in a worker, world and object options, budgets, measured #395; regions Physics 2/6: colliders cooked by the compiler, streamed, exact raycast #396.
• Physics 6/6: planet gravity, rewind, conveyors, impacts #400 keeps what does not depend on fluids. Wind, buoyancy and the boat move here.

[pasquelin]

Order (maintainer's delegate, 25 Sept.): only S1 (#419) is done, and no fluid example is live: floating-crates is parked on #573 and #357. Priority from now: #418 (S0), then #420 (S2), then #422 (P1 water surface), each 🟠 high. #422's surface comes from the one GPU deformation stage (#357, 🔴 critical in #483), never from a per-frame page loop. #421, #423, #424 and #425 follow.

[pasquelin]

Body updated: WebGL path removed from the scope (#1483).