babylon.quarks 0.24.1 → 0.26.0

package/src/QuarksLoader.ts

@@ -75,6 +75,7 @@ interface ParsedGeometry {
     positions: Float32Array;
     indices: Uint32Array | Uint16Array;
     uvs?: Float32Array;
+    uvs2?: Float32Array;
     normals?: Float32Array;
 }
 
@@ -101,6 +102,7 @@ function geometryKey(geometry: ParsedGeometry): string {
         geometry.positions,
         geometry.indices,
         geometry.uvs,
+        geometry.uvs2,
         geometry.normals,
     ];
     let lengths = '';
@@ -313,6 +315,7 @@ export class QuarksLoader {
                     positions: new Float32Array(geom.positions ?? []),
                     indices: geom.indices ? new Uint32Array(geom.indices) : new Uint32Array(0),
                     uvs: geom.uvs ? new Float32Array(geom.uvs) : undefined,
+                    uvs2: geom.uvs2 ? new Float32Array(geom.uvs2) : undefined,
                     normals: geom.normals ? new Float32Array(geom.normals) : undefined,
                 });
             }
@@ -427,7 +430,10 @@ export class QuarksLoader {
         let positions = new Float32Array(0);
         let indices: Uint32Array | Uint16Array = new Uint32Array(0);
         let uvs: Float32Array | undefined;
+        let uvs2: Float32Array | undefined;
         let normals: Float32Array | undefined;
+        // three.js names the second UV set `uv1` (r151 on), `uv2` before.
+        const uv2Attribute = data.attributes?.uv1 ?? data.attributes?.uv2;
 
         if (data.interleavedBuffers && data.arrayBuffers) {
             const buffers: {[uuid: string]: {data: Float32Array; stride: number}} = {};
@@ -453,6 +459,16 @@ export class QuarksLoader {
                     const buf = buffers[attr.data];
                     if (buf) uvs = this.extractInterleavedAttribute(buf.data, buf.stride, attr.offset, attr.itemSize);
                 }
+                if (uv2Attribute?.isInterleavedBufferAttribute) {
+                    const buf = buffers[uv2Attribute.data];
+                    if (buf)
+                        uvs2 = this.extractInterleavedAttribute(
+                            buf.data,
+                            buf.stride,
+                            uv2Attribute.offset,
+                            uv2Attribute.itemSize
+                        );
+                }
                 if (data.attributes.normal?.isInterleavedBufferAttribute) {
                     const attr = data.attributes.normal;
                     const buf = buffers[attr.data];
@@ -467,6 +483,9 @@ export class QuarksLoader {
             if (data.attributes.uv?.array) {
                 uvs = new Float32Array(data.attributes.uv.array);
             }
+            if (uv2Attribute?.array) {
+                uvs2 = new Float32Array(uv2Attribute.array);
+            }
             if (data.attributes.normal?.array) {
                 normals = new Float32Array(data.attributes.normal.array);
             }
@@ -482,7 +501,7 @@ export class QuarksLoader {
 
         indices = ensureTriangleIndices(positions, indices);
 
-        return {positions, indices, uvs, normals};
+        return {positions, indices, uvs, uvs2, normals};
     }
 
     private extractInterleavedAttribute(buffer: Float32Array, stride: number, offset: number, itemSize: number): any {
@@ -666,7 +685,7 @@ export class QuarksLoader {
                         const data = await loadGeometry(geom.url);
                         // Copy arrays so a shared fetch-cache document is not aliased across
                         // effects — mutating one effect's inlined geometry must not corrupt others.
-                        for (const key of ['positions', 'indices', 'uvs', 'normals']) {
+                        for (const key of ['positions', 'indices', 'uvs', 'uvs2', 'normals']) {
                             const value = data?.[key];
                             if (value === undefined) {
                                 continue;
@@ -824,6 +843,32 @@ export class QuarksLoader {
             if (matDef.rim && typeof matDef.rim === 'object') {
                 matInfo.rim = matDef.rim;
             }
+            // Texture effects (QuarksMaterial): mapUV {channel, tiling, offset, scroll},
+            // gradientMap {ramp (texture uuid), channel},
+            // erosion {mask (texture uuid), maskUV {channel, tiling, offset, scroll}, softness, edgeWidth,
+            // edgeColor}.
+            if (matDef.mapUV && typeof matDef.mapUV === 'object') {
+                matInfo.mapUV = matDef.mapUV;
+            }
+            if (matDef.gradientMap && typeof matDef.gradientMap === 'object') {
+                matInfo.gradientMap = {
+                    ...matDef.gradientMap,
+                    ramp: matDef.gradientMap.ramp ? meta.textures[matDef.gradientMap.ramp] || null : null,
+                };
+            }
+            if (matDef.erosion && typeof matDef.erosion === 'object') {
+                matInfo.erosion = {
+                    ...matDef.erosion,
+                    mask: matDef.erosion.mask ? meta.textures[matDef.erosion.mask] || null : null,
+                };
+            }
+            // uvDistortion {map (texture uuid), mapUV {channel, tiling, offset, scroll}, strength}.
+            if (matDef.uvDistortion && typeof matDef.uvDistortion === 'object') {
+                matInfo.uvDistortion = {
+                    ...matDef.uvDistortion,
+                    map: matDef.uvDistortion.map ? meta.textures[matDef.uvDistortion.map] || null : null,
+                };
+            }
 
             // QuarksMaterial (what ParticleSystem.ensureMaterialMeta emits) writes `alphaMode`
             // directly as a Babylon alpha-mode constant; three.js materials (MeshBasicMaterial
@@ -873,6 +918,9 @@ export class QuarksLoader {
             if (geometry.uvs && geometry.uvs.length > 0) {
                 vertexData.uvs = geometry.uvs;
             }
+            if (geometry.uvs2 && geometry.uvs2.length > 0) {
+                vertexData.uvs2 = geometry.uvs2;
+            }
             if (geometry.normals && geometry.normals.length > 0) {
                 vertexData.normals = geometry.normals;
             }

package/src/QuarksUtil.ts

@@ -1,6 +1,6 @@
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Node} from '@babylonjs/core/node';
-import {EmitSubParticleSystem} from 'quarks.core';
+import {ConstantValue, EmitSubParticleSystem, FunctionValueGenerator, IntervalValue, ValueGenerator} from 'quarks.core';
 import {BatchedRenderer} from './BatchedRenderer';
 import {ParticleEmitter} from './ParticleEmitter';
 import {ParticleSystem} from './ParticleSystem';
@@ -120,6 +120,102 @@ export class QuarksUtil {
         return copy;
     }
 
+    /**
+     * Seconds until the effect under `root` is over when it plays from the
+     * start: for each system its start delay, its duration and its longest
+     * particle life, divided by its playback speed; a sub emitter target goes
+     * on emitting for its own duration after the last of its parents' particles
+     * and ends a particle life after that, wherever it sits in the scene.
+     * Infinity when a system loops, since such an effect only ends on
+     * {@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
+     * real effect shorter.
+     */
+    static getDuration(root: Node): number {
+        const systems: ParticleSystem[] = [];
+        QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
+            systems.push(emitter.system as unknown as ParticleSystem);
+        });
+        const parents = new Map<ParticleSystem, ParticleSystem[]>();
+        // Grows while it is walked: a target outside `root` is part of the effect too.
+        for (let i = 0; i < systems.length; i++) {
+            const system = systems[i];
+            for (const behavior of system.behaviors) {
+                if (!(behavior instanceof EmitSubParticleSystem)) {
+                    continue;
+                }
+                const target = (behavior.subParticleSystem as unknown as ParticleEmitter | undefined)?.system as
+                    | ParticleSystem
+                    | undefined;
+                if (target !== undefined && typeof target === 'object') {
+                    if (!systems.includes(target)) {
+                        systems.push(target);
+                    }
+                    const list = parents.get(target) ?? [];
+                    list.push(system);
+                    parents.set(target, list);
+                }
+            }
+        }
+        const ends = new Map<ParticleSystem, number>();
+        const endOf = (system: ParticleSystem): number => {
+            const known = ends.get(system);
+            if (known !== undefined) {
+                return known;
+            }
+            // Marks the system while it is resolved, so a sub emitter cycle loops forever rather than the stack.
+            ends.set(system, Infinity);
+            const speed = system.playbackSpeed;
+            const life = QuarksUtil.maxOf(system.startLife) / speed;
+            let end: number;
+            if (!(speed > 0)) {
+                end = Infinity;
+            } else if (system.onlyUsedByOther) {
+                end = 0;
+                for (const parent of parents.get(system) ?? []) {
+                    end = Math.max(end, endOf(parent));
+                }
+                end += system.duration / speed + life;
+            } else if (system.looping) {
+                end = Infinity;
+            } else {
+                // The delay is drawn once, at the start.
+                end = (QuarksUtil.maxOf(system.startDelay, 0) + system.duration) / speed + life;
+            }
+            ends.set(system, end);
+            return end;
+        };
+        let duration = 0;
+        for (const system of systems) {
+            duration = Math.max(duration, endOf(system));
+        }
+        return duration;
+    }
+
+    /** The largest value `generator` gives: exact for constants and intervals, sampled otherwise. */
+    private static maxOf(generator: ValueGenerator | FunctionValueGenerator, at?: number): number {
+        if (generator instanceof ConstantValue) {
+            return generator.value;
+        }
+        if (generator instanceof IntervalValue) {
+            return Math.max(generator.a, generator.b);
+        }
+        let max = -Infinity;
+        const samples = 32;
+        for (let i = 0; i <= samples; i++) {
+            const memory: number[] = [];
+            generator.startGen(memory);
+            const value =
+                generator.type === 'function'
+                    ? generator.genValue(memory, at ?? i / samples)
+                    : generator.genValue(memory);
+            max = Math.max(max, value);
+        }
+        return max;
+    }
+
     private static traverseNode(node: Node, callback: (node: Node) => void): void {
         callback(node);
         const children = node.getChildren();

package/src/SpriteBatch.ts

@@ -15,9 +15,11 @@ import {
     SpriteParticle,
     StretchedBillBoardSettings,
     Vector3,
+    Vector4,
 } from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
 import {gather, sortByKey, SortScratch} from './instanceSort';
+import type {ParticleSystem} from './ParticleSystem';
 import local_particle_physics_vert from './shaders/local_particle_physics_vert.glsl';
 import local_particle_physics_vert_wgsl from './shaders/local_particle_physics_vert.wgsl';
 import particle_frag from './shaders/particle_frag.glsl';
@@ -90,6 +92,9 @@ export class SpriteBatch extends VFXBatch {
         } else {
             vertexData.uvs = new Float32Array(vertexCount * 2);
         }
+        if (this.meshUV2()) {
+            vertexData.uvs2 = this.settings.instancingUVs2!;
+        }
         if (this.settings.instancingNormals) {
             vertexData.normals = this.settings.instancingNormals;
         }
@@ -98,6 +103,33 @@ export class SpriteBatch extends VFXBatch {
         this.buildExpandableBuffers();
     }
 
+    /**
+     * True when a mesh batch reads UV channel 1 and has a second UV set to
+     * read it from, two values per vertex. A set of any other length is left
+     * out with a warning, and channel 1 then reads the first set.
+     */
+    private warnedUV2 = false;
+
+    private meshUV2(): boolean {
+        const uvs2 = this.settings.instancingUVs2;
+        if (this.settings.renderMode !== RenderMode.Mesh || !uvs2 || !this.usesUV1()) {
+            return false;
+        }
+        const expected = (this.settings.instancingGeometry.length / 3) * 2;
+        if (uvs2.length !== expected) {
+            if (this.warnedUV2) {
+                return false;
+            }
+            this.warnedUV2 = true;
+            console.warn(
+                `[babylon.quarks] instancingUVs2 has ${uvs2.length} values for ${expected / 2} vertices ` +
+                    '(two per vertex expected); UV channel 1 reads the first UV set instead.'
+            );
+            return false;
+        }
+        return true;
+    }
+
     /** Releases the instance vertex buffers so a resize does not leak GPU memory. */
     private disposeExpandableBuffers(): void {
         this.offsetVB?.dispose();
@@ -138,7 +170,7 @@ export class SpriteBatch extends VFXBatch {
         }
         this.mesh.setVerticesBuffer(this.rotationVB);
 
-        if (this.settings.renderMode === RenderMode.StretchedBillBoard) {
+        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
             this.velocityBuffer = new Float32Array(this.maxParticles * 4);
             this.velocityVB = new VertexBuffer(engine, this.velocityBuffer, 'velocity', true, false, 4, true);
             this.mesh.setVerticesBuffer(this.velocityVB);
@@ -276,7 +308,7 @@ export class SpriteBatch extends VFXBatch {
         if (this.settings.renderMode === RenderMode.Mesh) {
             vertexShader = {glsl: local_particle_physics_vert, wgsl: local_particle_physics_vert_wgsl};
             fragmentShader = {glsl: particle_physics_frag, wgsl: particle_physics_frag_wgsl};
-        } else if (this.settings.renderMode === RenderMode.StretchedBillBoard) {
+        } else if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
             vertexShader = {glsl: stretched_bb_particle_vert, wgsl: stretched_bb_particle_vert_wgsl};
             fragmentShader = {glsl: particle_frag, wgsl: particle_frag_wgsl};
         } else {
@@ -322,6 +354,9 @@ export class SpriteBatch extends VFXBatch {
         if (this.settings.renderMode === RenderMode.HorizontalBillBoard) {
             defines.push('HORIZONTAL');
         }
+        if (this.settings.renderMode === RenderMode.Beam) {
+            defines.push('BEAM');
+        }
         const pivot = SpriteBatch.takesPivotAndFlip(this.settings.renderMode) ? this.settings.pivot : undefined;
         if (pivot) {
             defines.push('PIVOT');
@@ -339,11 +374,14 @@ export class SpriteBatch extends VFXBatch {
         const rim = isMesh ? this.settings.rim : undefined;
         if (rim) {
             defines.push('MESH_RIM');
-            if (rim.mode === 'mix') {
+            if (rim.mode === 'fade') {
+                defines.push('MESH_RIM_FADE');
+            } else if (rim.mode === 'mix') {
                 defines.push('MESH_RIM_MIX');
             }
         }
         const needsEyePosition = useEnvAtlas || !!rim;
+        defines.push(...this.surfaceDefines());
 
         const shaderLanguage = shaderLanguageFor(this.scene.getEngine());
         registerShaders(shaderName, vertexShader, fragmentShader, shaderLanguage);
@@ -352,7 +390,11 @@ export class SpriteBatch extends VFXBatch {
         if (this.settings.renderMode === RenderMode.Mesh) {
             attributes.push('normal');
         }
-        if (this.settings.renderMode === RenderMode.StretchedBillBoard) {
+        if (this.usesUV1() && this.meshUV2()) {
+            defines.push('MESH_UV2');
+            attributes.push('uv2');
+        }
+        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
             attributes.push('velocity');
         }
 
@@ -377,7 +419,8 @@ export class SpriteBatch extends VFXBatch {
             uniforms.push('rimColor');
             uniforms.push('rimParams');
         }
-        if (this.settings.renderMode === RenderMode.StretchedBillBoard) {
+        this.surfaceUniforms(uniforms, samplers);
+        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
             uniforms.push('speedFactor');
         }
         if (this.settings.softParticles) {
@@ -441,7 +484,7 @@ export class SpriteBatch extends VFXBatch {
             mat.setFloat('tileCountX', this.settings.uTileCount);
             mat.setFloat('tileCountY', this.settings.vTileCount);
         }
-        if (this.settings.renderMode === RenderMode.StretchedBillBoard) {
+        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
             mat.setFloat('speedFactor', this.settings.softNearFade > 0 ? this.settings.softNearFade : 1.0);
         }
         if (this.settings.softParticles) {
@@ -491,6 +534,7 @@ export class SpriteBatch extends VFXBatch {
         }
 
         this.bindFog(mat);
+        this.bindSurface(mat);
         mat.backFaceCulling = false;
 
         if (this.settings.materialTransparent) {
@@ -584,6 +628,8 @@ export class SpriteBatch extends VFXBatch {
         const renderMode = this.settings.renderMode;
         const isMeshRender = renderMode === RenderMode.Mesh;
         const isStretchedRender = renderMode === RenderMode.StretchedBillBoard;
+        const isBeamRender = renderMode === RenderMode.Beam;
+        const usesVelocity = isStretchedRender || isBeamRender;
         const flipsSprites = SpriteBatch.takesPivotAndFlip(renderMode);
 
         const visibleSystems = this.getVisibleSystems();
@@ -904,6 +950,10 @@ export class SpriteBatch extends VFXBatch {
                 }
             }
 
+            const tint = (system as ParticleSystem).tint;
+            if (tint !== undefined && index > firstIndex) {
+                SpriteBatch.applyTint(this.colorBuffer, firstIndex * 4, index - firstIndex, tint);
+            }
             if (flipsSprites && system.flip !== undefined) {
                 if (store !== undefined) {
                     SpriteBatch.applyFlip(this.sizeBuffer, firstIndex * 3, store.flip, particleNum);
@@ -911,6 +961,9 @@ export class SpriteBatch extends VFXBatch {
                     SpriteBatch.applyFlipFromParticles(this.sizeBuffer, firstIndex * 3, particles, particleNum);
                 }
             }
+            if (isBeamRender && this.velocityBuffer) {
+                this.writeBeams(system as ParticleSystem, firstIndex, index - firstIndex);
+            }
         }
 
         if (isStretchedRender && visibleSystems.length > 0) {
@@ -926,7 +979,7 @@ export class SpriteBatch extends VFXBatch {
             // Slot 0 only needs clearing once per stretch of empty frames; re-uploading it every
             // frame cost five buffer uploads per idle batch per frame.
             if (!this.clearedInstanceUploaded) {
-                this.uploadClearedInstance(isMeshRender, isStretchedRender);
+                this.uploadClearedInstance(isMeshRender, usesVelocity);
                 this.clearedInstanceUploaded = true;
             }
             return;
@@ -934,7 +987,7 @@ export class SpriteBatch extends VFXBatch {
         this.clearedInstanceUploaded = false;
 
         if (this.settings.sortMode !== 'none') {
-            this.sortInstances(index, isMeshRender, isStretchedRender);
+            this.sortInstances(index, isMeshRender, usesVelocity);
         }
 
         // Upload only the slots actually filled this frame: the buffers are sized
@@ -944,7 +997,7 @@ export class SpriteBatch extends VFXBatch {
         this.colorVB.update(this.colorBuffer.subarray(0, index * 4));
         this.uvTileVB.update(this.uvTileBuffer.subarray(0, index));
         this.rotationVB.update(this.rotationBuffer.subarray(0, isMeshRender ? index * 4 : index));
-        if (isStretchedRender && this.velocityVB && this.velocityBuffer) {
+        if (usesVelocity && this.velocityVB && this.velocityBuffer) {
             this.velocityVB.update(this.velocityBuffer.subarray(0, index * 4));
         }
     }
@@ -970,7 +1023,35 @@ export class SpriteBatch extends VFXBatch {
         }
     }
 
-    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes. */
+    /** Stretched billboards and beams: drawn along a per-instance vector, by the stretched shader. */
+    private static drawsAlongVelocity(renderMode: RenderMode): boolean {
+        return renderMode === RenderMode.StretchedBillBoard || renderMode === RenderMode.Beam;
+    }
+
+    private readonly beamEnd_ = new Vector3();
+
+    /**
+     * Writes, for the `count` instances from `first`, the world vector from
+     * each one's drawn position to the system's beam end into the velocity
+     * buffer, which the stretched shader under `BEAM` lays the quad along. A
+     * beam without an end gets no length.
+     */
+    private writeBeams(system: ParticleSystem, first: number, count: number): void {
+        const velocities = this.velocityBuffer!;
+        const offsets = this.offsetBuffer;
+        const end = this.beamEnd_;
+        const hasEnd = typeof system.getBeamEnd === 'function' && system.getBeamEnd(end);
+        for (let i = first; i < first + count; i++) {
+            const o = i * 3;
+            const v = i * 4;
+            velocities[v] = hasEnd ? end.x - offsets[o] : 0;
+            velocities[v + 1] = hasEnd ? end.y - offsets[o + 1] : 0;
+            velocities[v + 2] = hasEnd ? end.z - offsets[o + 2] : 0;
+            velocities[v + 3] = 0;
+        }
+    }
+
+    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes or beams. */
     private static takesPivotAndFlip(renderMode: RenderMode): boolean {
         return (
             renderMode === RenderMode.BillBoard ||
@@ -980,6 +1061,16 @@ export class SpriteBatch extends VFXBatch {
         );
     }
 
+    /** Multiplies `count` RGBA colours starting at `base` by a system's {@link ParticleSystem.tint}. */
+    private static applyTint(colors: Float32Array, base: number, count: number, tint: Vector4): void {
+        for (let j = 0, o = base; j < count; j++, o += 4) {
+            colors[o] *= tint.x;
+            colors[o + 1] *= tint.y;
+            colors[o + 2] *= tint.z;
+            colors[o + 3] *= tint.w;
+        }
+    }
+
     /**
      * Negates the size of each flipped particle along the axes it flips on,
      * starting at `base` in `sizes`. The billboard shader scales the quad by