babylon.quarks 0.27.0 → 0.28.0

package/src/ParticleEmitter.ts

@@ -2,6 +2,29 @@ import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Matrix4, SerializationOptions} from 'quarks.core';
 import {quarksNodeId} from './nodeId';
+import type {BabylonMetaData} from './system/types';
+
+/** A {@link ParticleEmitter} as its `toJSON` writes it: the node, its transform and its system. */
+export interface ParticleEmitterJSON {
+    /** The node's id in the effect. */
+    uuid: string;
+    /** Always `'ParticleEmitter'`. */
+    type: 'ParticleEmitter';
+    /** The node's name. */
+    name: string;
+    /** `[x, y, z]`. */
+    position: number[];
+    /** Euler angles `[x, y, z]` in radians. */
+    rotation: number[];
+    /** `[x, y, z, w]`, when the node has a rotation quaternion. */
+    quaternion?: number[];
+    /** `[x, y, z]`. */
+    scale: number[];
+    /** The node's own enabled flag. */
+    visible: boolean;
+    /** The system's JSON, as its `toJSON` writes it. */
+    ps: unknown;
+}
 
 /**
  * Above 0 while a particle system disposes its own emitter (`ParticleSystem.dispose()`, which
@@ -117,8 +140,13 @@ export class ParticleEmitter extends TransformNode {
         return clonedEmitter;
     }
 
-    /** The node and its system in effect-file form; `serializeEffect` writes whole effects. @internal */
-    toJSON(meta?: any, options: SerializationOptions = {}): any {
+    /**
+     * The node and its system in effect-file form: one entry of an effect file's `object` tree,
+     * without its children. Geometry, materials and textures go into `meta` when it is given.
+     * `visible` is the node's own enabled flag, not the one it inherits from its parents. To write
+     * a whole effect, with its children and resources, use `serializeEffect`.
+     */
+    toJSON(meta?: BabylonMetaData, options: SerializationOptions = {}): ParticleEmitterJSON {
         return {
             uuid: quarksNodeId(this),
             type: 'ParticleEmitter',
@@ -134,7 +162,7 @@ export class ParticleEmitter extends TransformNode {
                   ]
                 : undefined,
             scale: [this.scaling.x, this.scaling.y, this.scaling.z],
-            visible: this.isEnabled(),
+            visible: this.isEnabled(false),
             ps: this.system.toJSON(meta, options),
         };
     }

package/src/ParticleSystem.ts

@@ -23,6 +23,7 @@ import {
     ParticleSystemEventType,
     Quaternion,
     RandomSource,
+    readFormatPart,
     RendererEmitterSettings,
     RotationGenerator,
     SerializationOptions,
@@ -63,7 +64,7 @@ import {
     runBehaviorSteps,
     snapshotPreviousState,
 } from './system/integrate';
-import {liveAtlas, MaterialOverrides, resolveMaterialSettings} from './system/materialResolve';
+import {liveAtlas, MaterialOverrides, ParticleMaterialSource, resolveMaterialSettings} from './system/materialResolve';
 import {
     DEFAULT_SOFT_FAR_FADE,
     nonZeroFlip,
@@ -74,6 +75,7 @@ import {
     validCullingMode,
     validLighting,
     validMaxParticles,
+    validRenderFace,
     validSoftFade,
     validSortMode,
     validTileCount,
@@ -101,6 +103,7 @@ import {
     ParticleGradientMap,
     ParticleUVDistortion,
     ParticleUVDistortionOptions,
+    RenderFace,
     RenderMode,
     SortMode,
     TextureUV,
@@ -295,7 +298,7 @@ export class ParticleSystem implements IParticleSystem {
     private readonly emission = new EmissionController(this, this.spawner);
     private readonly events = new EventDispatcher();
     private readonly layerMaskProxy: {mask: number};
-    private materialRef: any = null;
+    private materialRef: ParticleMaterialSource | null = null;
     private sceneRef: Scene | undefined;
     private qualityFactor = 1;
     private destroyed = false;
@@ -395,11 +398,11 @@ export class ParticleSystem implements IParticleSystem {
      * is not drawn with; particles always use quarks' own shaders. Null leaves the settings as they
      * are.
      */
-    get material(): any {
+    get material(): ParticleMaterialSource | null {
         return this.materialRef;
     }
 
-    set material(material: any) {
+    set material(material: ParticleMaterialSource | null) {
         this.materialRef = material;
         this.applyMaterialSettings(material);
     }
@@ -473,6 +476,21 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
+    /**
+     * Which faces of a mesh particle are drawn (Unity's Render Face): `'both'` by default,
+     * `'front'` to cull the back faces of a closed mesh, `'back'` to see only its inside. Applies
+     * to the Mesh render mode; the other modes draw both faces. See {@link RenderFace}. Saved in
+     * the effect JSON only when not `'both'`.
+     */
+    get renderFace(): RenderFace {
+        return this.rendererSettings.renderFace ?? 'both';
+    }
+
+    set renderFace(face: RenderFace) {
+        this.rendererSettings.renderFace = validRenderFace(face);
+        this.neededToUpdateRender = true;
+    }
+
     /**
      * Smallest size a billboard or stretched particle is drawn at, as a
      * fraction of the viewport height (Unity's Min Particle Size); 0 by
@@ -946,6 +964,24 @@ export class ParticleSystem implements IParticleSystem {
 
     private playbackSpeedValue = 1;
 
+    /**
+     * A runtime multiplier on {@link playbackSpeed} that is not part of the effect: what a
+     * timeline, a slow-motion moment or a game's pause menu sets on a system it plays, like
+     * Unreal's Custom Time Dilation or Unity's `VisualEffect.playRate`. The system runs at
+     * `playbackSpeed * timeDilation`. 1 by default; never saved, cloned or loaded. A negative,
+     * NaN or infinite value is read as 0. A `QuarksPrefab` sets it to its `timeScale` on the systems of
+     * its tracks.
+     */
+    get timeDilation(): number {
+        return this.timeDilationValue;
+    }
+
+    set timeDilation(dilation: number) {
+        this.timeDilationValue = dilation > 0 && dilation < Infinity ? dilation : 0;
+    }
+
+    private timeDilationValue = 1;
+
     /**
      * Runtime multiplier on how many particles the system emits: bursts,
      * emission over time and over distance alike. Unlike
@@ -1125,6 +1161,7 @@ export class ParticleSystem implements IParticleSystem {
             layerMask: parameters.layerMask ?? 0x0fffffff,
             pivot: nonZeroPivot(parameters.pivot),
             sortMode: validSortMode(parameters.sortMode),
+            renderFace: validRenderFace(parameters.renderFace),
             minParticleSize: Math.max(0, parameters.minParticleSize ?? 0),
             maxParticleSize: parameters.maxParticleSize ?? Infinity,
             renderingGroupId: parameters.renderingGroupId ?? 0,
@@ -1184,7 +1221,7 @@ export class ParticleSystem implements IParticleSystem {
      * ran) while the system still uses it, drops it and builds a new one if the cube is still alive,
      * so the batch never samples a disposed texture.
      */
-    private watchEnvAtlas(atlas: BaseTexture | null, material: any): void {
+    private watchEnvAtlas(atlas: BaseTexture | null, material: ParticleMaterialSource | null): void {
         atlas?.onDisposeObservable.addOnce(() => {
             if (this.destroyed || this.rendererSettings.reflectionAtlas !== atlas) {
                 return;
@@ -1211,7 +1248,7 @@ export class ParticleSystem implements IParticleSystem {
         });
     }
 
-    private applyMaterialSettings(material: any, overrides: MaterialOverrides = {}) {
+    private applyMaterialSettings(material: ParticleMaterialSource | null, overrides: MaterialOverrides = {}) {
         /* istanbul ignore if -- rendererSettings is always assigned in the constructor before any code path can call this private method */
         if (!this.rendererSettings) {
             return;
@@ -1261,10 +1298,30 @@ export class ParticleSystem implements IParticleSystem {
     }
 
     /**
-     * Resumes a paused system. It only resumes: a system that has finished ({@link isFinished})
-     * stays finished, since nothing is left to emit; {@link restart} plays it again from the start.
+     * Plays the system, like Unity's `Play`: a paused or stopped system resumes from where it is,
+     * and one that has finished ({@link isFinished}) starts over from the beginning, as
+     * {@link restart} does. A playing system that has not finished is left as it is. To undo a
+     * {@link pause} without replaying a system that had finished, use {@link resume}.
      */
     play(): void {
+        if (this.destroyed) {
+            return;
+        }
+        if (this.isFinished()) {
+            this.restart();
+        }
+        this.resume();
+    }
+
+    /**
+     * Undoes {@link pause}: the system goes on from where it is, and one that has finished stays
+     * finished. For a pause button over a whole scene, where {@link play} would replay the
+     * effects that had already ended.
+     */
+    resume(): void {
+        if (this.destroyed) {
+            return;
+        }
         this.paused = false;
         // A move made while paused is a placement, not motion to spread the next frame over.
         this.previousEmitterMatrix = undefined;
@@ -1406,12 +1463,7 @@ export class ParticleSystem implements IParticleSystem {
         // Bursts edited in place since the last play are put back in time order and in range.
         this.emissionBursts.forEach((burst) => Object.assign(burst, normalizeBurst(burst)));
         this.emissionBursts.sort((a, b) => a.time - b.time);
-        this.behaviors.forEach((behavior) => {
-            behavior.reset();
-            if (behavior instanceof EmitSubParticleSystem) {
-                behavior.clearEmissions();
-            }
-        });
+        this.behaviors.forEach((behavior) => behavior.reset());
         // A sweeping shape (Loop, PingPong) starts its arc over, so the replay is the same.
         this.emitterShape.reset?.();
         this.emitEnded = false;
@@ -1439,7 +1491,7 @@ export class ParticleSystem implements IParticleSystem {
      */
     update(delta: number, stepDeadline = Infinity, catchUpDeadline?: number) {
         if (this.paused || this.destroyed) return;
-        const speed = this.playbackSpeed;
+        const speed = this.playbackSpeed * this.timeDilationValue;
         delta = SimulationClock.frameSeconds(delta, speed);
 
         if (this.culled) {
@@ -1647,9 +1699,9 @@ export class ParticleSystem implements IParticleSystem {
      * per-instance data, Unreal's user parameters). With {@link erosion},
      * alpha is the erosion level, so this wipes the shape in and out. The
      * particles' own colours are untouched, so clearing it restores them, and
-     * systems with different tints still batch together. Under additive
-     * (`ALPHA_ONEONE`) or premultiplied blending, which ignore alpha, fade
-     * with the colour instead, or with erosion on. Unset (the default): none.
+     * systems with different tints still batch together. Its alpha fades the
+     * particles in every blend mode that blends by coverage (see
+     * {@link blendCategory}). Unset (the default): none.
      * Not saved in the effect JSON; copied by {@link clone}.
      */
     tint?: Vector4;
@@ -1799,9 +1851,15 @@ export class ParticleSystem implements IParticleSystem {
     /** Re-points every particle at the store, for {@link snapshotPreviousState}. */
     private readonly rebindParticles = (): void => this.spawner.rebind();
 
+    /** The one `particleDied` event, filled in for each death so a death allocates nothing. */
+    private readonly particleDiedEvent: ParticleSystemEvent = {type: 'particleDied', particleSystem: this};
+
     /** Fires `particleDied` for a particle the step retired. */
     private readonly fireParticleDied = (particle: Particle): void => {
-        this.events.fire({type: 'particleDied', particleSystem: this, particle});
+        const event = this.particleDiedEvent;
+        event.particle = particle;
+        this.events.fire(event);
+        event.particle = undefined;
     };
 
     private notifyFinished(): void {
@@ -1850,10 +1908,11 @@ export class ParticleSystem implements IParticleSystem {
     ): ParticleSystem {
         const ps = new ParticleSystem(particleSystemParametersFromJSON(json, meta, scene));
         ps.behaviors = (json.behaviors ?? [])
-            .map((behaviorJson) => {
-                const behavior = BehaviorFromJSON(behaviorJson, ps);
-                if (behavior && behavior.type === 'EmitSubParticleSystem') {
-                    dependencies[(behaviorJson as {subParticleSystem: string}).subParticleSystem] = behavior;
+            .map((behaviorJson, index) => {
+                const behavior = readFormatPart(`behaviors[${index}]`, () => BehaviorFromJSON(behaviorJson, ps));
+                const target = (behaviorJson as {subParticleSystem?: unknown}).subParticleSystem;
+                if (behavior && behavior.type === 'EmitSubParticleSystem' && typeof target === 'string') {
+                    dependencies[target] = behavior;
                 }
                 return behavior;
             })
@@ -1880,13 +1939,21 @@ export class ParticleSystem implements IParticleSystem {
      * Calls `callback` on each `event`: `'emitEnd'` when emission ends, `'finished'` when the last
      * particle of an ended system dies, `'particleDied'` per particle (with `event.particle`), and
      * `'destroy'` on dispose.
+     *
+     * A `'particleDied'` event and the particle on it are reused: read what you need inside the
+     * callback and keep neither, since the particle's slot goes to the next one spawned. In trail
+     * mode a particle dies when its trail is gone, so with a trail lifetime the event comes after
+     * the head stopped, once the last sample has faded.
+     *
+     * A callback added or removed while an event is firing takes effect from the next event; the
+     * callbacks of the one firing are all called.
      */
     addEventListener(event: ParticleSystemEventType, callback: (event: ParticleSystemEvent) => void): void {
         this.events.add(event, callback);
     }
 
-    /** Removes every callback registered for `event`. */
-    removeAllEventListeners(event: ParticleSystemEventType): void {
+    /** Removes every callback registered for `event`, or every callback of every event when it is left out. */
+    removeAllEventListeners(event?: ParticleSystemEventType): void {
         this.events.removeAll(event);
     }