babylon.quarks 0.27.0 → 0.28.0

package/src/QuarksSerializer.ts

@@ -8,10 +8,12 @@ import {Geometry} from '@babylonjs/core/Meshes/geometry';
 import {InstancedMesh} from '@babylonjs/core/Meshes/instancedMesh';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {GeometryEntry, QuarksMaterialJSON} from './effectDocumentJSON';
 import {ensureTriangleIndices} from './geometryUtil';
 import {quarksNodeId} from './nodeId';
 import {ParticleEmitter} from './ParticleEmitter';
 import type {BabylonMetaData, ParticleSystem, ParticleSystemJSONParameters} from './ParticleSystem';
+import type {AnimationJSON} from './QuarksPrefab';
 import {QuarksPrefab} from './QuarksPrefab';
 import {textureSourceUrl} from './textureSource';
 
@@ -83,10 +85,13 @@ export interface QuarksNodeJSON {
     type: 'Group' | 'ParticleEmitter' | 'Mesh' | 'QuarksPrefab' | string;
     /** The node's name. */
     name?: string;
-    /** Local transform, column-major, as Babylon's `Matrix.asArray()`. */
-    matrix: number[];
-    /** Written only when the node is disabled; loads it disabled, with everything under it. */
-    visible?: false;
+    /**
+     * Local transform, column-major, as Babylon's `Matrix.asArray()`. Always written; a three.js
+     * file without it places the node by `position`, `quaternion` or `rotation`, and `scale`.
+     */
+    matrix?: number[];
+    /** Written only when the node is disabled (false); loads it disabled, with everything under it. */
+    visible?: boolean;
     /** `Mesh`: written only when the mesh is not drawn (`isVisible`), which leaves its children drawn. */
     isVisible?: false;
     /** Child nodes, in order. */
@@ -95,9 +100,20 @@ export interface QuarksNodeJSON {
     ps?: ParticleSystemJSONParameters;
     /** `Mesh`: the {@link QuarksGeometryJSON} uuid. */
     geometry?: string;
-    /** `Mesh`: the material uuid. */
-    material?: string;
-    [key: string]: unknown;
+    /** `Mesh`: the material uuid; a three.js mesh may list several, of which the first is used. */
+    material?: string | string[];
+    /** `QuarksPrefab`: the timeline's speed, written only when not 1. */
+    timeScale?: number;
+    /** `QuarksPrefab`: the timeline's tracks. */
+    animationData?: AnimationJSON[];
+    /** three.js files without `matrix`: the position as `[x, y, z]`. */
+    position?: number[];
+    /** three.js files without `matrix`: the scale as `[x, y, z]`. */
+    scale?: number[];
+    /** three.js files without `matrix`: the rotation as a quaternion `[x, y, z, w]`. */
+    quaternion?: number[];
+    /** three.js files without `matrix` or `quaternion`: Euler angles `[x, y, z]` in radians. */
+    rotation?: number[];
 }
 
 /** A whole effect, as {@link serializeEffect} writes it and `QuarksLoader` reads it. */
@@ -116,7 +132,7 @@ export interface QuarksEffectJSON {
     /** Meshes the nodes and particle systems use. */
     geometries: QuarksGeometryJSON[];
     /** Materials the particle systems and `Mesh` nodes use, referred to by uuid. */
-    materials: Array<Record<string, unknown>>;
+    materials: QuarksMaterialJSON[];
     /** Textures the particle systems use. */
     textures: QuarksTextureJSON[];
     /** Image files the textures load. */
@@ -182,7 +198,7 @@ class EffectWriter {
     readonly meta: BabylonMetaData = {geometries: {}, materials: {}, textures: {}};
     private readonly meshGeometries = new Map<string, QuarksGeometryJSON>();
     private readonly geometryIds = new Map<Geometry, string>();
-    private readonly meshMaterials: Array<{json: Record<string, unknown>; map: BaseTexture | null}> = [];
+    private readonly meshMaterials: Array<{json: QuarksMaterialJSON; map: BaseTexture | null}> = [];
     private readonly meshMaterialIds = new Map<StandardMaterial, string>();
     private readonly extraTextures = new Map<BaseTexture, string>();
     private nextId = 0;
@@ -329,7 +345,7 @@ class EffectWriter {
             this.warn(`Mesh "${mesh.name}": its material's alpha and colours are not written; it loads opaque white.`);
         }
         // Each field only when it differs from what the loader gives a material without it.
-        const json: Record<string, unknown> = {uuid, type: 'MeshBasicMaterial'};
+        const json: QuarksMaterialJSON = {uuid, type: 'MeshBasicMaterial'};
         if (material.alphaMode !== Constants.ALPHA_COMBINE) json.alphaMode = material.alphaMode;
         if (material.backFaceCulling) json.side = 0;
         if (material.alphaCutOff !== 0) json.alphaTest = material.alphaCutOff;
@@ -398,7 +414,7 @@ class EffectWriter {
 
         const materials = Object.values(this.meta.materials).map((material) => {
             // The live Babylon material is for in-memory reuse only.
-            const {sourceMaterial: _sourceMaterial, ...serializable} = material as Record<string, unknown>;
+            const {sourceMaterial: _sourceMaterial, ...serializable} = material;
             return serializable;
         });
 
@@ -409,7 +425,10 @@ class EffectWriter {
                 generator: this.options.generator ?? 'babylon.quarks',
                 quarksFormat: QUARKS_FORMAT_VERSION,
             },
-            geometries: [...Object.values(this.meta.geometries), ...this.meshGeometries.values()],
+            geometries: [
+                ...Object.values(this.meta.geometries).filter(isQuarksGeometryJSON),
+                ...this.meshGeometries.values(),
+            ],
             materials: [...materials, ...meshMaterials],
             textures,
             images,
@@ -418,18 +437,27 @@ class EffectWriter {
     }
 }
 
+/** Whether a system's geometry entry is inline quarks data, the form its `toJSON` writes. */
+function isQuarksGeometryJSON(entry: GeometryEntry): entry is QuarksGeometryJSON {
+    return 'type' in entry && entry.type === 'QuarksGeometry' && Array.isArray(entry.positions);
+}
+
 /** Ids a written document links to by uuid, by the kind of link. */
 function* links(node: QuarksNodeJSON): Generator<[string, string]> {
-    const ps = node.ps as {behaviors?: Array<{type?: string; subParticleSystem?: unknown}>; shape?: any} | undefined;
+    const ps = node.ps;
     for (const behavior of ps?.behaviors ?? []) {
-        if (behavior.type === 'EmitSubParticleSystem' && typeof behavior.subParticleSystem === 'string') {
+        if (
+            behavior.type === 'EmitSubParticleSystem' &&
+            'subParticleSystem' in behavior &&
+            typeof behavior.subParticleSystem === 'string'
+        ) {
             yield ['a sub emitter', behavior.subParticleSystem];
         }
     }
     if (ps?.shape?.type === 'mesh_surface' && typeof ps.shape.mesh === 'string') {
         yield ['a mesh surface shape', ps.shape.mesh];
     }
-    for (const animation of (node.animationData as Array<{targetUUID?: unknown}> | undefined) ?? []) {
+    for (const animation of node.animationData ?? []) {
         if (typeof animation.targetUUID === 'string') {
             yield ['a prefab animation', animation.targetUUID];
         }

package/src/QuarksUtil.ts

@@ -1,8 +1,11 @@
+import {InstancedMesh} from '@babylonjs/core/Meshes/instancedMesh';
+import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Node} from '@babylonjs/core/node';
 import {ConstantValue, EmitSubParticleSystem, FunctionValueGenerator, IntervalValue, ValueGenerator} from 'quarks.core';
 import {BatchedRenderer} from './BatchedRenderer';
 import {shareEffectResources} from './effectResources';
+import {MeshSurfaceEmitter} from './MeshSurfaceEmitter';
 import {ParticleEmitter} from './ParticleEmitter';
 import {ParticleSystem} from './ParticleSystem';
 
@@ -27,13 +30,26 @@ export class QuarksUtil {
         });
     }
 
-    /** Resumes every system under `root`, see {@link ParticleSystem.play}. */
+    /**
+     * Plays every system under `root`, see {@link ParticleSystem.play}: paused ones resume and
+     * finished ones, a short burst inside a longer effect included, start over.
+     */
     static play(root: Node): void {
         QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
             (emitter.system as unknown as ParticleSystem).play();
         });
     }
 
+    /**
+     * Undoes {@link pause} on every system under `root`, see {@link ParticleSystem.resume}: the
+     * finished ones stay finished.
+     */
+    static resume(root: Node): void {
+        QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
+            (emitter.system as unknown as ParticleSystem).resume();
+        });
+    }
+
     /** Clears, rewinds and pauses every system under `root`, see {@link ParticleSystem.stop}. */
     static stop(root: Node): void {
         QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
@@ -90,16 +106,46 @@ export class QuarksUtil {
     /**
      * A deep copy of an effect: the node tree under `root` with every particle
      * system cloned, sub emitter links pointing at the copies, and the same
-     * transforms and enabled state. The copy is not added to any renderer.
-     * Nodes that are neither transform nodes nor emitters are skipped.
+     * transforms and enabled state. Meshes are cloned as meshes that share
+     * the source's geometry and material, instances of a mesh in the tree as
+     * instances of its copy, and a mesh surface shape that emits from a mesh
+     * in the tree emits from its copy. An instance of a mesh outside the tree
+     * stays an instance of that mesh, and goes when it is disposed. The copy holds the
+     * source's textures and materials, so disposing the source leaves the copy
+     * whole. It is not added to any renderer. Nodes that are neither transform
+     * nodes nor emitters, such as lights and cameras, are skipped.
      */
     static instantiate(root: TransformNode, name?: string): TransformNode {
         const copies = new Map<ParticleEmitter, ParticleEmitter>();
+        const meshCopies = new Map<Node, Mesh>();
+        const inTree = new Set<Node>([root, ...root.getDescendants(false)]);
+        // A mesh is copied when first needed: where it sits in the tree, or earlier, as the source
+        // of an instance copied before it. Its children are copied as every node's are.
+        const meshCopyOf = (mesh: Mesh): Mesh => {
+            let copy = meshCopies.get(mesh);
+            if (copy === undefined) {
+                copy = mesh.clone(mesh.name, null, true);
+                copy.setEnabled(mesh.isEnabled(false));
+                meshCopies.set(mesh, copy);
+            }
+            return copy;
+        };
         const copyNode = (node: Node, parent: TransformNode | null, copyName?: string): TransformNode | null => {
             let copy: TransformNode;
             if (node instanceof ParticleEmitter) {
                 copy = node.clone(copyName);
                 copies.set(node, copy as ParticleEmitter);
+            } else if (node instanceof Mesh) {
+                copy = meshCopyOf(node);
+                if (copyName !== undefined) {
+                    copy.name = copyName;
+                }
+            } else if (node instanceof InstancedMesh) {
+                // An instance of a mesh in the tree becomes an instance of its copy, so the copy
+                // does not go when the source effect is disposed (a mesh disposes its instances).
+                const source = inTree.has(node.sourceMesh) ? meshCopyOf(node.sourceMesh) : undefined;
+                copy = node.clone(copyName ?? node.name, null, true, source)!;
+                copy.setEnabled(node.isEnabled(false));
             } else if (node instanceof TransformNode) {
                 copy = new TransformNode(copyName ?? node.name, node.getScene());
                 copy.position.copyFrom(node.position);
@@ -119,11 +165,12 @@ export class QuarksUtil {
             return copy;
         };
         const copy = copyNode(root, null, name) as TransformNode;
-        // The copy draws with the source's textures, so QuarksLoader.disposeEffect(source) keeps them.
+        // The copy draws with the source's textures and materials, so disposeEffect(source) keeps them.
         shareEffectResources(root, copy);
-        // Sub emitter behaviors on the copies still target the original emitters.
         for (const emitter of copies.values()) {
-            for (const behavior of (emitter.system as unknown as ParticleSystem).behaviors) {
+            const system = emitter.system as unknown as ParticleSystem;
+            // Sub emitter behaviors on the copies still target the original emitters.
+            for (const behavior of system.behaviors) {
                 if (behavior instanceof EmitSubParticleSystem) {
                     const target = copies.get(behavior.subParticleSystem as unknown as ParticleEmitter);
                     if (target !== undefined) {
@@ -131,6 +178,14 @@ export class QuarksUtil {
                     }
                 }
             }
+            // So does a mesh surface shape: it emits from the copy of its mesh when the tree has one.
+            const shape = system.emitterShape;
+            if (shape instanceof MeshSurfaceEmitter && shape.mesh !== undefined) {
+                const meshCopy = meshCopies.get(shape.mesh);
+                if (meshCopy !== undefined) {
+                    shape.mesh = meshCopy;
+                }
+            }
         }
         return copy;
     }
@@ -145,7 +200,8 @@ export class QuarksUtil {
      * {@link endEmit}, or when one is frozen at playback speed 0.
      *
      * Random values count at their maximum, so this is an upper bound; curves
-     * are sampled. Particles cut short by collisions or culling only make the
+     * are sampled. A runtime {@link ParticleSystem.timeDilation} is not counted:
+     * this is the effect's own length. Particles cut short by collisions or culling only make the
      * real effect shorter.
      */
     static getDuration(root: Node): number {
@@ -162,8 +218,7 @@ export class QuarksUtil {
                     continue;
                 }
                 const target = (behavior.subParticleSystem as unknown as ParticleEmitter | undefined)?.system as
-                    | ParticleSystem
-                    | undefined;
+                    ParticleSystem | undefined;
                 if (target !== undefined && typeof target === 'object') {
                     if (!systems.includes(target)) {
                         systems.push(target);

package/src/SpriteBatch.ts

@@ -37,6 +37,13 @@ export class SpriteBatch extends VFXBatch {
             texture = RawTexture.CreateRGBATexture(new Uint8Array([255, 255, 255, 255]), 1, 1, scene);
             texture.name = 'quarksMeshWhite';
             SpriteBatch.whiteTextureByScene.set(scene, texture);
+            // Disposed from outside (a scene-wide texture sweep): the next batch makes a new one.
+            const made = texture;
+            texture.onDisposeObservable.addOnce(() => {
+                if (SpriteBatch.whiteTextureByScene.get(scene) === made) {
+                    SpriteBatch.whiteTextureByScene.delete(scene);
+                }
+            });
         }
         return texture;
     }
@@ -67,14 +74,14 @@ export class SpriteBatch extends VFXBatch {
     constructor(settings: VFXBatchSettings, scene: Scene, depth: DepthBinding | null = null) {
         super(settings, scene, depth);
         this.storeFixedLighting(defaultMeshLighting());
-        this.maxParticles = 1000;
+        this.maxParticles = this.initialCapacity;
         this.setupBuffers();
         this.rebuildMaterial();
     }
 
     /** @internal */
     setupBuffers(): void {
-        this.mesh.dispose();
+        this.mesh?.dispose();
         this.mesh = new Mesh('spriteBatch', this.scene);
         this.configureMesh();
 
@@ -178,11 +185,19 @@ export class SpriteBatch extends VFXBatch {
         this.mesh.doNotSyncBoundingInfo = true;
     }
 
+    /** @internal */
+    protected readonly initialCapacity = 1000;
+
     /** @internal */
     expandBuffers(target: number): void {
         while (target >= this.maxParticles) {
             this.maxParticles *= 2;
         }
+        this.resizeBuffers();
+    }
+
+    /** @internal */
+    protected resizeBuffers(): void {
         this.disposeExpandableBuffers();
         this.buildExpandableBuffers();
         this.sortScratch = undefined;
@@ -393,7 +408,9 @@ export class SpriteBatch extends VFXBatch {
 
         this.bindFog(mat);
         this.bindSurface(mat);
-        mat.backFaceCulling = false;
+        // Billboards, beams and the like are flat sheets: both faces, whatever the setting says.
+        mat.backFaceCulling = this.settings.renderFace !== 'both';
+        mat.cullBackFaces = this.settings.renderFace !== 'back';
 
         if (this.settings.materialTransparent) {
             mat.alphaMode = this.settings.materialBlendMode;
@@ -532,9 +549,7 @@ export class SpriteBatch extends VFXBatch {
         for (let i = 0; i < visibleSystems.length; i++) {
             particleCount += visibleSystems[i].particleNum;
         }
-        if (particleCount > this.maxParticles) {
-            this.expandBuffers(particleCount);
-        }
+        this.fitBuffers(particleCount);
 
         for (let s = 0; s < visibleSystems.length; s++) {
             const system = visibleSystems[s];

package/src/TrailBatch.ts

@@ -121,14 +121,14 @@ export class TrailBatch extends VFXBatch {
         // For a trail batch `maxParticles` counts vertices, two per drawn point: the buffers are
         // the largest per-batch allocation in the library, so start small and let expandBuffers
         // grow to whatever the batch actually needs.
-        this.maxParticles = 1024;
+        this.maxParticles = this.initialCapacity;
         this.setupBuffers();
         this.rebuildMaterial();
     }
 
     /** @internal */
     setupBuffers(): void {
-        this.mesh.dispose();
+        this.mesh?.dispose();
         this.mesh = new Mesh('trailBatch', this.scene);
         this.configureMesh();
         this.buildGeometryBuffers();
@@ -210,11 +210,19 @@ export class TrailBatch extends VFXBatch {
         }
     }
 
+    /** @internal */
+    protected readonly initialCapacity = 1024;
+
     /** Grows the buffers to hold more than `target` vertices. @internal */
     expandBuffers(target: number): void {
         while (target >= this.maxParticles) {
             this.maxParticles *= 2;
         }
+        this.resizeBuffers();
+    }
+
+    /** @internal */
+    protected resizeBuffers(): void {
         // `Geometry.setVerticesBuffer` disposes the buffer it replaces; these custom attributes
         // are not in the geometry's map, so they are released here.
         this.previousVB?.dispose();
@@ -518,9 +526,7 @@ export class TrailBatch extends VFXBatch {
                 particleCount += (historyCount * (tessellation + 1) + 1) * 2;
             }
         }
-        if (particleCount > this.maxParticles) {
-            this.expandBuffers(particleCount);
-        }
+        this.fitBuffers(particleCount);
 
         for (let s = 0; s < visibleSystems.length; s++) {
             const system = visibleSystems[s];
@@ -969,7 +975,7 @@ export class TrailBatch extends VFXBatch {
     private adoptMeshBounds(): void {
         const meshBoundingInfo = this.mesh.getBoundingInfo();
         for (const subMesh of this.mesh.subMeshes) {
-            (subMesh as any)._boundingInfo = meshBoundingInfo;
+            subMesh.setBoundingInfo(meshBoundingInfo);
         }
     }