babylon.quarks 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.19.0",
+    "version": "0.21.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",

package/src/BatchedRenderer.ts

@@ -2,7 +2,7 @@ import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
-import {EmitSubParticleSystem, IParticleSystem} from 'quarks.core';
+import {EmitSubParticleSystem, IParticleSystem, Vector3} from 'quarks.core';
 import {ParticleSystem} from './ParticleSystem';
 import {SpriteBatch} from './SpriteBatch';
 import {TrailBatch} from './TrailBatch';
@@ -47,6 +47,14 @@ export interface VFXBatchSettings {
      */
     reflectionAtlas: BaseTexture | null;
     layerMask: number;
+    /**
+     * Offset of billboard quads from their particle, in particle-size units
+     * (Unity's renderer Pivot). On billboards x/y move the quad in its own plane
+     * before it is rotated and z moves it toward the camera (up for horizontal
+     * billboards). On stretched billboards x runs from the head to the tail and
+     * y across, and z is unused. Absent or zero: no offset. Meshes ignore it.
+     */
+    pivot?: Vector3;
 }
 
 export interface AdaptivePerformanceOptions {
@@ -57,6 +65,11 @@ export interface AdaptivePerformanceOptions {
     increaseStep: number;
 }
 
+/** True when both pivots put the quad in the same place; a missing pivot is zero. */
+function pivotEqual(a: Vector3 | undefined, b: Vector3 | undefined): boolean {
+    return (a?.x ?? 0) === (b?.x ?? 0) && (a?.y ?? 0) === (b?.y ?? 0) && (a?.z ?? 0) === (b?.z ?? 0);
+}
+
 /** True when both face lists are the same six texture references (or both empty). */
 function reflectionFacesEqual(a: BaseTexture[] | null | undefined, b: BaseTexture[] | null | undefined): boolean {
     if (a === b) {
@@ -147,7 +160,8 @@ export class BatchedRenderer extends TransformNode {
             a.vTileCount === b.vTileCount &&
             a.instancingGeometry === b.instancingGeometry &&
             a.renderOrder === b.renderOrder &&
-            a.layerMask === b.layerMask
+            a.layerMask === b.layerMask &&
+            pivotEqual(a.pivot, b.pivot)
         );
     }
 

package/src/MeshSurfaceEmitter.ts

@@ -1,6 +1,6 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
-import {EmitterShape, IParticleSystem, Particle, Plugin, ShapeJSON, Vector3} from 'quarks.core';
+import {EmitterShape, IParticleSystem, Particle, Plugin, ShapeJSON, ShapeTransform, Vector3} from 'quarks.core';
 
 export class MeshSurfaceEmitter implements EmitterShape {
     type = 'mesh_surface';
@@ -10,6 +10,8 @@ export class MeshSurfaceEmitter implements EmitterShape {
     private _positions?: Float32Array;
     private _indices?: Uint32Array | Int32Array;
     private _meshReferenceId?: string;
+    /** Offset, rotation and scale of the mesh within the particle system. */
+    transform?: ShapeTransform;
 
     get mesh() {
         return this._mesh;
@@ -53,8 +55,9 @@ export class MeshSurfaceEmitter implements EmitterShape {
         }
     }
 
-    constructor(mesh?: Mesh, meshReferenceId?: string) {
+    constructor(mesh?: Mesh, meshReferenceId?: string, transform?: ShapeTransform) {
         this._meshReferenceId = meshReferenceId;
+        this.transform = transform;
         if (mesh) this.mesh = mesh;
     }
 
@@ -62,6 +65,7 @@ export class MeshSurfaceEmitter implements EmitterShape {
         if (!this._positions || !this._indices) {
             p.position.set(0, 0, 0);
             p.velocity.set(0, 0, 1).multiplyScalar(p.startSpeed);
+            this.transform?.apply(p);
             return;
         }
 
@@ -107,21 +111,23 @@ export class MeshSurfaceEmitter implements EmitterShape {
         const nz = bx * cy - by * cx;
         const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
         p.velocity.set(nx / len, ny / len, nz / len).multiplyScalar(p.startSpeed);
+        this.transform?.apply(p);
     }
 
     toJSON(): ShapeJSON {
         return {
             type: 'mesh_surface',
             mesh: this._mesh ? (this._mesh as any).uniqueId?.toString() : (this._meshReferenceId ?? ''),
+            ...ShapeTransform.toShapeJSON(this.transform),
         };
     }
 
     static fromJSON(json: any): MeshSurfaceEmitter {
-        return new MeshSurfaceEmitter(undefined, json?.mesh);
+        return new MeshSurfaceEmitter(undefined, json?.mesh, ShapeTransform.fromJSON(json?.transform));
     }
 
     clone(): EmitterShape {
-        return new MeshSurfaceEmitter(this._mesh, this._meshReferenceId);
+        return new MeshSurfaceEmitter(this._mesh, this._meshReferenceId, this.transform?.clone());
     }
 
     update(_system: IParticleSystem, _delta: number): void {}

package/src/ParticleSystem.ts

@@ -38,6 +38,7 @@ import {
     TrailSettings,
     ValueGenerator,
     ValueGeneratorFromJSON,
+    Vector2,
     Vector3,
     Vector3Generator,
     Vector4,
@@ -83,6 +84,16 @@ function fallbackUVsForPositions(positions: Float32Array): Float32Array {
 }
 const DEFAULT_INDICES = new Uint32Array([0, 1, 2, 0, 2, 3]);
 
+/** The optional trail flags that are switched on, so JSON and clones only carry the ones in use. */
+function trailFlags(settings: TrailSettings | undefined): Partial<TrailSettings> {
+    const flags: Partial<TrailSettings> = {};
+    if (settings?.uvFromHead) flags.uvFromHead = true;
+    if (settings?.colorFromParticle) flags.colorFromParticle = true;
+    if (settings?.dieWithParticle) flags.dieWithParticle = true;
+    if (settings?.recordWorldSpace) flags.recordWorldSpace = true;
+    return flags;
+}
+
 export interface ParticleSystemParameters {
     autoDestroy?: boolean;
     looping?: boolean;
@@ -99,6 +110,8 @@ export interface ParticleSystemParameters {
     emissionOverTime?: ValueGenerator | FunctionValueGenerator;
     emissionOverDistance?: ValueGenerator | FunctionValueGenerator;
     emissionBursts?: Array<BurstParameters>;
+    /** Most particles alive at once; emission past it is dropped. Leave unset for no limit. */
+    maxParticles?: number;
     onlyUsedByOther?: boolean;
     behaviors?: Array<Behavior>;
     instancingGeometry?: Float32Array;
@@ -125,6 +138,10 @@ export interface ParticleSystemParameters {
     depthWrite?: boolean;
     alphaTest?: number;
     layerMask?: number;
+    /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
+    pivot?: Vector3;
+    /** Fraction of billboard particles mirrored along U (x) and V (y), see {@link ParticleSystem.flip}. */
+    flip?: Vector2;
     scene?: Scene;
 }
 
@@ -152,6 +169,7 @@ export interface ParticleSystemJSONParameters {
     emissionOverTime: FunctionJSON;
     emissionOverDistance: FunctionJSON;
     emissionBursts?: Array<BurstParametersJSON>;
+    maxParticles?: number;
     onlyUsedByOther: boolean;
     rendererEmitterSettings: RendererEmitterSettings;
     instancingGeometry?: any;
@@ -175,6 +193,10 @@ export interface ParticleSystemJSONParameters {
     alphaTest?: number;
     behaviors: Array<any>;
     worldSpace: boolean;
+    /** `[x, y, z]`; written only when non-zero. */
+    pivot?: number[];
+    /** `[u, v]`; written only when non-zero. */
+    flip?: number[];
 }
 
 export interface BabylonMetaData {
@@ -203,9 +225,17 @@ export class ParticleSystem implements IParticleSystem {
     startColor: ColorGenerator | FunctionColorGenerator;
     startTileIndex: ValueGenerator;
     rendererEmitterSettings: RendererEmitterSettings;
+    /**
+     * Fraction of billboard particles mirrored along U (x) and V (y), each
+     * picked at random when the particle is born — Unity's renderer Flip.
+     * Undefined: nothing is mirrored. Meshes ignore it.
+     */
+    flip?: Vector2;
     emissionOverTime: ValueGenerator | FunctionValueGenerator;
     emissionOverDistance: ValueGenerator | FunctionValueGenerator;
     emissionBursts: Array<BurstParameters>;
+    /** Most particles alive at once (Unity's Max Particles); emission past it is dropped. Undefined means no limit. */
+    maxParticles?: number;
     onlyUsedByOther: boolean;
     worldSpace: boolean;
     particleNum: number;
@@ -356,6 +386,28 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
+    /**
+     * Billboard pivot in particle-size units (Unity's renderer Pivot), see
+     * {@link VFXBatchSettings.pivot}. Assign a new vector to change it: editing
+     * the returned one in place does not reach the renderer.
+     */
+    get pivot(): Vector3 | undefined {
+        return this.rendererSettings.pivot;
+    }
+
+    set pivot(v: Vector3 | undefined) {
+        this.rendererSettings.pivot = ParticleSystem.nonZeroPivot(v);
+        this.neededToUpdateRender = true;
+    }
+
+    private static nonZeroPivot(v: Vector3 | undefined): Vector3 | undefined {
+        return v && (v.x !== 0 || v.y !== 0 || v.z !== 0) ? v.clone() : undefined;
+    }
+
+    private static nonZeroFlip(v: Vector2 | undefined): Vector2 | undefined {
+        return v && (v.x > 0 || v.y > 0) ? v.clone() : undefined;
+    }
+
     get softNearFade() {
         return this.rendererSettings.softNearFade;
     }
@@ -468,6 +520,7 @@ export class ParticleSystem implements IParticleSystem {
         this.emissionOverTime = parameters.emissionOverTime ?? new ConstantValue(10);
         this.emissionOverDistance = parameters.emissionOverDistance ?? new ConstantValue(0);
         this.emissionBursts = parameters.emissionBursts ?? [];
+        this.maxParticles = parameters.maxParticles;
         this.onlyUsedByOther = parameters.onlyUsedByOther ?? false;
         this.emitterShape = parameters.shape ?? new SphereEmitter();
         this.behaviors = parameters.behaviors ?? [];
@@ -509,7 +562,9 @@ export class ParticleSystem implements IParticleSystem {
             reflectionFaces: null,
             reflectionAtlas: null,
             layerMask: parameters.layerMask ?? 0x0fffffff,
+            pivot: ParticleSystem.nonZeroPivot(parameters.pivot),
         };
+        this.flip = ParticleSystem.nonZeroFlip(parameters.flip);
         if (this.rendererSettings.renderMode === RenderMode.Mesh && !this.rendererSettings.instancingNormals) {
             this.rendererSettings.instancingNormals = ParticleSystem.createFallbackNormals(
                 this.rendererSettings.instancingGeometry
@@ -724,6 +779,10 @@ export class ParticleSystem implements IParticleSystem {
         const timeRatio = emissionState.time / this.duration;
         const trailSettings = isTrailMode ? (this.rendererEmitterSettings as TrailSettings) : undefined;
         const followLocalOrigin = Boolean(trailSettings?.followLocalOrigin);
+        if (this.maxParticles !== undefined) {
+            // Like Unity, a full system skips the particles it has no room for rather than queueing them.
+            count = Math.min(count, Math.max(0, this.maxParticles - this.particleNum));
+        }
 
         for (let i = 0; i < count; i++) {
             emissionState.burstParticleIndex = i;
@@ -795,6 +854,9 @@ export class ParticleSystem implements IParticleSystem {
                     // Set until a turning behavior says otherwise, so the
                     // renderer never carries a recycled particle's old spin.
                     sprite.angularVelocity = 0;
+                    const flip = this.flip;
+                    sprite.flip =
+                        flip === undefined ? 0 : (Math.random() < flip.x ? 1 : 0) | (Math.random() < flip.y ? 2 : 0);
                 }
             } else if (trailSettings) {
                 const trail = particle as TrailParticle;
@@ -1084,6 +1146,33 @@ export class ParticleSystem implements IParticleSystem {
             }
         }
 
+        // Newborns were snapshotted above with spawn size/color (startSize /
+        // startColor) before SizeOverLife / ColorOverLife ran. That false jump
+        // is then extrapolated by the renderer when simulationResidual is
+        // negative (common with rounded fixed-step) and flashes the start
+        // appearance at the emitter. Collapse it so birth matches t=0 on the
+        // curves. Age is still 0 here — integration below ages them.
+        if (particleCount > 0) {
+            const prevSize = columns.previousSize;
+            const curSize = columns.size;
+            const prevColor = columns.previousColor;
+            const curColor = columns.color;
+            const scalars = columns.scalars;
+            const stride = ParticleStore.SCALAR_STRIDE;
+            for (let i = 0, o3 = 0, o4 = 0, s = 0; i < particleCount; i++, o3 += 3, o4 += 4, s += stride) {
+                if (scalars[s + ParticleStore.AGE] !== 0) {
+                    continue;
+                }
+                prevSize[o3] = curSize[o3];
+                prevSize[o3 + 1] = curSize[o3 + 1];
+                prevSize[o3 + 2] = curSize[o3 + 2];
+                prevColor[o4] = curColor[o4];
+                prevColor[o4 + 1] = curColor[o4 + 1];
+                prevColor[o4 + 2] = curColor[o4 + 2];
+                prevColor[o4 + 3] = curColor[o4 + 3];
+            }
+        }
+
         const followLocalOrigin = isTrailMode && (this.rendererEmitterSettings as TrailSettings).followLocalOrigin;
         if (followLocalOrigin) {
             const emitterMatrix = this.emitter.matrixWorld;
@@ -1114,8 +1203,30 @@ export class ParticleSystem implements IParticleSystem {
         }
 
         if (isTrailMode) {
+            const trailSettings = this.rendererEmitterSettings as TrailSettings;
+            const dieWithParticle = trailSettings.dieWithParticle;
+            // A world-space system records world positions already.
+            const recordWorldSpace = trailSettings.recordWorldSpace && !this.worldSpace;
+            const emitterMatrix = this.emitter.matrixWorld;
             for (let i = 0; i < particleCount; i++) {
-                (particles[i] as TrailParticle).update();
+                const trail = particles[i] as TrailParticle;
+                // Emptying the history lets the removal pass below take the
+                // particle this same step.
+                if (dieWithParticle && trail.age >= trail.life) {
+                    trail.resetHistory();
+                    continue;
+                }
+                trail.update();
+                // update() wrote a sample only while the particle is alive.
+                if (recordWorldSpace && trail.age <= trail.life) {
+                    const offset = ((trail.historyHead + trail.historyCapacity - 1) % trail.historyCapacity) * 3;
+                    const positions = trail.historyPositions;
+                    tempV.set(positions[offset], positions[offset + 1], positions[offset + 2]);
+                    tempV.applyMatrix4(trail.parentMatrix ?? emitterMatrix);
+                    positions[offset] = tempV.x;
+                    positions[offset + 1] = tempV.y;
+                    positions[offset + 2] = tempV.z;
+                }
             }
         }
 
@@ -1281,6 +1392,7 @@ export class ParticleSystem implements IParticleSystem {
                 interval: burst.interval,
                 cycle: burst.cycle,
             })),
+            ...(this.maxParticles !== undefined ? {maxParticles: this.maxParticles} : {}),
             onlyUsedByOther: this.onlyUsedByOther,
             instancingGeometry: geometryUUID,
             renderMode: this.renderMode,
@@ -1302,6 +1414,8 @@ export class ParticleSystem implements IParticleSystem {
             alphaTest: this.rendererSettings.materialAlphaTest,
             behaviors: this.behaviors.map((b) => b.toJSON()),
             worldSpace: this.worldSpace,
+            ...(this.pivot ? {pivot: [this.pivot.x, this.pivot.y, this.pivot.z]} : {}),
+            ...(this.flip ? {flip: [this.flip.x, this.flip.y]} : {}),
         };
     }
 
@@ -1321,6 +1435,7 @@ export class ParticleSystem implements IParticleSystem {
                         ? ValueGeneratorFromJSON(trailSettings.startLength)
                         : new ConstantValue(30),
                 followLocalOrigin: trailSettings?.followLocalOrigin ?? false,
+                ...trailFlags(trailSettings),
             };
         } else if (json.renderMode === RenderMode.StretchedBillBoard) {
             rendererEmitterSettings = {...(json.rendererEmitterSettings ?? {})};
@@ -1371,6 +1486,7 @@ export class ParticleSystem implements IParticleSystem {
                 interval: burst.interval ?? 0.1,
                 cycle: burst.cycle ?? burst.cycleCount ?? 1,
             })),
+            maxParticles: typeof json.maxParticles === 'number' ? json.maxParticles : undefined,
             onlyUsedByOther: json.onlyUsedByOther,
             instancingGeometry: resolvedGeometry.positions,
             instancingIndices: resolvedGeometry.indices,
@@ -1399,6 +1515,8 @@ export class ParticleSystem implements IParticleSystem {
             behaviors: [],
             worldSpace: json.worldSpace,
             layerMask: json.layers,
+            pivot: json.pivot ? new Vector3(json.pivot[0] ?? 0, json.pivot[1] ?? 0, json.pivot[2] ?? 0) : undefined,
+            flip: json.flip ? new Vector2(json.flip[0] ?? 0, json.flip[1] ?? 0) : undefined,
         });
         ps.behaviors = (json.behaviors ?? [])
             .map((behaviorJson) => {
@@ -1432,6 +1550,7 @@ export class ParticleSystem implements IParticleSystem {
             return {
                 startLength: (this.rendererEmitterSettings as TrailSettings).startLength.toJSON(),
                 followLocalOrigin: (this.rendererEmitterSettings as TrailSettings).followLocalOrigin,
+                ...trailFlags(this.rendererEmitterSettings as TrailSettings),
             };
         }
         if (this.renderMode === RenderMode.StretchedBillBoard) {
@@ -1594,6 +1713,7 @@ export class ParticleSystem implements IParticleSystem {
             rendererEmitterSettings = {
                 startLength: (this.rendererEmitterSettings as TrailSettings).startLength.clone(),
                 followLocalOrigin: (this.rendererEmitterSettings as TrailSettings).followLocalOrigin,
+                ...trailFlags(this.rendererEmitterSettings as TrailSettings),
             };
         } else if (this.renderMode === RenderMode.StretchedBillBoard) {
             rendererEmitterSettings = {
@@ -1619,6 +1739,7 @@ export class ParticleSystem implements IParticleSystem {
             emissionOverTime: this.emissionOverTime.clone(),
             emissionOverDistance: this.emissionOverDistance.clone(),
             emissionBursts: this.emissionBursts.map((b) => ({...b})),
+            maxParticles: this.maxParticles,
             onlyUsedByOther: this.onlyUsedByOther,
             instancingGeometry: this.rendererSettings.instancingGeometry,
             instancingIndices: this.rendererSettings.instancingIndices,
@@ -1644,6 +1765,8 @@ export class ParticleSystem implements IParticleSystem {
             depthWrite: this.rendererSettings.materialDepthWrite,
             alphaTest: this.rendererSettings.materialAlphaTest,
             layerMask: this.rendererSettings.layerMask,
+            pivot: this.pivot,
+            flip: this.flip,
             scene: this.emitter.getScene(),
         });
     }