babylon.quarks 0.21.0 → 0.24.0

package/CHANGELOG.md

@@ -4,6 +4,190 @@ All notable changes to the `babylon.quarks` package are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project follows the `quarks.core` 0.x version line.
 
+## [0.24.0] — 2026-10-20
+
+### Added
+
+- `ParticleSystem.renderingGroupId` (constructor option, JSON `renderingGroupId`, written only when
+  not 0): the Babylon rendering group the batch mesh draws in. Systems with different groups are
+  batched apart.
+- `ParticleSystem.applyFog` (constructor option, JSON `applyFog`, written only when false): the
+  scene's fog now reaches the particles in every render mode, in GLSL and WGSL, the way it reaches
+  any other mesh. Additive blending fades toward black instead of the fog colour. Fog is bound from
+  the scene on every draw, so enabling or disabling it at runtime needs no recompile.
+- `ParticleSystem.playbackSpeed` (constructor option, JSON `playbackSpeed`, written only when
+  not 1): a multiplier on the time the system is advanced by — Unity's Simulation Speed. The
+  Unity exporter writes it from Main → Simulation Speed.
+- quarks.core `ApplySequences` is registered in `BehaviorTypes`, so an effect using it serialises
+  and loads like any other behavior.
+- Bounds and culling. Every system measures the world bounds of what it draws
+  (`ParticleSystem.getWorldBounds`), from the store columns for sprites and meshes and from the
+  ribbons for trails; batch meshes carry the union, so Babylon's frustum culling skips the draw of
+  a batch no camera sees and transparent sorting has real bounds to work with. Measured in full
+  every few steps and carried, padded for the motion since, in between: no measurable cost on the
+  profiling scenarios.
+- `ParticleSystem.cullingMode` (constructor option, JSON `cullingMode`, written only when not
+  `'always'`): Unity's Culling Mode. `'pause'` freezes a system while no active camera sees its
+  bounds; `'pauseAndCatchUp'` also replays the missed time (up to 2 s) when it comes back, within
+  `BatchedRenderer.catchUpBudgetMs` (2 ms per frame, shared by all systems; what does not fit is
+  dropped). Culled systems are neither simulated nor filled into their batch. Empty systems and sub
+  emitter targets are never culled; `BatchedRenderer.cullingEnabled = false` turns the test off.
+  With 400 systems in a ring around the camera and three quarters of them out of view, a frame goes
+  from 9.6 ms to 1.6 ms. The Unity exporter writes Pause and Pause And Catch-up.
+- Deterministic randomness. Every roll the simulation makes now goes through quarks.core's
+  `random()`, whose source is replaceable: `setRandomSource(createSeededRandom(seed))` makes a whole
+  scene reproducible, `withRandomSource` scopes it, and `getRandomSource` reads it back. The noise
+  generators are seeded by slot, so a Noise behavior looks the same on every run. UUIDs keep using
+  `Math.random`.
+- `ParticleSystem.seed` (constructor option, JSON `seed`, written only when set): the system rolls
+  on its own generator started from the seed while it steps, and restarts it on `restart()`, so the
+  effect plays out identically every time; systems it emits into roll on it too. The editor has a
+  "Fixed seed" field; the Unity exporter writes Main → Random Seed when Auto Random Seed is off.
+- `EffectPool`: a pool of copies of one effect for things played many times over. `acquire(position,
+  parent)` takes an idle copy (or makes one, up to `maxSize`), places it and plays it; a copy whose
+  systems have all finished returns to the pool by itself; `stop(copy)` ends a looping copy's
+  emission and lets it die out first; `release(copy)` takes it back at once; `prewarm` makes copies
+  up front. Idle copies stay disabled in the renderer's batches, so acquiring allocates nothing.
+- `QuarksUtil.instantiate(root)`: a deep copy of an effect tree, with sub emitter links pointing at
+  the copied emitters.
+- `ParticleSystem.sortMode` (constructor option, JSON `sortMode`, written only when not `'none'`):
+  Unity's Sort Mode. `'distance'` draws the particles of the batch farthest from the active camera
+  first, so nearer alpha-blended particles cover farther ones; `'oldestInFront'` and
+  `'youngestInFront'` order by age. The order is a radix sort over the whole batch after each fill
+  (about 2.5 ms per 50k particles), so systems with different modes are batched apart; trails are
+  not sorted. The editor's Renderer module and the Unity exporter carry it (Distance and Depth both
+  map to `'distance'`).
+- `ParticleSystem.minParticleSize` / `maxParticleSize` (constructor options, JSON, written only when
+  set): Unity's Min / Max Particle Size, the smallest and largest size a billboard or stretched
+  particle is drawn at as a fraction of the viewport height, clamped in the vertex shader (GLSL and
+  WGSL). Meshes and trails ignore them. The editor's Renderer module has them under "Limit screen
+  size"; the exporter writes Unity's values, its default maximum of 0.5 included.
+- `ParticleSystem.alignToDirection` (constructor option, JSON `alignToDirection`, written only when
+  true): Unity's Align To Direction. A mesh particle's +Z is turned along the direction its shape
+  sends it; a billboard's top is turned toward it in the emitter's XY plane. The start rotation is
+  applied on top; a particle with no speed is left alone. Shape module checkbox in the editor; the
+  exporter writes Shape → Align To Direction.
+- quarks.core `Noise` gains `scrollSpeed` (Unity's Scroll Speed: the field moves past the particles,
+  sampled once per frame, reset with the behavior) and `remap` (Unity's Remap: a curve read at the
+  raw noise mapped from [-1, 1] to [0, 1], whose value replaces it). Both in JSON, the editor's Noise
+  module and the exporter.
+- quarks.core `VelocityOverLife` gains `radial` (Unity's Radial: speed away from the orbit centre)
+  and `orbitalOffset` (Unity's Orbital Offset: where the orbital speeds turn around, relative to
+  the emitter). In JSON, the editor's Velocity module and the exporter.
+- quarks.core `EmitSubParticleSystem` gains `inherit` (Unity's sub emitter Inherit): `'color'` and
+  `'size'` multiply the sub particles' start values by the parent's current ones, `'rotation'` adds
+  the parent's, `'lifetime'` scales theirs by the parent's remaining lifetime fraction. The mask
+  travels in the emission state, so a host that emits into a system by hand can set it too. In
+  JSON, the editor's Sub Emitters module (four checkboxes) and the exporter.
+- `BatchedRenderer.simulationBudgetMs` (unlimited by default): once a frame's simulation has taken
+  this long, the systems still to be advanced run one step instead of catching up on the long
+  frame, and the time the skipped steps would have covered is dropped — so a frame that already ran
+  long cannot make the next one longer still.
+
+### Changed
+
+- Developed and tested against `@babylonjs/core` 9.31.0 (was 9.6.2); the peer range stays
+  `>=9.0.0`. The examples and the editor's dev dependencies follow.
+- `ParticleSystem.isFinished()` is true for a looping system whose emission was ended with
+  `endEmit()` once its particles are gone, and for a sub emitter target whenever it is empty,
+  looping or not; `finished` fires accordingly. `QuarksUtil.isEffectFinished` follows, so an effect
+  with looping systems is finished after `endEmit` rather than never.
+
+### Fixed
+
+- quarks.core `ApplySequences` threw on update while it had no sequences yet (an editor adds the
+  behavior before its first sequence); it now leaves the particles alone until one is appended.
+- `ParticleSystem.clone()` left cloned `EmitSubParticleSystem` behaviors transforming by the
+  original system's emitter; they now follow the clone. `ParticleEmitter.clone()` no longer
+  disables the clone itself when only an ancestor of the original was disabled.
+- `renderOrder` now reaches the batch mesh as `alphaIndex`, so it orders the batch among the
+  scene's transparent meshes instead of only keying the batching; it used to have no effect on
+  what was drawn first. `layerMask` likewise now reaches the batch mesh — cameras with a
+  non-matching mask used to draw the particles anyway.
+
+## [0.23.0] — 2026-10-18
+
+### Changed
+
+- CPU simulation and batch upload rewritten to work on the `ParticleStore` columns instead of
+  walking particle objects. Scalar attributes (`rotation`, `angularVelocity`, `uvTile`, `flip`,
+  `startSpeed`) and mesh quaternion rotations now live in store columns; the sprite batch copies
+  them as ranges and only visits particle objects for sub-emitted systems. Compiled behavior passes
+  (now built for single behaviors too) read and write the columns, interpolate sampled curves and
+  gradients inline and take per-particle random samples from a mirrored memory column, so a step
+  no longer touches the particle object for the built-in behaviors. Snapshots of size and colour
+  for the renderer are only kept when a behavior can change them, and the step's integration,
+  newborn fix-up and compaction run in one pass. Trail ribbons transform each recorded sample
+  once, upload indices straight to the GPU buffer (no per-frame sub mesh rebuild) and recompute
+  the emitter matrix only when its transform changed. `Noise` and `TurbulenceField` evaluate
+  constant generators once per frame and update through the columns. Measured on 50k particles:
+  billboards 2.1–2.9x faster per frame, trails 1.5x, noise/turbulence 1.2x.
+- Assigning a `Quaternion` to a sprite particle's `rotation` or `angularVelocity` copies it into
+  the particle's store row; reading the property back returns a view of that row rather than the
+  assigned object. `RandomQuatGenerator` stores its sample as four numbers in the particle's
+  memory instead of a `Quaternion`. `TrailParticle.previous` (deprecated) is created on first use.
+
+## [0.22.0] — 2026-10-17
+
+### Added
+
+- Mesh particle lighting modes: `ParticleSystem.lighting` (constructor option `lighting`, saved
+  as `lighting` on the effect's `QuarksMaterial` and read back by `QuarksLoader`) is `'fixed'`
+  (default — exactly the light mesh particles had before), `'unlit'` (the lighting term is
+  compiled out with `MESH_UNLIT`: texture × particle colour, for emissive meshes) or `'scene'`
+  (the scene's first enabled `DirectionalLight` / `HemisphericLight`, re-read every frame:
+  direction, diffuse × intensity, `scene.ambientColor`, plus a hemispheric light's ground colour
+  in the ambient; falls back to the fixed light when the scene has neither). Systems with
+  different lighting are batched apart. The default is not written to JSON.
+- `BatchedRenderer.setMeshLighting({direction, color, ambient})` (Babylon `Vector3` / `Color3`,
+  any subset) sets the `'fixed'` light for every mesh batch of the renderer, including later ones;
+  `getMeshLighting()` returns a copy, `defaultMeshLighting()` the built-in values
+  (`(0.4, -1, 0.6)`, white, `0.35` grey). Exposed in the editor's Renderer module as "Lighting".
+- Mesh particle rim (Fresnel) term: `ParticleSystem.rim` (constructor option `rim`, saved as
+  `rim` on the effect's `QuarksMaterial`) — `{color: [r, g, b], power, strength, mode}` with
+  defaults `[1, 1, 1]`, `2`, `1`, `'add'`; any field may be left out. The edge term is
+  `pow(1 - |N·V|, power) * strength`; `'add'` adds `color` (glowing edge), `'mix'` blends toward it
+  (outline). Compiled in only when set (`MESH_RIM` / `MESH_RIM_MIX`), batched by value, written to
+  JSON only when set, and exposed in the editor's Renderer module. `normalizeMeshRim` /
+  `meshRimEqual` are exported.
+
+### Changed
+
+- **Behaviour change:** quarks.core `WidthOverLength` (Width over Trail) now reads its curve as a
+  multiplier on the width each trail sample was recorded with (the particle's `size.x` at that
+  moment), the way Unity's Width over Trail works, and gives the head sample the curve's value at
+  0, so a trail no longer flares out behind its head or steps at the tip. A new `absolute` flag
+  (`new WidthOverLength(curve, absolute = false)`, JSON field `absolute`) keeps the old reading —
+  the curve as the width in world units, the head at the particle's size. `toJSON` always writes
+  the flag; JSON without it (everything written by 0.21 and earlier, including the Unity
+  exporter's output) loads as `absolute: true`, so authored effects keep their look. Code that
+  builds `new WidthOverLength(curve)` gets the new multiplier behaviour: divide an absolute curve
+  by the start size, or pass `true`. `TrailParticle` gains `historyBaseSizes` (the unscaled
+  recorded widths) and `headWidthScale`.
+
+### Fixed
+
+- Burst `cycle` / `interval` are honoured: a burst fires `cycle` waves, `interval` seconds apart,
+  each rolling `probability` on its own. Repeats past the system's `duration` are dropped (a
+  looping system starts them over every loop), a `cycle` below 1 fires once, and a zero interval
+  fires every wave at once. Previously every burst fired a single wave.
+- Emission over distance spreads the particles it owes along the path the emitter travelled
+  this step, each at its own metre mark (the spacing carries across steps), instead of spawning
+  all of them at the emitter's current position — a fast world-space emitter now leaves a
+  continuous trail rather than one clump per frame. Only the position is interpolated (rotation
+  and scale are the emitter's current ones) and the particles start at age 0. Local-space
+  systems, whose particles move with the emitter, are unchanged.
+- A sub emitter whose target uuid is not in the effect no longer throws on every frame.
+  `QuarksLoader` unlinks it (`subParticleSystem = undefined`) with one `console.warn` naming the
+  emitter and the uuid — also when the uuid names a node that is not a particle emitter — and
+  quarks.core `EmitSubParticleSystem` skips any value that is not a resolved emitter. An
+  unresolved uuid string is written back unchanged by `toJSON`.
+- quarks.core `RotationOverLife` turns mesh particles too: a quaternion rotation is turned about
+  the particle's local Z axis (the axis a number `startRotation` uses, and what Unity's Rotation
+  over Lifetime without separate axes does to meshes), in its own pass and in the fused pass, and
+  the step is kept for the renderer's in-between-step interpolation. It used to do nothing on
+  meshes, silently. `Rotation3DOverLife` remains the behavior for any other axis.
+
 ## [0.21.0] — 2026-10-16
 
 ### Added