@woosh/meep-engine 3.69.0 → 3.70.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+### Wind: the far field carries turbulence, and the gust is gone
+
+- **Breaking:** `GlobalFluidEffector` loses `gust`, `gust_period`, `gust_phase`, `advance()` and `compute_gust()`.
+  The far field was one vector everywhere, the gust pulsing the whole world at once; it is now the mean wind and a
+  field of eddies the mean carries along, which the GPU fluid steps toward at every face, so the ground, a wall or
+  a canopy shapes them.
+- **Added:** `GlobalFluidEffector.turbulence_intensity`, the eddies' rms as a share of the mean speed (0 by default,
+  no turbulence; 0.15 to 0.2 over grass), and `turbulence_length`, their length scale `L` in metres (58.6 by
+  default; the most energetic eddies are about `4·L` long).
+- **Added:** `GPUFluidSystem#far_field_at(out, x, y, z)`, the far field at a point. `far_field(out)` is its mean.
+  Headless requests and both cloth winds read the far field at the point.
+- **Breaking:** `GlobalFluidEffector` serializes as version 1. A host that loads saves made before registers
+  `GlobalFluidEffectorSerializationUpgrader_0_1` beside its adapter; a saved gust is dropped.
+- **Breaking:** the `FluidAtmosphere` record is 17 words; `VELOCITY_*` is the mean. `WIND_FIELD_UNIFORM` is set from
+  `GPUSceneWind.is_uniform`, and a pass that binds the wind field by hand binds `fluid_turbulence`
+  (`GPUSceneWind.turbulence`) too; `GPUSceneWind.bind` does.
+- Turbulence costs the AMD RDNA2 iGPU 0.5 ms a frame at the default fluid domain (64×32×64 cells of 0.5 m, 4
+  cascades), on 8 ms; none without it. Each cascade reads it band-limited to its own cells.
+
+Migrating:
+
+- A gust becomes turbulence: `turbulence_intensity = gust / |wind|` keeps its strength as an rms, and
+  `turbulence_length = |wind| · gust_period / 4.05` sends the strongest eddies by every `gust_period` seconds.
+
 ### Trails: `Trail3DSystem` simulates and extrudes them on the GPU
 
 - **Breaking:** `Trail3DSystem` takes the scene its entities are in, `new Trail3DSystem(graphics, scene)`, as
@@ -43,9 +67,14 @@ Migrating:
   writes to `time` and `timeSinceLastUpdate`, `system.update(0)` before rendering) drops all of it: the head
   follows the announced transform. Where `time = maxAge` was written to show a tracer whole at once, set
   `warmup = false`.
+- The head is read when a frame is drawn. A new trail's knots start where its entity stands in the first frame
+  drawn after the component is added, and a trail whose `Spawning` is cleared keeps its head where the last frame
+  drew it. An entity moved before its first frame, or a `Spawning` cleared in the same update as the head's last
+  move, loses that stretch: meep-shooter's tracers stay at the muzzle for their first frame and clear `Spawning`
+  the frame after the impact.
 - A shape written into `trail.tube` after `trail.build` (queep-3-arena's helix) goes into a `TrailKnots` on
   `trail.knots` instead: `setCount`, then `setKnot` with each knot's position, frame, thickness and starting age.
-- A trail that only hangs on an entity (meep-demo-castle) needs nothing.
+- A trail that only hangs on an entity (meep-demo-castle) needs nothing beyond the scene passed to the system.
 
 ### Network: the render delay comes down by the clock, and starts over after a wait of the client's own (SW_303, SW_304)