babylon.quarks 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,63 @@ 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.20.0] — 2026-10-16
+
+### Added
+
+- `ParticleSystem.maxParticles` (optional, no limit when unset) caps how many particles a system
+  keeps alive, like Unity's Max Particles: emission past the cap is dropped rather than queued.
+  Saved in the effect JSON only when set.
+- quarks.core `BoxEmitter` (`box`) emits from the volume, faces or edges of a box, with an
+  optional per-axis thickness, moving particles along +Z; a box with no depth is a flat rectangle.
+  `EdgeEmitter` (`edge`) emits from a line along X, moving particles along +Y. Both match the
+  Unity shapes of the same name.
+
+- Trail settings `uvFromHead`, `colorFromParticle`, `dieWithParticle` and `recordWorldSpace`
+  (all optional, off by default) for trails that behave like Unity's: the texture runs from the
+  particle back to the tail, the whole trail takes the particle's current color, the trail
+  disappears the moment its particle dies, and a local-space system lays its trail points down in
+  world space so they streak behind a moving emitter. Saved in the effect JSON only when switched
+  on.
+- Emitter shapes take an optional local `transform` (`ShapeTransform`: position, rotation
+  quaternion, scale) like the Position / Rotation / Scale of Unity's Shape module. The spawn point
+  goes through scale, rotation and offset, and the start direction through scale and rotation
+  without changing the start speed. Every `quarks.core` shape and `MeshSurfaceEmitter` support
+  it; the shape JSON gets a `transform` entry only when one is set.
+- `ParticleSystem.pivot` (Unity's renderer Pivot): offsets billboard and stretched billboard quads
+  from their particle, in particle-size units. Billboards turn the offset with the particle and
+  move it toward the camera by z (up, for horizontal billboards); stretched billboards measure x
+  from head to tail and y across. Systems with different pivots batch separately; the shaders
+  only compile it in (`PIVOT`) when a pivot is set.
+- `ParticleSystem.flip` (Unity's renderer Flip): the fraction of billboard and stretched billboard
+  particles whose texture is mirrored along U and V, picked per particle at birth.
+- Both are saved in the effect JSON (`pivot: [x, y, z]`, `flip: [u, v]`) only when non-zero, and
+  carried by `clone()`.
+
+### Changed
+
+- `QuarksLoader` shares one `Texture` per scene between every effect that uses the same image with
+  the same sampling, and one copy of identical mesh geometry. The renderer only batches systems
+  that share these objects, so each loaded effect used to get batches of its own: 661 Epic Toon
+  FX combat effects loaded together drew 2,577 batches, and draw 180 now. Turn it off per loader
+  with `shareResources: false`; `QuarksLoader.clearSharedResources(scene)` forgets the shared set.
+
+### Fixed
+
+- `PiecewiseBezier` and `Gradient` (`quarks.core`) resampled their 257-point lookup tables on
+  every refresh, which runs every simulation step for every behavior using them. The "unchanged"
+  check compared the control points against a `Float32Array` copy, and any value float32 can't
+  hold exactly (0.2, 0.3, …) never compared equal. With such curves, 1,000 systems took 22.9 ms
+  per frame and now take 12.7 ms.
+- An idle sprite batch uploaded its cleared instance (five or six vertex buffer updates) on every
+  frame; it now does so once each time it goes empty. Systems with no particles are skipped when
+  the batch is filled, and the emitter's matrix is only fully decomposed for local-space mesh
+  particles.
+- A trail texture now reaches the end of the ribbon on frames that draw no live tip (with
+  `followLocalOrigin`, while paused, or exactly on a simulation step). The newest recorded sample
+  stopped one segment short of the texture's end, which cut the end of the texture off and made
+  it pop in and out as the tip came and went.
+
 ## [0.17.9] — 2026-07-14
 
 ### Fixed

package/README.md

@@ -8,10 +8,10 @@ High-performance particle system for [Babylon.js](https://www.babylonjs.com/). B
 
 [**Live demos**](https://soullnik.github.io/babylon.quarks-standalone/)
 
-| | | | |
-|---|---|---|---|
-| [![Muzzle Flash](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/muzzle-flash.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#MuzzleFlashDemo) | [![Explosion](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/explosion.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#ExplosionDemo) | [![Trail](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/trail.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#TrailDemo) | [![Sub Emitter](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/sub-emitter.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#SubEmitterDemo) |
-| [![Electric Ball](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/electric-ball.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#ElectricBallDemo) | [![Black Hole](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/black-hole.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#BlackHoleDemo) | [![Soft Particles](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/soft-particle.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#SoftParticleDemo) | [![Level-Up](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/level-up.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#LevelUpDemo) |
+|                                                                                                                                                                                                                                  |                                                                                                                                                                                                                         |                                                                                                                                                                                                                                   |                                                                                                                                                                                                                            |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [![Muzzle Flash](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/muzzle-flash.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#MuzzleFlashDemo)    | [![Explosion](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/explosion.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#ExplosionDemo)   | [![Trail](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/trail.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#TrailDemo)                         | [![Sub Emitter](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/sub-emitter.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#SubEmitterDemo) |
+| [![Electric Ball](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/electric-ball.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#ElectricBallDemo) | [![Black Hole](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/black-hole.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#BlackHoleDemo) | [![Soft Particles](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/soft-particle.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#SoftParticleDemo) | [![Level-Up](https://raw.githubusercontent.com/Soullnik/babylon.quarks-standalone/main/examples/public/previews/level-up.png)](https://soullnik.github.io/babylon.quarks-standalone/babylonDemo.html#LevelUpDemo)          |
 
 ## Features
 
@@ -35,7 +35,7 @@ Peer dependency: `@babylonjs/core` >= 9.
 ## Quick start
 
 ```ts
-import {Constants} from "@babylonjs/core/Engines/constants";
+import {Constants} from '@babylonjs/core/Engines/constants';
 import {
     BatchedRenderer,
     ParticleSystem,
@@ -45,10 +45,10 @@ import {
     IntervalValue,
     ConstantColor,
     Vector4,
-} from "babylon.quarks";
+} from 'babylon.quarks';
 
 // One renderer per scene; it batches all systems added to it.
-const batchRenderer = new BatchedRenderer("particles", scene);
+const batchRenderer = new BatchedRenderer('particles', scene);
 
 const system = new ParticleSystem({
     scene,
@@ -80,13 +80,13 @@ The package ships a UMD bundle (`dist/babylon.quarks.umd.min.js`, exposed as the
 ```js
 var createScene = async function () {
     var scene = new BABYLON.Scene(engine);
-    var camera = new BABYLON.ArcRotateCamera("cam", -Math.PI / 2, 1.2, 10, BABYLON.Vector3.Zero(), scene);
+    var camera = new BABYLON.ArcRotateCamera('cam', -Math.PI / 2, 1.2, 10, BABYLON.Vector3.Zero(), scene);
     camera.attachControl(canvas, true);
 
-    await BABYLON.Tools.LoadScriptAsync("https://cdn.jsdelivr.net/npm/babylon.quarks/dist/babylon.quarks.umd.min.js");
+    await BABYLON.Tools.LoadScriptAsync('https://cdn.jsdelivr.net/npm/babylon.quarks/dist/babylon.quarks.umd.min.js');
     const Q = BabylonQuarks;
 
-    const batchRenderer = new Q.BatchedRenderer("particles", scene);
+    const batchRenderer = new Q.BatchedRenderer('particles', scene);
     const system = new Q.ParticleSystem({
         scene,
         duration: 5,
@@ -98,7 +98,7 @@ var createScene = async function () {
         emissionOverTime: new Q.ConstantValue(60),
         shape: new Q.ConeEmitter({radius: 0.3, angle: 0.4}),
         renderMode: Q.RenderMode.BillBoard,
-        texture: new BABYLON.Texture("textures/flare.png", scene),
+        texture: new BABYLON.Texture('textures/flare.png', scene),
         transparent: true,
         blendMode: BABYLON.Constants.ALPHA_ADD,
     });
@@ -124,8 +124,8 @@ The same bundle works in any plain `<script>` setup alongside the global `babylo
 The library runs on Babylon's `WebGPUEngine` — its GLSL shaders are transpiled to WGSL automatically by Babylon (glslang/twgsl are fetched by Babylon on engine init). Everything except engine creation stays the same:
 
 ```ts
-import {WebGPUEngine} from "@babylonjs/core/Engines/webgpuEngine";
-import "@babylonjs/core/Engines/WebGPU/Extensions/index";
+import {WebGPUEngine} from '@babylonjs/core/Engines/webgpuEngine';
+import '@babylonjs/core/Engines/WebGPU/Extensions/index';
 
 const engine = new WebGPUEngine(canvas, {antialias: true});
 await engine.initAsync();
@@ -134,6 +134,28 @@ await engine.initAsync();
 
 All render modes (billboard, stretched billboard, mesh, trail) are validated to create WebGPU pipelines with zero validation errors. The [live demos](https://soullnik.github.io/babylon.quarks-standalone/) and the [benchmark page](https://soullnik.github.io/babylon.quarks-standalone/benchmark.html) accept `?engine=webgpu` in the URL to switch engines.
 
+## Unity-style emitter options
+
+A few optional settings mirror Shuriken so Unity exports look the same; all are off by default and
+only written to the effect JSON when set.
+
+```ts
+import {ConeEmitter, Quaternion, ShapeTransform, Vector2, Vector3} from 'quarks.core';
+
+const system = new ParticleSystem({
+    // Shape module Position / Rotation / Scale: spawn points and start directions go through it.
+    shape: new ConeEmitter({
+        radius: 0.5,
+        transform: new ShapeTransform(new Vector3(0, 1, 0), new Quaternion(), new Vector3(2, 1, 1)),
+    }),
+    // Renderer Pivot, in particle-size units (billboards and stretched billboards).
+    pivot: new Vector3(0, 0.5, 0),
+    // Renderer Flip: mirror the texture of 50% of particles along U.
+    flip: new Vector2(0.5, 0),
+    // ...
+});
+```
+
 ## Author & load effects
 
 Design an effect with one of these tools, then load the exported JSON with `QuarksLoader`:
@@ -143,11 +165,11 @@ Design an effect with one of these tools, then load the exported JSON with `Quar
 - **quarks.art** — effects exported from the [quarks.art](https://quarks.art/) editor also load fine, since it's the same JSON envelope.
 
 ```ts
-import {BatchedRenderer, QuarksLoader, QuarksUtil} from "babylon.quarks";
+import {BatchedRenderer, QuarksLoader, QuarksUtil} from 'babylon.quarks';
 
-const batchRenderer = new BatchedRenderer("particles", scene);
+const batchRenderer = new BatchedRenderer('particles', scene);
 const loader = new QuarksLoader(scene);
-const effect = await loader.load("effects/explosion.json");
+const effect = await loader.load('effects/explosion.json');
 QuarksUtil.addToBatchRenderer(effect, batchRenderer);
 QuarksUtil.play(effect);
 ```