babylon.quarks 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,85 @@ 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.21.0] — 2026-10-16
+
+### Added
+
+- `QuarksResourceResolver` on `QuarksLoaderOptions` (`resolve` / `fetchJson`) so File pickers,
+  CDN layouts and virtual FS backends can resolve relative texture and geometry links without
+  calling `resolveExternalGeometries` by hand.
+- `loadFromJSON(json, baseUrl?)` — same pipeline as `load(url)` when the effect document is
+  already in memory; `resolveResources` / static `resolveLinkedResources` for prepare-only.
+- `loadAll(urls)` and `loadFromJSONAll(entries)` for battle / level preload: fetch effect docs
+  (optional `concurrency`), resolve every linked geometry/image across the pack so shared asset
+  urls hit a per-scene fetch cache once, then parse. `continueOnError` and `onProgress` (once per
+  settled effect) supported; without `continueOnError` the return type is `TransformNode[]`.
+- `QuarksLoader.joinUrl` for portable baseUrl joining (data/blob/absolute urls left alone).
+
+### Changed
+
+- `load(url)` goes through `loadFromJSON` after fetching the effect JSON. Geometry JSON fetches
+  are deduped per scene; inlined array fields are copied so cached documents are not aliased
+  across effects. Prefer `load` / `loadFromJSON` / `resolveResources` over
+  `resolveExternalGeometries` (kept for compatibility).
+
+## [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

@@ -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`:
@@ -148,6 +170,8 @@ import {BatchedRenderer, QuarksLoader, QuarksUtil} from 'babylon.quarks';
 const batchRenderer = new BatchedRenderer('particles', scene);
 const loader = new QuarksLoader(scene);
 const effect = await loader.load('effects/explosion.json');
+// Or preload a battle pack — shared textures/geometries fetch once:
+// const roots = await loader.loadAll(['fx/hit.json', 'fx/explosion.json'], { concurrency: 6 });
 QuarksUtil.addToBatchRenderer(effect, batchRenderer);
 QuarksUtil.play(effect);
 ```