babylon.quarks 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,591 @@ 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
+mode, as in Unity; shapes fill like Unity's; `play()`, `resume()` and the `QuarksPrefab` timeline
+behave like Unity's `Play` and `PlayableDirector`; the renderer's transform and the camera layers
+no longer change what is drawn; effect files hold only what differs from the defaults; and no
+`any` is left in the public types. The Unity exporter is out of experimental, and the editor gets a
+headless `createEditorSession` and WebGPU. 0.27.1 was never published to npm: its packaging changes
+(below) ship in this release.
+
+### Upgrading from 0.27
+
+Most effects load and play unchanged. Check these, in this order:
+
+1. **Effects under additive, premultiplied, screen, subtract or max blending whose alpha falls
+   below 1** now fade with it. If one looks dimmer than you want, raise its alpha or its colour; a
+   texture authored premultiplied should be re-exported with straight alpha. Multiply and min
+   particles lighten toward white as their alpha falls instead of staying dark.
+2. **Fog follows the blend mode.** Subtract and screen effects fade toward black with distance, like
+   additive ones, and multiply effects toward white; only those that lay over the frame still mix
+   toward the fog colour.
+3. **Soft particles** fade linearly instead of quadratically under `ALPHA_ADD` and
+   `ALPHA_COMBINE`; re-tune `softFarFade` if a soft edge looks different.
+4. **Shapes with a thickness above 0, cones, and grids** spread particles differently (evenly over
+   the volume, every cone particle at its start speed, grid cells centred). Re-tune an effect that
+   relied on the old crowding at the centre.
+5. **Behaviors no longer reset at every loop.** A looping `Noise` or `TurbulenceField` keeps going
+   instead of jumping back to its start once a loop, and the sub emissions of particles still alive
+   carry on into the next loop.
+6. **`play()` on a finished system restarts it.** To undo a pause and leave a finished system
+   finished, call `resume()` (or `QuarksUtil.resume(root)`).
+7. **`QuarksPrefab`'s end lets the particles die out.** Call `stop()` yourself where you want them
+   cleared on the spot. `update()` with no argument now steps by the engine's frame time, and
+   `autoUpdate` drives the timeline for you. A prefab saved with a `timeScale` other than 1 now
+   plays its systems at that speed, and `addParticleSystemAnimation` no longer pauses the prefab.
+8. **Move emitters, not the `BatchedRenderer`.** Its transform no longer moves the particles.
+9. **Camera layers count for culling.** Only systems with a `cullingMode` other than the default
+   `'always'` are affected: one whose `layers.mask` no active camera renders now pauses as its
+   `cullingMode` says. Give the camera a `layerMask` that includes it.
+10. **Files are written with only their non-default fields.** babylon.quarks 0.27 and later read
+    them; three.quarks and babylon.quarks before 0.27 do not. Keep the old files if a three.quarks
+    tool must read them.
+11. **TypeScript and plugins:**
+    - `v.isVector2` instead of `Vector2.isVector2`; `setAxisAngleFromRotationMatrix` takes a
+      `Matrix4`.
+    - JSON readers and `QuarksLoader` take typed JSON or `unknown` (see the `any` items below), and
+      a behavior's `toJSON` returns a `BehaviorJSON` with a `type`.
+    - A plugin's `loadJSON` must only read its JSON: saving now calls it to find the defaults.
+    - `BatchedRenderer.batches` and `systemToBatchIndex` are read-only.
+    - A `VFXBatch` subclass implements `resizeBuffers()` and `initialCapacity` and creates its own
+      `mesh` in `setupBuffers`.
+    - `EulerGenerator.eular` is now `euler` (the old name is a deprecated alias).
+12. **Editor:** a `resolveTexture` callback returns a Babylon `Texture`, and `ValueField` with
+    `curve={false}` reports a `ValueGenerator` (see the editor's changelog). Install
+    `babylon.quarks-editor` 0.28 with `babylon.quarks` 0.28.
+
+### Breaking
+
+- **Alpha means coverage in every blend mode.** A particle's alpha (its colour over life, a soft
+  fade, erosion, a rim fade, a `tint`) now fades it out whatever `blendMode` it draws with, as
+  Unity's particle shaders do for their Alpha, Premultiply, Additive and Multiply modes. Before,
+  modes whose blend takes the colour at full weight ignored alpha. What changes on screen:
+  - `ALPHA_ONEONE`, `ALPHA_PREMULTIPLIED`, `ALPHA_SCREENMODE`, `ALPHA_SUBTRACT`, `ALPHA_MAXIMIZED`,
+    `ALPHA_MAX` and the other modes that take the colour at full weight multiply it by its alpha
+    in the shader. An effect whose alpha is below 1 under these modes draws dimmer than before, as
+    it would in Unity; one with alpha 1 draws as before. Textures stay straight alpha, as in
+    Unity's Premultiply mode: a texture authored premultiplied should be re-exported straight.
+  - `ALPHA_MULTIPLY` and `ALPHA_MIN` move the colour toward white as alpha falls, so a fading
+    multiply particle lightens away instead of staying dark (Babylon's own particles do the same).
+  - The soft-particle fade lowers alpha only. Under `ALPHA_ADD` and `ALPHA_COMBINE` it used to fade
+    colour and alpha together, so the blend weighed it twice and the fade looked quadratic; it is
+    now linear over the soft distance, as in Unity and Unreal's Depth Fade. An opaque system
+    (`transparent: false`) or one under `ALPHA_INTERPOLATE` or `ALPHA_REPLACE_COLOR` has no
+    coverage to fade, so soft particles no longer darken it; they never faded it out either.
+  - `ALPHA_MAXIMIZED` takes the colour by alpha twice (its blend weighs it once more), so its fade
+    is quadratic; every other coverage mode fades linearly.
+- **Fog follows the blend mode.** Particles that subtract from or screen over the frame fade
+  toward black with distance, like additive ones; multiply particles fade toward white, which
+  leaves the frame alone; particles that lay over the frame (`ALPHA_COMBINE`,
+  `ALPHA_PREMULTIPLIED`, opaque) still mix toward the fog colour. Before, every mode other than
+  `ALPHA_ADD` and `ALPHA_ONEONE` mixed toward the fog colour, which fogged a multiply or subtract
+  effect into a coloured haze.
+- **`Vector2.isVector2` is an instance flag**, set on the prototype as `isVector3` and `isVector4`
+  are, instead of a static field. Read it on a vector (`v.isVector2`); `Vector2.isVector2` on the
+  class is gone.
+- **`Vector4.setAxisAngleFromRotationMatrix` takes a `Matrix4`**, the matrix it has always read
+  (see Fixed). Code that passed a `Matrix3` no longer compiles; it got a wrong axis and angle.
+- **Shape thickness fills evenly, as in Unity.** A sphere's or hemisphere's Radius Thickness now
+  spreads particles evenly over the volume of the shell, and a circle's and donut tube's over its
+  area (the cone already did); a rectangle spreads each edge's particles evenly over its band. Before, the radius was rolled linearly, so a
+  full sphere put half its particles within half its radius instead of an eighth. Effects with a
+  thickness above 0 look less crowded at the centre.
+- **Cone particles all start at their start speed.** The direction tilted toward the rim was not
+  normalised, so particles inside the base disc moved slower than the rim's, by up to 3 % at the
+  default 30° and up to 24 % at 90°.
+- **A grid emits from its cells' centres**, symmetric about the origin: a grid of width 2 with two
+  columns emits from x = ±0.5 instead of −1 and 0.
+- Every shape's `fromJSON` takes a `ShapeJSON` instead of `any`, `ShapeJSON.speed` is a
+  `FunctionJSON`, and `ValueGenerator.startGen` and `genValue` take a `GeneratorMemory`.
+- `EmitterShapes` lists the fields its shapes have: the grid's `row` (it said `rows`), no `angle`
+  on the sphere and hemisphere, the box's `emitFrom` as the new `'boxEmitFrom'` field type, and a
+  `transform` (the new `'shapeTransform'` type) on every shape.
+- **Files hold only the shape and behavior fields that differ from their defaults.** A system's
+  shape and each behavior are written through the new `EmitterToJSON` and `BehaviorToJSON`, which
+  leave out every field equal to the default their type reads a missing field as, as the system's
+  own settings already were; a field the type needs, such as a behavior's curve, stays. babylon.quarks
+  0.27 and later read these files; **three.quarks and babylon.quarks before 0.27 no longer do**.
+  `toJSON()` on a shape or behavior still writes every field.
+- `Behavior.toJSON()` returns the new `BehaviorJSON` (a `type` and the settings) instead of `any`. A
+  behavior whose `toJSON` was declared to return something without a `type` no longer compiles.
+  `EmitterShapePlugin.loadJSON` and `BehaviorPlugin.loadJSON` are declared to take `ShapeJSON` and
+  `BehaviorJSON`, as methods, so a plugin that types its own JSON still compiles; they must only
+  read, since saving calls them to find the defaults.
+- **`play()` on a finished system plays it again**, as Unity's `Play` does: it restarts it from
+  the beginning. Before, it only unpaused, and a finished system stayed empty. A paused or stopped
+  system still resumes where it was. `QuarksUtil.play(root)` does the same for each system, so a
+  short burst that had finished inside a longer effect plays again; to undo a pause without that,
+  use the new `resume()` and `QuarksUtil.resume(root)`.
+- **Behaviors no longer reset at every loop.** A looping system called each behavior's `reset()`
+  as it began its next loop, so a `Noise` or `TurbulenceField` jumped back to its start offset
+  once a loop and the sub emissions of particles still alive were dropped. `reset()` now runs only
+  on `restart()` (and `stop()`), as `Behavior.reset` documents.
+- **`QuarksPrefab` timeline:**
+  - The end of the timeline ends the emission of the systems still playing and lets their
+    particles die out, stops the clips, stops the prefab and rewinds it; it used to call `stop()`,
+    which cleared every particle on the spot. Call `stop()` yourself for that.
+  - A track's window excludes its end in `update` too, as `setTime` did: a system whose track ends
+    at 0.5 s stops emitting at 0.5 s, not one frame later.
+  - `update()` with no argument advances by the engine's frame time (game time) instead of the
+    wall clock.
+  - `addParticleSystemAnimation` no longer pauses the prefab.
+  - A looping track that ends with the timeline does not start over, and one restarted earlier
+    ends its emission with the timeline too.
+  - `timeScale` now speeds up and slows down the particle systems on the timeline (see Added), and
+    a negative, NaN or infinite one is read as 0. A prefab saved with a `timeScale` other than 1
+    plays its systems at that speed now.
+  - `pause()` then `play()` resumes exactly the systems the pause paused, those dying out after
+    their window included (they stayed frozen before), and `setTime` on a paused prefab leaves the
+    systems it starts paused.
+- `ParticleEmitter.toJSON` writes `visible` from the emitter's own enabled flag, as `clone()` and
+  `serializeEffect` do, not from its parents': an emitter under a disabled template is saved
+  visible.
+- `retainEffectResources` takes the effect's materials as any iterable, and counts holders of a
+  material as it does of a texture.
+- **The renderer's transform no longer moves particles.** The batch meshes stay under the
+  `BatchedRenderer` node (disabling or disposing it still hides or frees them), but their world
+  matrix is frozen at identity: particles are drawn where their emitters put them, wherever the
+  renderer is, and the batch bounds Babylon culls by are the particles' own. Before, a moved,
+  turned or scaled renderer moved every particle again and only warned once; the warning is gone.
+- `BatchedRenderer.batches` and `systemToBatchIndex` are read-only (`ReadonlyArray`,
+  `ReadonlyMap`); the renderer has always owned them, and code that wrote to them no longer
+  compiles; assigning `batches` throws at runtime.
+- **Culling only counts the cameras that render a system's layer**: a camera whose `layerMask`
+  shares no bit with the system's `layers.mask` no longer keeps it simulating, so a system on a
+  layer only an inactive camera renders pauses as its `cullingMode` says. The `CullingMode` docs
+  say which cameras are tested, and that one rendering into a render target texture is not.
+- A `VFXBatch` subclass implements `resizeBuffers()` and `initialCapacity`, which the shrinking
+  instance buffers call, and creates `mesh` in `setupBuffers`; the base class no longer makes one.
+- **quarks.core's JSON and data types have no `any` left.** What changes for code that
+  compiles against them:
+  - `FunctionJSON` is the union of each generator's JSON (`ConstantValueJSON`, `GradientJSON`,
+    `EulerJSON` and the rest, grouped as `ValueGeneratorJSON`, `ColorGeneratorJSON`,
+    `RotationGeneratorJSON` and `Vector3GeneratorJSON`), with `type` as the tag. It was an open
+    record of `any`. Each generator's `toJSON` and `fromJSON` use its own type, and the
+    `…GeneratorFromJSON` readers take their group's. A generator class of your own that
+    implements `ValueGenerator` or a sibling interface writes one of these, or casts its `toJSON`;
+    no reader would know its type anyway.
+  - `BehaviorJSON` is `{type: string}`, no longer an open record, and every built-in behavior has its
+    own JSON type (`ColorOverLifeJSON`, `EmitSubParticleSystemJSON`, …) for its `toJSON` and
+    `fromJSON`. A plugin's `loadJSON` may take its own JSON interface with a `type`, as
+    `examples/src/demos/customPlugin.ts` does. An object literal passed to `BehaviorFromJSON` is
+    typed as its behavior's JSON, e.g. `const json: NoiseJSON = {type: 'Noise', …}`.
+  - `GeneratorMemory` is `number[]`. `ContinuousLinearFunction`'s values are `number`, `Vector3` or
+    `Vector4`, its `subType` follows from them, and its `fromJSON` returns the matching type for
+    the `subType`. `GradientJSON`'s `color` and `alpha` say their `subType`.
+  - `IEmitter.matrixWorld` is a `Matrix4`; `IParticleSystem.toJSON` and `IAnimationData.target` are
+    `unknown`, which a renderer narrows; `Constructable` takes `never[]` arguments.
+  - `EmitSubParticleSystem.subParticleSystem` is declared `IEmitter | string | undefined`: a loaded
+    behavior holds the uuid until the loader links it, as it always has.
+  - `Sequencer.toJSON` returns `SequencerJSON`; `Euler.fromArray` and `toArray` take numbers and an
+    order.
+  - In babylon.quarks, `ParticleSystemJSONParameters.rendererEmitterSettings` is the new
+    `RendererEmitterSettingsJSON`: a trail's `TrailSettingsJSON` or a stretched billboard's
+    settings.
+  - The `isVector3`-style flags are set on the prototypes as non-enumerable, read-only properties,
+    so they no longer show up in a `for…in` over a vector.
+- **babylon.quarks's effect format and loader have no `any` left either.** The parts of an effect
+  file have named types: `EffectDocumentJSON` for what `QuarksLoader` reads, with
+  `QuarksMaterialJSON`, `EffectGeometryJSON` (quarks' own, three.js `BufferGeometry`,
+  `PlaneGeometry` and `SphereGeometry`), `EffectImageJSON`, `QuarksPrefabJSON`,
+  `ParticleEmitterJSON` and the rest. What changes for code that compiles against them:
+  - `QuarksLoader`'s `loadFromJSON`, `parse`, `resolveResources`, `resolveLinkedResources` and
+    `resolveExternalGeometries` take the document as `unknown`, as parsed from its file. `resolveLinkedResources` takes the new `QuarksResolveOptions`.
+  - `ParticleSystem.material` and `ParticleSystemParameters.material` are a
+    `ParticleMaterialSource`: the fields a system reads from a Babylon material or a loaded
+    material record. Any Babylon material fits.
+  - `BabylonMetaData` holds `BaseTexture | null` textures, `QuarksMaterialJSON` materials and
+    `GeometryEntry` geometries; its unused maps are `unknown`.
+  - `QuarksNodeJSON` lists its fields instead of an open record, `matrix` is optional, `visible`
+    is a boolean, and it has the prefab and three.js transform fields the loader reads.
+    `QuarksEffectJSON.materials` is `QuarksMaterialJSON[]`.
+  - `ParticleSystemJSONParameters` types its generators by group (`ValueGeneratorJSON`,
+    `ColorGeneratorJSON`, …), its `shape` as `ShapeJSON`, its `behaviors` as `BehaviorJSON[]`,
+    and `instancingGeometry` as a uuid or an entry. `BurstParametersJSON` has the older
+    `cycleCount`.
+  - `QuarksPrefab.toJSON` returns a `QuarksPrefabJSON`, `ParticleEmitter.toJSON` a
+    `ParticleEmitterJSON`, and `MeshSurfaceEmitter.fromJSON` takes a `ShapeJSON`.
+  - quarks.core's `JsonMetaData.textures` may hold null.
+
+### Deprecated
+
+- `RecordState`, the sample of the old linked-list trail history. Trails record into the flat ring
+  buffer of `TrailParticle` (`historyPositions` and its siblings); nothing fills or draws the list.
+- `TrailParticle.previous`, that list, is `@internal` and out of the documented API.
+- `MeshSettings.startRotationX`, `startRotationY` and `startRotationZ`, which nothing reads, are
+  optional and deprecated; a mesh particle's start rotation about each axis is the system's
+  `startRotation`, an `EulerGenerator`.
+- `EulerGenerator.eular`, a misspelling: the Euler is `EulerGenerator.euler`, and `eular` is an
+  alias of it.
+
+### Added
+
+- **`blendCategory(settings)`** says how a blend mode's colour leaves the shader (`'straight'`,
+  `'premultiply'` or `'multiply'`) and where fog takes it (`'color'`, `'black'` or `'white'`), with
+  the `BlendCategory`, `BlendOutput` and `FogTarget` types. Opaque materials, `ALPHA_INTERPOLATE`,
+  `ALPHA_REPLACE_COLOR` and `ALPHA_DUAL_SRC0_ADD_SRC1xDST` have no coverage and stay `'straight'`.
+- The shader variants cover every blend resolve with and without fog and soft particles, so
+  `validate:shaders` compiles the new `BLEND_PREMULTIPLY`, `BLEND_MULTIPLY` and `FOG_MULTIPLY`
+  defines in GLSL and WGSL.
+- **The whole simulation core is documented.** Every vector, quaternion, matrix and math helper,
+  every shape, value, colour and rotation generator, behavior field and plugin type re-exported from
+  `quarks.core` now carries TSDoc, and `npm run docs:check` fails on one that does not, as it does
+  for the rest of the package.
+- `ContinuousLinearFunction` (the keys of a `Gradient`) and its `ObjectValueType` are exported, and
+  `Bezier` has `BezierJSON` and `BezierSplit` types for what `toJSON` and `split` return.
+- **Format warnings name the part of the file they are about**, by its JSON path
+  (`object.children[2].ps.behaviors[3]`). `QuarksLoaderOptions.onFormatWarning` receives them
+  instead of the console, and `QuarksLoaderOptions.strict` makes a load throw `QuarksFormatError`
+  for them, after reading the whole effect and freeing what it built, with every part in its
+  `problems`, to check in CI that a set of assets loads cleanly. The
+  loader's own format warnings (a newer format, an unresolved sub emitter or mesh surface link, an
+  image url that is not an image) go the same way. `readFormat`, `readFormatPart`,
+  `currentFormatPath`, `warnFormat` and `QuarksFormatError` (now defined in `quarks.core`) give plugin
+  readers and other hosts the same.
+- `BehaviorTypes.EmitSubParticleSystem` lists `inherit`, with the new `'subEmitterInherit'` field
+  type.
+- **`EffectPool.acquire` takes a placement** (`EffectPlacement`: `position`, `rotation` or
+  `rotationQuaternion`, `scaling`, `parent`), so a hit can face its surface normal or a muzzle
+  flash its barrel. Every acquire first puts the copy back to the template's transform, so a
+  rotation or scale from its last use does not stay. `acquire(position, parent)` still works, with
+  any vector that has `x`, `y` and `z`.
+- **`ParticleSystem.timeDilation`**, a runtime multiplier on `playbackSpeed` that is not part of
+  the effect (never saved, cloned or loaded), like Unreal's Custom Time Dilation or Unity's
+  `VisualEffect.playRate`: for slow motion, a pause menu, or a timeline.
+- **`QuarksPrefab.timeScale` reaches the systems**: it sets the `timeDilation` of each track's
+  system, so they slow down and speed up with the timeline; it is normalised like
+  `playbackSpeed`. Removing a system's last track sets it back to 1. Clips keep their own speed.
+- **`ParticleSystem.resume()` and `QuarksUtil.resume(root)`** undo a pause and leave a finished
+  system finished, for a pause button over a scene; the editor's transport uses them.
+- **`QuarksPrefab.autoUpdate`** advances the timeline before every render by the engine's frame
+  time, as a Unity `PlayableDirector` on Game Time does; it is turned off on dispose.
+- `removeAllEventListeners()` with no event type removes every listener.
+- A **Timeline** demo: a charge, a release burst on a window shorter than a frame and lingering
+  smoke on a `QuarksPrefab`, every other blast in slow motion.
+- **`renderFace`** on a system (`'both'`, `'front'`, `'back'`; the new `RenderFace` type), Unity's
+  Render Face and Unreal's Two Sided: a mesh particle can cull its back faces, or show only its
+  inside. `'both'` by default, as before; written to JSON only when set; mesh systems that differ
+  are batched apart; the flat render modes (billboards, stretched, beam, trail) always draw both
+  faces. The culling is per batch, so a mesh mirrored by a negative size on an odd number of axes
+  swaps which side `'front'` and `'back'` show. The editor has a Render face field for mesh systems.
+
+### Fixed
+
+- `new Gradient()` with no keys is opaque white from 0 to 1, as Unity's default gradient is. Its two
+  colour keys were both at 0 (black, then white), so it already looked white after the start; now
+  its keys span the range.
+- `PiecewiseBezier.toSVG` returns an empty path for a curve with no pieces instead of throwing.
+- A shape transform's rotation is read as a unit quaternion, and a zero one as the identity, so a
+  hand-written or rounded rotation no longer scales the shape.
+- `Rotation3DOverLife` no longer allocates a quaternion for each mesh particle it starts.
+- `BatchedRenderer.addSystem` throws for a system of another scene instead of building a batch
+  that holds two scenes' meshes and materials.
+- `configureAdaptivePerformance` keeps `minQuality` at 0.1 or more, the floor
+  `ParticleSystem.setQualityFactor` clamps to and the documented range; it allowed 0.05.
+- The 1×1 white map mesh batches share is made again after something outside disposes it, instead
+  of binding a disposed texture.
+- An env atlas that fails to build from a cube's faces warns once instead of once per system: it
+  is not tried again until the cube's faces change or `disposeEnvAtlas` is called for the cube.
+- `ApplySequences` keeps each particle's place in a `WeakMap` instead of fields added to the
+  particle, reuses that state when a pooled particle is emitted again instead of allocating two
+  vectors, and moves a particle straight to its point when a sequence's range has no length (it
+  divided by zero).
+- An `EmitSubParticleSystem` read from a file without `useVelocityAsBasis` saves without it, as a
+  default, instead of writing `false`.
+- `PiecewiseBezier.toSVG` draws the curve itself, not its sampled table.
+- A `Gradient` read from JSON without its `color` or `alpha` keys warns, and keeps the default for
+  the missing part.
+- A particle system reads its texture from the first material slot that holds a `Texture`; a cube
+  or other non-`Texture` in a slot is passed over instead of drawn as a broken 2D texture.
+- A list of an effect file (`images`, `textures`, `materials`, `geometries`, a node's `children`)
+  that is not a list, or an entry in one that is not an object, warns and is skipped, like any
+  other part the loader cannot read, instead of failing the load with a `TypeError`.
+- `ParticleSystem.fromJSON` with a material entry whose `reflectionAtlas` is a texture uuid
+  resolves it, as it does the other slots, instead of failing on the string.
+- The fragment's `alpha < 0.01` discard is right in every blend mode: under one-one or
+  premultiplied blending a discarded fragment used to be one that would still have drawn.
+- Erosion and a mesh's rim fade no longer show a hard cut under one-one and premultiplied
+  blending; they fade like under alpha blending.
+- **`Bezier.split(t)` split the curve at `1 - t`.** Its de Casteljau steps weighted the two points
+  the wrong way round, so the halves met at the mirrored point; a curve split in the editor away
+  from a segment's middle changed shape. It now splits at `t`, and both halves trace the curve.
+- `Matrix3.makeTranslation(vector)` read a `Vector2` as a number and built a broken matrix; it
+  checked a flag that `Vector2` only had as a static.
+- `Vector4.setAxisAngleFromRotationMatrix` is typed to take the `Matrix4` it reads (as three.js
+  does); it was typed `Matrix3` and read a 3×3 matrix's entries from the wrong places.
+- Shapes read out-of-range settings safely: a thickness is clamped to [0, 1] (NaN reads as 1), a negative radius,
+  width or height is read as 0, a cone's angle is clamped to [0, π/2] and a box's thickness to 1, a
+  grid's rows and columns are read as whole numbers of at least 1 (0 or Infinity gave NaN
+  positions), and a
+  short `boxThickness` array reads its missing axes as 0.
+- A donut with no tube, and a rectangle with no size, started particles with no speed; they head
+  out from the centre line, or along the edge's normal, at their start speed.
+- `AxisAngleGenerator` normalises its axis when it rotates (a zero axis is read as +z): an axis of
+  any other length gave a quaternion that was not a unit and skewed mesh particles.
+- `RandomQuatGenerator` and `RandomColorBetweenGradient` used before `startGen` read slots that
+  belong to other generators, and the gradient mix rolled a new value every frame, flickering; both
+  now roll their own slots once, as `IntervalValue` does.
+- `PiecewiseFunction.insertFunction` at a `t` outside every piece inserted at the front and
+  unsorted the pieces; it inserts in order and clamps `t` to [0, 1].
+- A circle or rectangle in `Random` mode no longer samples its sweep speed every frame, as the
+  other shapes do not; a random sweep speed no longer draws its roll, which shifts a seeded
+  effect's random sequence by one draw.
+- Shape docs give the units and axes of `arc` (radians around +z from +x), the ranges of every
+  size and thickness, and say that `RectangleEmitter` emits from the outline (Unity's Rectangle is a
+  `BoxEmitter` with no depth); the donut's `donutRadius` is the tube's radius, not the hole's.
+- `docs/FORMAT.md` gave 0.28 as the release of format version 1; 0.27.0 is. It now says how a
+  system's blend mode is read when its material entry, or the system, has none, and that
+  `ps.version` is written for three.quarks only.
+- **`QuarksPrefab` plays a window a single frame steps over.** A track shorter than a frame (a
+  release burst, say) was never entered when one update jumped from before its start to after its
+  end; its system now restarts and ends its emission once it has simulated a step (checked on
+  each update and after each render), and its clip plays and stops.
+- **An `EffectPool` never hands out a disposed copy.** A copy disposed from outside, by its own
+  `dispose()` or with a parent it was placed under, leaves the pool, which makes a new one when
+  it needs it; before, `acquire` handed out the disposed node and it never came back.
+- **`QuarksUtil.instantiate` copies meshes as meshes**, sharing the source's geometry and
+  material, where it made plain transform nodes of them; an instance of a mesh in the tree becomes
+  an instance of its copy, and a `MeshSurfaceEmitter` whose mesh is in the copied tree emits from
+  the copy. The copy holds the source's materials as it held its
+  textures, so `disposeEffect(source)` leaves a copy's meshes and materials whole.
+- **`MeshSurfaceEmitter` emits from a mesh without indices**, read as a triangle list, instead of
+  from the origin. A stray vertex count past the last whole triangle is ignored.
+- **A listener removed while an event fires no longer makes the next one skip**: the listener
+  lists are copied on write, so every listener registered when the event fired is called once,
+  and one added during it waits for the next event.
+- `particleDied` allocates nothing per death: one event object is reused, its `particle` set only
+  while the listeners run (documented, as is when a trail's death fires).
+- `EmitSubParticleSystem.reset()` drops the running sub emissions, as `ParticleSystem.restart`
+  did through a special case it no longer needs; any host gets the same reset.
+- Culling reuses its frustum planes; it allocated a new array per extra camera every frame.
+- **Instance buffers shrink.** A batch whose buffers a burst grew halves them after it has used
+  under a quarter of them for 300 renderer updates (about five seconds at 60 fps), down to where
+  it started, so one big explosion no longer holds that memory for the rest of the session.
+  Trails too.
+- A batch no longer creates a placeholder mesh that it disposes straight away.
+- `SortMode` documents that `'distance'` sorts once a frame, for the first active camera.
+
+### Internal
+
+- Tests cover the vectors, quaternions, Euler angles, matrices and math helpers, and the coverage
+  floors rise: the simulation core's from 54 % to 88 % of lines, the library's and the editor's to
+  one point under what the suites reach.
+- Behaviour tests for every shape: even filling, bounds, start speed, the rectangle's outline,
+  grid cells, out-of-range settings, JSON round trips of every field and the registry's fields.
+- Golden fixtures in `packages/babylon.quarks/test/fixtures`: effects written by three.quarks, by
+  the Unity exporter and by babylon.quarks 0.27.0. Each loads with the warnings its snapshot holds and
+  saves to the format it holds, saving is stable, and each 0.27.0 file loads as the one it was
+  written from.
+- Loaded node ids and mesh surface links live in module `WeakMap`s instead of `as any` fields on
+  nodes and systems.
+- The batch settings, their defaults and the helpers that normalise and compare them move from
+  `VFXBatch.ts` to `batchSettings.ts`, which `VFXBatch.ts` re-exports; the batch key reads them
+  there, so the build no longer reports a circular import. Exports are unchanged.
+- A clean build and install print no warnings: the core build stops passing `declarationDir`
+  without declarations, CI runs on Node 24 with current GitHub Actions, dev dependencies have no
+  known vulnerabilities, and the demo smoke test fails on a console warning as well as an error.
+- The toolchain moves to ESLint 10 (with `defineConfig` and react-hooks 7's React Compiler rules),
+  TypeScript 6, Vite 8 (Rolldown: the examples' chunks all fit under its 500 kB warning) and
+  cross-env 10. Babel stays on 7, which Jest's own preset still needs.
+- No explicit `any` is left in the repository, tests included, and ESLint now reports one as an
+  error. Tests reach private members with `obj['member']`, and use typed helpers in
+  `test/internals.ts` for shader options, empty resources, fetch responses and values the types
+  rule out.
+
+## [0.27.1] — 2026-10-23 (not published)
+
+Packaging and release checks; the runtime is the same as 0.27.0. It was never published to npm; its
+changes ship in 0.28.0.
+
+### Changed
+
+- **`@babylonjs/core` peer range is `^9.0.0`** instead of `>=9.0.0`. The package is built and
+  tested against Babylon 9; a future major is a separate release, so npm no longer accepts it
+  silently. No Babylon 10 exists yet, so no install that worked stops working.
+- **`sideEffects` names the built bundles**, the only files with import-time work (they register
+  the mesh-surface emitter with the shape table, so a bare `import 'babylon.quarks'` keeps doing
+  that); bundlers may treat everything else in the package as side-effect free.
+- The README says what `require('babylon.quarks')` needs: `@babylonjs/core` is ES modules only, so
+  CommonJS consumers need a Node that can `require` ES modules (20.19 or 22.12 and later).
+
+### Internal
+
+- **`npm run check:pack` checks that the editor moves with the library.** The editor's peer
+  dependency on `babylon.quarks` must be the library's own minor line (`~X.Y.0`), and CONTRIBUTING's
+  release steps say so: an editor published with an older range would install a babylon.quarks
+  without the API it imports.
+- The examples compile with `strict` and are part of `npm run typecheck`, in CI too.
+- The vendored `quarks.core` workspace is marked `private` (it is bundled into babylon.quarks and
+  never published on its own), points at this repository, and lists `types` first in its
+  `exports`. Its unused Babel and ESLint configs are gone, and so is `composite` in the library's
+  `tsconfig.json`, which nothing referenced.
+- The examples dev server accepts only localhost and Cloudflare quick tunnel hosts instead of
+  any `Host` header. The repository's Node requirement is 20.19, the version `check:pack`'s
+  CommonJS import needs.
+
 ## [0.27.0] — 2026-10-23
 
 The release that follows the October 2026 audit: every domain (emitters, behaviors, system and

package/README.md

@@ -32,7 +32,9 @@ High-performance particle system for [Babylon.js](https://www.babylonjs.com/). B
 npm install babylon.quarks @babylonjs/core
 ```
 
-Peer dependency: `@babylonjs/core` >= 9.
+Peer dependency: `@babylonjs/core` 9.x. The package ships ES module and CommonJS builds;
+`@babylonjs/core` is ES modules only, so `require('babylon.quarks')` needs a Node that can
+`require` ES modules (20.19 or 22.12 and later). Bundlers and `import` work everywhere.
 
 ## Quick start