babylon.quarks 0.17.4 → 0.17.7

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+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.17.7] — 2026-07-09
+
+### Changed
+
+- Docs reframed around the in-house `babylon.quarks-editor` effect editor and the Unity
+  exporter as the primary authoring workflows, instead of the external quarks.art editor
+  (quarks.art-exported JSON still loads fine — same format).
+- `babylon.quarks-editor`'s README now documents the `resolveTexture`/`resolveGeometry` host
+  callbacks: their per-entry-point signatures (`EffectEditorHost`/`Show()` pass a `Scene` second
+  argument, the bare `EffectEditor` component does not) and what happens when they're omitted.
+
+## [0.17.5] — 2026-07-02
+
+### Added
+
+- UMD/CDN bundle `dist/babylon.quarks.umd.min.js` exposing the `BabylonQuarks` global —
+  usable in the Babylon.js Playground and plain `<script>` setups. `quarks.core` is bundled in;
+  `@babylonjs/core` maps to the `BABYLON` global. `unpkg`/`jsdelivr` fields point to it.
+- WebGPU support validated: all render modes (billboard, stretched billboard, mesh, trail)
+  create pipelines under `WebGPUEngine` with zero validation errors (GLSL is transpiled to WGSL
+  by Babylon automatically). Documented in the README.
+- Exported types that the public API referenced but did not export:
+  `AdaptivePerformanceOptions`, `AdaptivePerformanceState`, `ParticleSystemJSONParameters`,
+  `BabylonMetaData`, `AnimationData`, `QuarksTimelineClip`, `BurstParametersJSON`.
+- API documentation generated with TypeDoc, published at
+  <https://soullnik.github.io/babylon.quarks-standalone/docs/>.
+
+### Changed
+
+- `SpriteBatch` and `QuarksLoader` pass typed arrays to Babylon `VertexData` directly instead
+  of copying them through `Array.from`.
+- `BatchedRenderer` internals use typed `ParticleSystem` narrowing instead of `as any` casts
+  (public signatures unchanged).
+
+### CI
+
+- npm publishing switched to trusted publishing (OIDC) with provenance.
+
+## [0.17.4] — 2026-05-15
+
+### Changed
+
+- `QuarksLoader` test coverage reworked; demo application restructured (new demos, hero
+  background). No functional changes to the package runtime.
+
+## [0.17.3] — 2026-05-13
+
+### Added
+
+- Adaptive performance budget controls on `BatchedRenderer`
+  (`configureAdaptivePerformance` / `disableAdaptivePerformance` / `getAdaptivePerformanceState`)
+  with per-system quality scaling.
+
+### Performance
+
+- Tightened particle system update and spawn loops.
+- Reduced hot-path allocations in renderer batches.
+- Fast trail history ring buffers for trail rendering.
+
+### Tests
+
+- Extensive coverage expansion (sprite/trail batch integration, particle system, loader,
+  prefab and utility paths) with enforced coverage thresholds.
+
+## [0.17.2] — 2026-05-11
+
+### Fixed
+
+- `QuarksLoader` marks sub-emitter systems as `onlyUsedByOther` after UUID resolution.
+- Custom blending mode handling refined.
+
+### Added
+
+- Tile blending support in shaders (additional UV calculations).
+
+## [0.17.1] — 2026-05-11
+
+### Changed
+
+- Packaging setup for the standalone monorepo (README shipped with the package,
+  tarball content checks).
+
+## [0.17.0] — 2026-05-11
+
+### Added
+
+- Initial public release: a high-performance batched particle system for Babylon.js built on
+  `quarks.core` — batched sprite/trail rendering, billboard/stretched/mesh/trail render modes,
+  soft particles, texture tile animation, sub-emitters, mesh surface emitter plugin,
+  `QuarksLoader` for quarks.art / Unity-exported JSON, `QuarksUtil` helpers.
+
+[0.17.5]: https://github.com/Soullnik/babylon.quarks-standalone/releases/tag/v0.17.5
+[0.17.4]: https://www.npmjs.com/package/babylon.quarks/v/0.17.4
+[0.17.3]: https://www.npmjs.com/package/babylon.quarks/v/0.17.3
+[0.17.2]: https://www.npmjs.com/package/babylon.quarks/v/0.17.2
+[0.17.1]: https://www.npmjs.com/package/babylon.quarks/v/0.17.1
+[0.17.0]: https://www.npmjs.com/package/babylon.quarks/v/0.17.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 soullnik
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 soullnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,33 +1,169 @@
-# babylon.quarks
-
-High-performance particle system for [Babylon.js](https://www.babylonjs.com/). Built on [quarks.art](https://quarks.art/) (`quarks.core`).
-
-## Install
-
-```bash
-npm install babylon.quarks @babylonjs/core
-```
-
-Peer dependency: `@babylonjs/core` >= 9.
-
-## Quick start
-
-```ts
-import { BatchedRenderer, ParticleSystem } from "babylon.quarks";
-
-const batchRenderer = new BatchedRenderer("particles", scene);
-// Create ParticleSystem instances, add them to your scene logic, then each frame:
-// batchRenderer.update(deltaTimeInSeconds);
-```
-
-See the [examples app](https://github.com/Soullnik/babylon.quarks-standalone/tree/main/examples) in the monorepo for interactive demos and usage patterns.
-
-## Links
-
-- [npm package](https://www.npmjs.com/package/babylon.quarks)
-- [Source (monorepo)](https://github.com/Soullnik/babylon.quarks-standalone/tree/main/packages/babylon.quarks)
-- [Issues](https://github.com/Soullnik/babylon.quarks-standalone/issues)
-
-## License
-
-MIT
+# babylon.quarks
+
+[![npm version](https://img.shields.io/npm/v/babylon.quarks)](https://www.npmjs.com/package/babylon.quarks)
+[![CI](https://github.com/Soullnik/babylon.quarks-standalone/actions/workflows/ci.yml/badge.svg)](https://github.com/Soullnik/babylon.quarks-standalone/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Soullnik/babylon.quarks-standalone/blob/main/LICENSE)
+
+High-performance particle system for [Babylon.js](https://www.babylonjs.com/). Built on `quarks.core` (historically derived from [quarks.art](https://quarks.art/) / three.quarks).
+
+[**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) |
+
+## Features
+
+- **Batched rendering** — heterogeneous particle systems share draw calls via `BatchedRenderer`.
+- **Render modes** — billboard, vertical/horizontal billboard, stretched billboard, mesh particles, and **trails** (not available in Babylon's built-in particle systems).
+- **Sub-emitters** and a rich set of composable behaviors (color/size/speed over life, noise turbulence, forces, and more from `quarks.core`).
+- **Soft particles**, texture tile animation with blending, custom blend functions.
+- **Visual authoring** — design effects in our own [effect editor](https://soullnik.github.io/babylon.quarks-standalone/editor.html) or export them from Unity, then load with `QuarksLoader` (quarks.art-exported JSON also works — same format).
+- **Cross-engine format** — the same effect JSON runs in three.js (three.quarks) and Babylon.js.
+- **Adaptive performance** — optional frame-budget quality scaling built into `BatchedRenderer`.
+- **WebGL and WebGPU** — runs on both Babylon engines; shaders are transpiled to WGSL automatically.
+
+## Install
+
+```bash
+npm install babylon.quarks @babylonjs/core
+```
+
+Peer dependency: `@babylonjs/core` >= 9.
+
+## Quick start
+
+```ts
+import {Constants} from "@babylonjs/core/Engines/constants";
+import {
+    BatchedRenderer,
+    ParticleSystem,
+    PointEmitter,
+    RenderMode,
+    ConstantValue,
+    IntervalValue,
+    ConstantColor,
+    Vector4,
+} from "babylon.quarks";
+
+// One renderer per scene; it batches all systems added to it.
+const batchRenderer = new BatchedRenderer("particles", scene);
+
+const system = new ParticleSystem({
+    scene,
+    duration: 5,
+    looping: true,
+    startLife: new IntervalValue(4, 5),
+    startSpeed: new ConstantValue(1),
+    startSize: new IntervalValue(1, 2),
+    startColor: new ConstantColor(new Vector4(1, 1, 1, 1)),
+    emissionOverTime: new ConstantValue(20),
+    shape: new PointEmitter(),
+    renderMode: RenderMode.BillBoard,
+    texture: myParticleTexture,
+    transparent: true,
+    blendMode: Constants.ALPHA_COMBINE,
+});
+batchRenderer.addSystem(system);
+
+// Advance the simulation every frame:
+scene.onBeforeRenderObservable.add(() => {
+    batchRenderer.update(scene.getEngine().getDeltaTime() / 1000);
+});
+```
+
+## Use in the Babylon.js Playground
+
+The package ships a UMD bundle (`dist/babylon.quarks.umd.min.js`, exposed as the `BabylonQuarks` global) that can be loaded straight from a CDN — no build step needed. Paste this into the [Playground](https://playground.babylonjs.com/):
+
+```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);
+    camera.attachControl(canvas, true);
+
+    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 system = new Q.ParticleSystem({
+        scene,
+        duration: 5,
+        looping: true,
+        startLife: new Q.IntervalValue(2, 3),
+        startSpeed: new Q.ConstantValue(2),
+        startSize: new Q.IntervalValue(0.5, 1),
+        startColor: new Q.ConstantColor(new Q.Vector4(1, 0.6, 0.2, 1)),
+        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),
+        transparent: true,
+        blendMode: BABYLON.Constants.ALPHA_ADD,
+    });
+    batchRenderer.addSystem(system);
+
+    scene.onBeforeRenderObservable.add(() => {
+        batchRenderer.update(engine.getDeltaTime() / 1000);
+    });
+
+    return scene;
+};
+```
+
+The same bundle works in any plain `<script>` setup alongside the global `babylon.js` build:
+
+```html
+<script src="https://cdn.babylonjs.com/babylon.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/babylon.quarks/dist/babylon.quarks.umd.min.js"></script>
+```
+
+## WebGPU
+
+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";
+
+const engine = new WebGPUEngine(canvas, {antialias: true});
+await engine.initAsync();
+// Scene + BatchedRenderer setup is identical to WebGL.
+```
+
+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.
+
+## Author & load effects
+
+Design an effect with one of these tools, then load the exported JSON with `QuarksLoader`:
+
+- **[Effect editor](https://soullnik.github.io/babylon.quarks-standalone/editor.html)** — our in-house Shuriken-style editor ([`babylon.quarks-editor`](https://www.npmjs.com/package/babylon.quarks-editor), embeddable in your own app).
+- **[Unity exporter](https://github.com/Soullnik/babylon.quarks-standalone/tree/main/tools/unity-quarks-exporter)** — a Unity Editor tool that exports Shuriken Particle Systems to the same JSON format.
+- **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";
+
+const batchRenderer = new BatchedRenderer("particles", scene);
+const loader = new QuarksLoader(scene);
+const effect = await loader.load("effects/explosion.json");
+QuarksUtil.addToBatchRenderer(effect, batchRenderer);
+QuarksUtil.play(effect);
+```
+
+See the [examples app](https://github.com/Soullnik/babylon.quarks-standalone/tree/main/examples) in the monorepo for 18 interactive demos and usage patterns.
+
+## Links
+
+- [API documentation](https://soullnik.github.io/babylon.quarks-standalone/docs/)
+- [Changelog](https://github.com/Soullnik/babylon.quarks-standalone/blob/main/packages/babylon.quarks/CHANGELOG.md)
+- [Contributing](https://github.com/Soullnik/babylon.quarks-standalone/blob/main/CONTRIBUTING.md)
+- [npm package](https://www.npmjs.com/package/babylon.quarks)
+- [Source (monorepo)](https://github.com/Soullnik/babylon.quarks-standalone/tree/main/packages/babylon.quarks)
+- [Roadmap](https://github.com/Soullnik/babylon.quarks-standalone/blob/main/ROADMAP.md)
+- [Issues](https://github.com/Soullnik/babylon.quarks-standalone/issues)
+
+## License
+
+MIT