babylon.quarks 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,166 @@ 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.29.0] — 2026-10-24
+
+Phase 7 of the road to 1.0: what still behaves differently from Unity is brought in line before
+the API and the look of effects are frozen. Cones tilt and fill like Unity's and emit from their
+volume, Scaling Mode has Unity's Local, Hierarchy and Shape, curves can be random between two,
+Limit Velocity has Separate Axes, a system has a Stop Action and a Ring Buffer Mode, and the
+particles take the scene's image processing as Babylon's own materials do.
+
+### Upgrading from 0.28
+
+Effects in a scene without image processing, at scale 1 and without cones, look as before. Check
+these, in this order:
+
+1. **Scenes with image processing** (tone mapping, exposure, contrast, a vignette or grading, also
+   when set up by `createDefaultEnvironment()` or a `DefaultRenderingPipeline`): the particles now
+   take it. Re-tune colours that were authored to look right without it, or set
+   `applyImageProcessing: false` on a system to keep the old look.
+2. **Scaled emitters or scaled parents:** the default Scaling Mode is now `'local'`. Set
+   `scalingMode: 'hierarchy'` where a parent's scale should reach the effect. Files saved before
+   0.29 read as `'hierarchy'` and keep their look; save them again to write format 2.
+3. **Cones:** particles between the centre and the rim lean out more (Unity's tilt). Re-tune an
+   effect that relied on the narrower middle.
+4. **`autoDestroy`** still works but is deprecated: use `stopAction: 'destroy'`. Files are
+   written with `stopAction`, which a 0.28 runtime does not read.
+5. **TypeScript:** narrow `LimitSpeedOverLife.speed` before calling `genValue` on it
+   (`!(speed instanceof Vector3Function)`); a custom behavior reading `emitter.matrixWorld` gets
+   the matrix with the Scaling Mode's scale.
+6. **Files are format 2.** babylon.quarks 0.28 warns about them and reads their systems with its
+   own Scaling Mode. Install `babylon.quarks-editor` 0.29 with `babylon.quarks` 0.29, and export
+   from the Unity exporter 0.29 for this runtime.
+
+### Breaking
+
+- `autoDestroy` gives way to `stopAction` (`'none'`, `'disable'` or `'destroy'`, Unity's Stop
+  Action). Files are written with `stopAction` and no longer with `autoDestroy`; reading
+  `autoDestroy: true` from an older file, or passing it to the constructor, still gives
+  `'destroy'`, and the `autoDestroy` property and `QuarksUtil.setAutoDestroy` remain as deprecated
+  aliases. An older runtime does not read `stopAction`.
+- `LimitSpeedOverLife.speed` is typed `FunctionValueGenerator | ValueGenerator | Vector3Function`
+  (it was `FunctionValueGenerator`), for Separate Axes and constant limits. Code that reads it
+  with `genValue(memory, t)` narrows it first: `!(speed instanceof Vector3Function)`.
+- **Cone particles between the centre and the rim tilt by `atan(r · tan(angle))`**, as Unity's
+  Cone, instead of `angle · r`. Each particle follows the cone's side line through its start
+  point, so the cone's far end is a disc of radius `radius + length · tan(angle)` filled as evenly
+  as its base. The rim and the centre are unchanged; particles in between lean out more than
+  before. Re-tune a cone effect that relied on the old, narrower middle. Cones in three.quarks
+  files tilt the new way too, so they lean out further in the middle than in three.quarks.
+- **Scaling Mode works as Unity's, in world and local space, and defaults to `'local'`.** The
+  emitter's scale now reaches the shape, the particles' size and their motion in every mode except
+  where the mode leaves it out: `'local'` (new, the default) uses only the emitter's own `scaling`
+  and leaves its parents' out; `'hierarchy'` uses the whole world scale, as before; `'shape'` now
+  scales only the emission shape, leaving the particles' size and speed alone (it used to scale
+  their size too). Before, a local-space system took its emitter's whole world scale whatever the
+  mode. An effect whose emitter or its parents are scaled looks different unless it was
+  `'hierarchy'`: set `scalingMode: 'hierarchy'` to keep a parent's scale on it, or leave it at
+  `'local'` to keep the effect its own size under a scaled parent. Effects at scale 1 are
+  unchanged.
+  - **Files from before this release keep their look:** the format goes to 2, and a system in a
+    file of format 1 or without `quarksFormat` (older babylon.quarks, three.quarks, the Unity
+    exporter before 0.29) reads as `'hierarchy'`, which gives it the emitter's whole world scale
+    as before (except a world-space system's speed, which now scales too). Save it again to keep
+    that, or set the mode you want. A 0.28 loader warns about a format 2 file and reads its
+    systems as its own default.
+  - **`ParticleEmitter.matrixWorld` (`IEmitter.matrixWorld`) is the matrix the system simulates
+    and draws in:** the world matrix with each axis's length set by the mode. A custom behavior
+    that reads it gets that scale. `ParticleEmitter.shapeScale` is what `'shape'` gives the shape.
+  - **Negative scales mirror the start velocity as they mirror the position,** in every mode; a
+    world-space `'hierarchy'` system used to mirror the position only.
+  - **A sub emission's speed** takes its parent particle's frame, as its size did: it no longer
+    scales with the sub emitter's own scale in `'hierarchy'`.
+- **The scene's image processing applies to the particles by default**, as it does to Babylon's
+  own `ParticleSystem` and its standard and PBR materials. A scene whose
+  `imageProcessingConfiguration` does nothing (Babylon's default) looks the same as before. One
+  that tone maps, sets exposure or contrast, grades, vignettes or dithers now does it to the
+  particles too, so they sit in the frame like the meshes around them. Under a
+  `DefaultRenderingPipeline` with image processing on (`applyByPostProcess`), the particles now
+  leave their colour in linear space for the post process, as Babylon's materials do; before they
+  were gamma-corrected twice and looked washed out. Set `applyImageProcessing: false` on a system
+  to keep the old look. Check effects in scenes set up by any of these, which turn image
+  processing on or hand it to a post process without saying so: `scene.createDefaultEnvironment()`
+  (tone mapping, exposure and contrast), a `DefaultRenderingPipeline` with
+  `imageProcessingEnabled` (its default), a `PrePassRenderer` (SSAO2, SSR, motion blur) and a
+  `ReflectionProbe` rendering in linear space.
+  Tone mapping clamps HDR particle colours, and a contrast below 1 or colour curves lift black,
+  which an additive particle then adds.
+
+### Added
+
+- **Scene image processing** (`ParticleSystem.applyImageProcessing`, default true; JSON writes it
+  only when false): the scene's `imageProcessingConfiguration` (exposure, contrast, tone mapping,
+  vignette, colour curves, colour grading, dithering) is compiled into every render mode, in GLSL
+  and WGSL, through Babylon's own includes, bound on every draw, and switched in place, on
+  the same material, when the configuration changes what the shader needs. A post process that applies it gets the colour in
+  linear space. It runs on the straight colour after fog and before the blend resolve, so alpha
+  stays coverage; particles that multiply the frame (`ALPHA_MULTIPLY`) are a factor rather than
+  light and are not tone mapped. Systems that differ are batched apart. On WebGPU, a 2D colour
+  grading texture works through a WGSL port of Babylon's slice sampler, which Babylon's own WGSL
+  include lacks. The Image Processing demo compares a flame with and without it.
+
+- **Cone Emit from Volume and Length** (Unity's Cone Volume): `ConeEmitter.emitFrom`
+  (`ConeEmitFrom.Base`, the default, or `ConeEmitFrom.Volume`) and `ConeEmitter.length` (5 by
+  default, as in Unity). In Volume, particles start anywhere on their side line from the base up
+  to `length` along z. The Unity exporter writes Cone Volume with its Length instead of warning,
+  and the editor's Shape module and wireframe show both.
+- **Random Between Two Curves** (Unity's MinMaxCurve mode of the same name): `RandomBetweenCurves`
+  holds two `PiecewiseBezier` curves and rolls each particle a mix between them, kept for its
+  life, so every particle follows its own curve within the band. It goes wherever a curve does
+  (start values over the system's cycle, emission rates, every over-lifetime and by-speed
+  behavior, Noise) and reads and writes as `{type: 'RandomBetweenCurves', curve1, curve2}`. Where
+  a system-level setting takes it (emission over time or distance, a burst's count, a shape's
+  speed, Noise's scroll speed) the mix is rolled once per play, as a random range is there, rather
+  than at each emission step as in Unity. A bound that is missing or not a curve warns and reads as
+  a flat 0 curve. The Unity exporter writes it instead of the upper curve, and the editor offers it
+  in its value fields and in every module that edits a curve over life.
+- **Grid sampling** (Niagara's Grid Location by particle index): `GridEmitter.sampling`
+  (`GridSampling.Random`, the default, or `GridSampling.Sequential`). Sequential fills the cells in
+  turn, row by row from −x, −y, so a burst of `row × column` particles puts one in every cell; a
+  restart starts over at the first cell. The editor's Shape module offers it.
+- **Separate Axes for Limit Velocity over Lifetime** (Unity's option of the same name):
+  `LimitSpeedOverLife.speed` takes a `Vector3Function`, a limit per axis, and the new
+  `LimitSpeedOverLife.space` (`'local'`, the default, or `'world'`) says which axes they are
+  measured along. Each component of the velocity is limited on its own and keeps its sign; a world
+  limit is scaled by the system's `motionScale` in a world-space system. `space` is written only
+  when not `'local'`. One limit for the speed works as before. The editor's Limit Speed, Size over
+  Lifetime and Size by Speed modules get a Separate Axes switch, and the new Limit Velocity Axes
+  demo compares the two.
+- **Stop Action** (Unity's option of the same name): `ParticleSystem.stopAction` says what a
+  finished system does: nothing (`'none'`, the default), disable its emitter node (`'disable'`,
+  once per finish), or dispose itself (`'destroy'`). Unity's Callback is the `finished` event,
+  which fires whatever the action. `ignoreStopAction`, runtime only, skips it for tools that replay
+  an effect; `EffectPool` and the editor set it, so pooled and previewed effects keep their
+  authored stop action. `QuarksUtil.setStopAction` sets it on a whole effect. As in Unity, the
+  action waits until the systems the system emits into have no particles left, and a sub emitter
+  target takes none of its own. `ParticleSystem.isAlive(withSubEmitters = true)` is Unity's
+  `IsAlive`. quarks.core's `IParticleSystem` gains `stopAction` (`autoDestroy` is deprecated),
+  `ringBufferActive`, and `hasPendingEmission(state?)` for a sub emission's state.
+- **Ring Buffer Mode** (Unity's option of the same name): with `maxParticles`, a full system's
+  new particles replace the oldest instead of being dropped. `ringBufferMode: 'pauseUntilReplaced'`
+  freezes a particle at the end of its life until then (footprints, decals);
+  `'loopUntilReplaced'` replays the part of its life `ringBufferLoopRange` names (0 to 1 by
+  default); a range of no length holds the particle at that point. Particles of a ring buffer
+  never die by age, so the system keeps them, fires no Death sub emitter for them and never
+  finishes. Lowering `maxParticles` drops the oldest over the new limit. Every render mode but
+  Trail, whose particles always die. The Ring Buffer demo shows both.
+- `EmitterFrame.fromSimulation`, the inverse of `toSimulation`, for behaviors that measure a
+  vector in their own space.
+
+### Fixed
+
+- A **Death sub emitter** fired for the particles that died on a non-looping system's last step
+  queued its burst and never emitted it: the system counted itself finished first. A system now
+  finishes once the emissions its sub emitters run have nothing left to emit, so `finished` fires
+  after those bursts.
+- A local-space force, orbit or per-axis speed limit under an emitter scaled to 0 on an axis read
+  a NaN rotation from it, and turned the velocity into NaN (forces) or stopped limiting
+  (limits). `EmitterFrame` rebuilds the rotation from the axes that remain.
+- **Noise** rolls a random Frequency, Strength, Position or Rotation amount, or Remap (a range or
+  two curves) into every particle. Only the first particle got its own value; the others read a
+  missing one and their position became NaN.
+
 ## [0.28.0] — 2026-10-23
 
 The release after phase 6 of the audit and the 0.28 cleanup: alpha means coverage in every blend