babylon.quarks 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -4,6 +4,431 @@ 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.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