@woosh/meep-engine 3.68.0 → 3.70.0

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 ## 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
+  `ShadedGeometrySystem` and `GPUParticleEmitterSystem` do. It simulates every trail in compute and extrudes its
+  tube in the vertex stage, drawn inside the transparency pipeline as before. The CPU builds no geometry and
+  uploads only the trails whose fields changed: a frame costs a comparison of each trail's fields.
+- **Breaking:** a trail's head follows its entity's transform as the scene holds it, so a translation written by
+  hand moves the trail only once it is announced (`t64_announce_change`), as for meshes and particle emitters.
+  The system read `transform.matrix` every frame before.
+- **Breaking:** a trail's knots live on the GPU only. Removed from `Trail3D`: `tube`, `build()`, `updateHead()`,
+  `dispose()`, `time`, `timeSinceLastUpdate`, `distanceSinceLastUpdate`, `trailingIndex`, `mesh` and `bvh`; from
+  `Trail3DFlags`: `Aging`, `Built`, `BoundsNeedUpdate` and `Reseed` (`Spawning` and `Lit` keep their values);
+  `Trail3DSystem.batch`; and the modules `TubeX`, `TubeXFixedPhysicsSimulator`, `tube_attributes_spec`,
+  `trail_tube_write_geometry`, `seed_trail_tube`, `advance_trail` and `trail_head_position`. `trail_knot_count`
+  moves to `src/engine/graphics/ecs/trail3d/trail_knot_count.js`. `Trail3D` is not serializable, so no save is
+  affected.
+- **Changed:** `seed_trail_stroke` writes the stroke into `Trail3D.knots` alone. `make_gradient_stroke` is
+  unchanged.
+- **Added:** `Trail3D.warmup`, on by default: a new trail fades in over its first `maxAge` seconds, its head born as
+  old as the time left of that first life. Turn it off for a trail that must be whole from its first frame, a
+  tracer. It round-trips through JSON.
+- **Added:** `Trail3D.knots`, a `TrailKnots` of knots laid down whole (a stroke, a helix), drawn as they are, and
+  `Trail3D.clearCount`, which moves with every `clear()`.
+- Measured on an AMD RDNA2 iGPU (2 CUs) at 1258×566, 8 radial segments, every trail moving and in view, both
+  systems in one page: 100 trails of 2 s cost 22.8 ms of CPU a frame on the old system and 0.69 ms on this one;
+  1,000 trails of 2 s, 184 ms and 1.85 ms. Drawing them costs the GPU about the same, most of it in the vertex
+  stage: 0.70 against 0.81 ms at 100 trails, 6.3 against 7.2 ms at 1,000, the second figure including the
+  update and the cull. 10,000 trails of 2 s cost 10.8 ms of CPU, 4.5 ms of it moving and announcing the
+  transforms and 4.3 ms inside the render call, and 65.5 ms of GPU. One trail costs the GPU 25 µs a frame, where
+  it cost 9 µs: the update, the cull and the draw arguments are passes of their own however few trails there are.
+
+Migrating:
+
+- Pass the scene: `new Trail3DSystem(graphics, scene)`.
+- Announce every translation written to a trail's entity by hand (nekomancer's guide motes and speed ribbons).
+- A system subclass that scaled the tube's vertex colours after each update (nekomancer) puts the factor into
+  `trail.color` when the trail is made instead: colour is linear and unbounded, so the trail looks the same.
+- Code that seeded a tube and drove its head (meep-shooter's projectiles: `seed_trail_tube`, `updateHead`, the
+  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 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)
 
 - **Breaking:** `AdaptiveRenderDelay`'s `decay_per_sample_ms` is replaced by `decay_rate`: milliseconds of delay shed