babylon.quarks 0.20.0 → 0.23.0

package/src/TrailBatch.ts

@@ -56,6 +56,12 @@ export class TrailBatch extends VFXBatch {
         this.widthBuffer = new Float32Array(this.maxParticles * 2);
         this.colorBuffer = new Float32Array(this.maxParticles * 8);
         this.indexBuffer = new Uint32Array(this.maxParticles * 6);
+        // Vertices come in pairs, one per side of the ribbon, so the side never
+        // changes: written once here and never uploaded again.
+        for (let i = 0; i < this.sideBuffer.length; i += 2) {
+            this.sideBuffer[i] = 1;
+            this.sideBuffer[i + 1] = -1;
+        }
 
         // Initialize with full-capacity buffers (updatable) and a dummy triangle
         this.positionBuffer[0] = 0;
@@ -216,10 +222,21 @@ export class TrailBatch extends VFXBatch {
     private vector3_ = new Vector3();
     private quaternion_ = new Quaternion();
 
-    /** Forces the emitter's world matrix to be current before sampling it. */
+    /**
+     * Brings the emitter's world matrix up to date when its transform changed.
+     *
+     * Babylon only recomputes a world matrix once per render id, so a frame that
+     * moves the emitter after that (or a step driven without rendering) would
+     * draw the ribbon against the old one. Recomputing unconditionally every
+     * frame costs a matrix compose per system; checking the transform cache
+     * first makes a still emitter free.
+     */
     private static ensureWorldMatrix(system: IParticleSystem): void {
-        const emitter = system.emitter as {computeWorldMatrix?: (force: boolean) => void};
-        if (emitter.computeWorldMatrix) {
+        const emitter = system.emitter as {
+            computeWorldMatrix?: (force: boolean) => void;
+            isSynchronized?: () => boolean;
+        };
+        if (emitter.computeWorldMatrix && (!emitter.isSynchronized || !emitter.isSynchronized())) {
             emitter.computeWorldMatrix(true);
         }
     }
@@ -327,31 +344,46 @@ export class TrailBatch extends VFXBatch {
                     1 / (stepFraction !== 0 ? particleHistoryLength : Math.max(1, particleHistoryLength - 1));
 
                 // Walk the ring buffer oldest-first with hand-rolled wrapping so the
-                // inner loop stays free of modulo operations.
+                // inner loop stays free of modulo operations. Each sample is brought
+                // into world space once: the point written as `next` on one
+                // iteration is `current` on the following one and `previous` on
+                // the one after that.
                 let currentSlot = particle.getHistoryIndex(0);
-                let previousSlot = currentSlot;
+                let currentX = historyPositions[currentSlot * 3];
+                let currentY = historyPositions[currentSlot * 3 + 1];
+                let currentZ = historyPositions[currentSlot * 3 + 2];
+                if (!samplesInWorld) {
+                    const w = 1 / (m03 * currentX + m13 * currentY + m23 * currentZ + m33);
+                    const tx = (m00 * currentX + m10 * currentY + m20 * currentZ + m30) * w;
+                    const ty = (m01 * currentX + m11 * currentY + m21 * currentZ + m31) * w;
+                    currentZ = (m02 * currentX + m12 * currentY + m22 * currentZ + m32) * w;
+                    currentX = tx;
+                    currentY = ty;
+                }
+                let previousX = currentX;
+                let previousY = currentY;
+                let previousZ = currentZ;
 
                 for (let i = 0; i < particleHistoryLength; i++, index += 2) {
-                    const nextSlot =
-                        i + 1 < particleHistoryLength
-                            ? currentSlot + 1 === historyCapacity
-                                ? 0
-                                : currentSlot + 1
-                            : currentSlot;
-
-                    const currentPosIndex = currentSlot * 3;
-                    const previousPosIndex = previousSlot * 3;
-                    const nextPosIndex = nextSlot * 3;
-
-                    let currentX = historyPositions[currentPosIndex];
-                    let currentY = historyPositions[currentPosIndex + 1];
-                    let currentZ = historyPositions[currentPosIndex + 2];
-                    let previousX = historyPositions[previousPosIndex];
-                    let previousY = historyPositions[previousPosIndex + 1];
-                    let previousZ = historyPositions[previousPosIndex + 2];
-                    let nextX = historyPositions[nextPosIndex];
-                    let nextY = historyPositions[nextPosIndex + 1];
-                    let nextZ = historyPositions[nextPosIndex + 2];
+                    let nextX = currentX;
+                    let nextY = currentY;
+                    let nextZ = currentZ;
+                    let nextSlot = currentSlot;
+                    if (i + 1 < particleHistoryLength) {
+                        nextSlot = currentSlot + 1 === historyCapacity ? 0 : currentSlot + 1;
+                        const nextPosIndex = nextSlot * 3;
+                        nextX = historyPositions[nextPosIndex];
+                        nextY = historyPositions[nextPosIndex + 1];
+                        nextZ = historyPositions[nextPosIndex + 2];
+                        if (!samplesInWorld) {
+                            const w = 1 / (m03 * nextX + m13 * nextY + m23 * nextZ + m33);
+                            const tx = (m00 * nextX + m10 * nextY + m20 * nextZ + m30) * w;
+                            const ty = (m01 * nextX + m11 * nextY + m21 * nextZ + m31) * w;
+                            nextZ = (m02 * nextX + m12 * nextY + m22 * nextZ + m32) * w;
+                            nextX = tx;
+                            nextY = ty;
+                        }
+                    }
 
                     const currentSize = historySizes[currentSlot];
                     const currentColorIndex = colorFromParticle ? particleColorIndex : currentSlot * 4;
@@ -360,33 +392,6 @@ export class TrailBatch extends VFXBatch {
                     const currentColorZ = colors[currentColorIndex + 2];
                     const currentColorW = colors[currentColorIndex + 3];
 
-                    previousSlot = currentSlot;
-                    currentSlot = nextSlot;
-
-                    if (!samplesInWorld) {
-                        // Inlined point transforms — three per trail sample.
-                        let w = 1 / (m03 * currentX + m13 * currentY + m23 * currentZ + m33);
-                        let tx = (m00 * currentX + m10 * currentY + m20 * currentZ + m30) * w;
-                        let ty = (m01 * currentX + m11 * currentY + m21 * currentZ + m31) * w;
-                        currentZ = (m02 * currentX + m12 * currentY + m22 * currentZ + m32) * w;
-                        currentX = tx;
-                        currentY = ty;
-
-                        w = 1 / (m03 * previousX + m13 * previousY + m23 * previousZ + m33);
-                        tx = (m00 * previousX + m10 * previousY + m20 * previousZ + m30) * w;
-                        ty = (m01 * previousX + m11 * previousY + m21 * previousZ + m31) * w;
-                        previousZ = (m02 * previousX + m12 * previousY + m22 * previousZ + m32) * w;
-                        previousX = tx;
-                        previousY = ty;
-
-                        w = 1 / (m03 * nextX + m13 * nextY + m23 * nextZ + m33);
-                        tx = (m00 * nextX + m10 * nextY + m20 * nextZ + m30) * w;
-                        ty = (m01 * nextX + m11 * nextY + m21 * nextZ + m31) * w;
-                        nextZ = (m02 * nextX + m12 * nextY + m22 * nextZ + m32) * w;
-                        nextX = tx;
-                        nextY = ty;
-                    }
-
                     const pi = index * 3;
                     this.positionBuffer[pi] = currentX;
                     this.positionBuffer[pi + 1] = currentY;
@@ -409,9 +414,6 @@ export class TrailBatch extends VFXBatch {
                     this.nextBuffer[pi + 4] = nextY;
                     this.nextBuffer[pi + 5] = nextZ;
 
-                    this.sideBuffer[index] = 1;
-                    this.sideBuffer[index + 1] = -1;
-
                     if (systemWorldSpace || particle.parentMatrix) {
                         this.widthBuffer[index] = currentSize;
                         this.widthBuffer[index + 1] = currentSize;
@@ -448,6 +450,14 @@ export class TrailBatch extends VFXBatch {
                         this.indexBuffer[triangles * 3 + 2] = index + 3;
                         triangles++;
                     }
+
+                    previousX = currentX;
+                    previousY = currentY;
+                    previousZ = currentZ;
+                    currentX = nextX;
+                    currentY = nextY;
+                    currentZ = nextZ;
+                    currentSlot = nextSlot;
                 }
 
                 // Live tip: same place a sprite would be drawn this frame, past
@@ -505,9 +515,6 @@ export class TrailBatch extends VFXBatch {
                     this.nextBuffer[headPi + 4] = tipY;
                     this.nextBuffer[headPi + 5] = tipZ;
 
-                    this.sideBuffer[index] = 1;
-                    this.sideBuffer[index + 1] = -1;
-
                     const tipSize = particle.size.x;
                     if (systemWorldSpace || particle.parentMatrix) {
                         this.widthBuffer[index] = tipSize;
@@ -560,22 +567,30 @@ export class TrailBatch extends VFXBatch {
      * costs that loop its optimised code.
      */
     private uploadGeometry(index: number, triangles: number): void {
+        const geometry = this.mesh.geometry;
+        const indexBuffer = geometry?.getIndexBuffer();
         if (index > 0 && triangles > 0) {
             // Upload only the vertices written this frame; the buffers are sized for
             // the high-water mark of every system in the batch.
             this.mesh.updateVerticesData(VertexBuffer.PositionKind, this.positionBuffer.subarray(0, index * 3));
             this.mesh.updateVerticesData(VertexBuffer.UVKind, this.uvBuffer.subarray(0, index * 2));
-            this.mesh.updateIndices(this.indexBuffer.subarray(0, triangles * 3));
+            // Straight to the GPU buffer. Going through `mesh.updateIndices` with a
+            // range whose length changes every frame makes Babylon copy the
+            // indices, rebuild the sub mesh and recompute its bounds from the
+            // whole position buffer, all of which this batch then undoes.
+            if (indexBuffer) {
+                this.scene
+                    .getEngine()
+                    .updateDynamicIndexBuffer(indexBuffer, this.indexBuffer.subarray(0, triangles * 3), 0);
+            }
             this.previousVB.update(this.previousBuffer.subarray(0, index * 3));
             this.nextVB.update(this.nextBuffer.subarray(0, index * 3));
-            this.sideVB.update(this.sideBuffer.subarray(0, index));
             this.widthVB.update(this.widthBuffer.subarray(0, index));
 
             const colorVB = this.mesh.getVertexBuffer(VertexBuffer.ColorKind);
             if (colorVB) colorVB.update(this.colorBuffer.subarray(0, index * 4));
 
             if (this.mesh.subMeshes && this.mesh.subMeshes.length > 0) {
-                this.adoptMeshBounds();
                 this.mesh.subMeshes[0].indexCount = triangles * 3;
                 this.mesh.subMeshes[0].verticesCount = index;
             }
@@ -593,8 +608,9 @@ export class TrailBatch extends VFXBatch {
             // every empty frame.
             if (!this.drawsNothing) {
                 this.indexBuffer.fill(0, 0, 6);
-                this.mesh.updateIndices(this.indexBuffer.subarray(0, 6));
-                this.adoptMeshBounds();
+                if (indexBuffer) {
+                    this.scene.getEngine().updateDynamicIndexBuffer(indexBuffer, this.indexBuffer.subarray(0, 6), 0);
+                }
                 this.drawsNothing = true;
             }
             this.mesh.subMeshes[0].indexCount = 6;

package/src/VFXBatch.ts

@@ -1,5 +1,7 @@
 import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {ShaderMaterial} from '@babylonjs/core/Materials/shaderMaterial';
+import {Color3} from '@babylonjs/core/Maths/math.color';
+import {Vector3 as BVector3} from '@babylonjs/core/Maths/math.vector';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Vector3} from 'quarks.core';
@@ -14,6 +16,96 @@ export enum RenderMode {
     VerticalBillBoard = 5,
 }
 
+/**
+ * How mesh particles are lit.
+ *
+ * - `'fixed'` (default): one directional light plus ambient, the same for every
+ *   mesh batch of a renderer, set with {@link BatchedRenderer.setMeshLighting}.
+ * - `'unlit'`: no lighting term — the texture times the particle colour, for
+ *   emissive meshes (fire, energy, glowing blades).
+ * - `'scene'`: follows the scene's first enabled `DirectionalLight` or
+ *   `HemisphericLight` every frame, falling back to the fixed light when there
+ *   is none.
+ *
+ * Only mesh particles are lit; other render modes ignore it.
+ */
+export type MeshLighting = 'unlit' | 'fixed' | 'scene';
+
+/** The light {@link MeshLighting} `'fixed'` mesh particles are lit by. */
+export interface MeshLightingSettings {
+    /** Direction the light travels in, world space. Default `(0.4, -1, 0.6)`. */
+    direction: BVector3;
+    /** Light colour, intensity folded in. Default white. */
+    color: Color3;
+    /** Light every face gets regardless of its direction. Default `(0.35, 0.35, 0.35)`. */
+    ambient: Color3;
+}
+
+/** The light mesh particles have always been lit by. */
+export function defaultMeshLighting(): MeshLightingSettings {
+    return {
+        direction: new BVector3(0.4, -1, 0.6),
+        color: new Color3(1, 1, 1),
+        ambient: new Color3(0.35, 0.35, 0.35),
+    };
+}
+
+/**
+ * A rim (Fresnel) term on mesh particles: a colour that grows where the surface
+ * turns away from the camera, `pow(1 - |N·V|, power) * strength`. Unset: no rim.
+ * Only mesh particles draw it.
+ */
+export interface MeshRim {
+    /** Edge colour, linear RGB. Default `[1, 1, 1]`. */
+    color: [number, number, number];
+    /** Falloff exponent; higher keeps the rim to a thinner edge. Default 2. */
+    power: number;
+    /** How much of the rim is applied, usually 0…1. Default 1. */
+    strength: number;
+    /**
+     * `'add'` (default) adds the colour, for a glowing edge; `'mix'` blends the
+     * surface toward it, for an outline (a dark ink line with a dark colour).
+     */
+    mode: 'add' | 'mix';
+}
+
+/**
+ * A complete rim from a partial one, every field defaulted and kept in range,
+ * or undefined when `rim` is unset.
+ */
+export function normalizeMeshRim(rim: Partial<MeshRim> | null | undefined): MeshRim | undefined {
+    if (!rim || typeof rim !== 'object') {
+        return undefined;
+    }
+    const color = Array.isArray(rim.color) ? rim.color : [1, 1, 1];
+    const channel = (value: unknown, fallback: number) =>
+        typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    return {
+        color: [channel(color[0], 1), channel(color[1], 1), channel(color[2], 1)],
+        power: Math.max(0.01, channel(rim.power, 2)),
+        strength: Math.max(0, channel(rim.strength, 1)),
+        mode: rim.mode === 'mix' ? 'mix' : 'add',
+    };
+}
+
+/** True when both describe the same rim (or both none). */
+export function meshRimEqual(a: MeshRim | undefined, b: MeshRim | undefined): boolean {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b) {
+        return false;
+    }
+    return (
+        a.mode === b.mode &&
+        a.power === b.power &&
+        a.strength === b.strength &&
+        a.color[0] === b.color[0] &&
+        a.color[1] === b.color[1] &&
+        a.color[2] === b.color[2]
+    );
+}
+
 export interface StoredBatchSettings {
     instancingGeometry: Float32Array;
     instancingIndices: Uint32Array | Uint16Array;
@@ -40,6 +132,10 @@ export interface StoredBatchSettings {
     layerMask: number;
     /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
     pivot?: Vector3;
+    /** Mesh particle lighting, see {@link VFXBatchSettings.lighting}. */
+    lighting?: MeshLighting;
+    /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
+    rim?: MeshRim;
 }
 
 export abstract class VFXBatch {
@@ -79,6 +175,8 @@ export abstract class VFXBatch {
             reflectionAtlas: settings.reflectionAtlas ?? null,
             pivot: settings.pivot?.clone(),
             layerMask: settings.layerMask,
+            lighting: settings.lighting,
+            rim: normalizeMeshRim(settings.rim),
         };
         this.mesh = new Mesh('vfxBatch', scene);
         this.mesh.alwaysSelectAsActiveMesh = true;
@@ -116,6 +214,9 @@ export abstract class VFXBatch {
         }
     }
 
+    /** Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it. */
+    applyMeshLighting(_lighting: MeshLightingSettings): void {}
+
     abstract setupBuffers(): void;
     abstract expandBuffers(target: number): void;
     abstract rebuildMaterial(): void;

package/src/index.ts

@@ -25,15 +25,21 @@ export type {
     ParticleSystemParameters,
 } from './ParticleSystem';
 export {QuarksLoader} from './QuarksLoader';
-export type {QuarksLoaderOptions} from './QuarksLoader';
+export type {
+    QuarksBatchLoadOptions,
+    QuarksJSONLoadEntry,
+    QuarksLoaderOptions,
+    QuarksResourceKind,
+    QuarksResourceResolver,
+} from './QuarksLoader';
 export {QuarksPrefab} from './QuarksPrefab';
 export type {AnimationData, QuarksTimelineClip} from './QuarksPrefab';
 export {QuarksUtil} from './QuarksUtil';
 export * from './shaders/';
 export {SpriteBatch} from './SpriteBatch';
 export {TrailBatch} from './TrailBatch';
-export {RenderMode, VFXBatch} from './VFXBatch';
-export type {StoredBatchSettings} from './VFXBatch';
+export {defaultMeshLighting, meshRimEqual, normalizeMeshRim, RenderMode, VFXBatch} from './VFXBatch';
+export type {MeshLighting, MeshLightingSettings, MeshRim, StoredBatchSettings} from './VFXBatch';
 
 // Re-export quarks.core types (interfaces - type-only)
 export type {

package/src/shaders/particle_physics_frag.glsl.ts

@@ -4,9 +4,11 @@ varying vec4 vColor;
 varying vec3 vNormal;
 varying vec3 vWorldPos;
 
+#ifndef MESH_UNLIT
 uniform vec3 lightDirection;
 uniform vec3 lightColor;
 uniform vec3 ambientColor;
+#endif
 
 #ifdef TILE_BLEND
 varying vec2 vUV2;
@@ -17,11 +19,19 @@ varying float vTileBlend;
 uniform sampler2D map;
 #endif
 
+#if defined(USE_ENVMAP_ATLAS) || defined(MESH_RIM)
+uniform vec3 eyePosition;
+#endif
+
+#ifdef MESH_RIM
+uniform vec3 rimColor;
+uniform vec2 rimParams;
+#endif
+
 // One 3×2 atlas (px py pz / nx ny nz). Avoids samplerCube and multi-face
 // sampler bindings that raise GL_INVALID_OPERATION on iOS WebKit.
 #ifdef USE_ENVMAP_ATLAS
 uniform sampler2D envAtlas;
-uniform vec3 eyePosition;
 uniform float reflectionLevel;
 
 vec3 sampleEnvAtlas(vec3 r) {
@@ -94,11 +104,15 @@ void main() {
 #endif
 
     vec3 N = normalize(vNormal);
+#ifdef MESH_UNLIT
+    vec3 color = baseColor.rgb;
+#else
     vec3 L = normalize(-lightDirection);
     float NdotL = max(dot(N, L), 0.0);
     vec3 litColor = ambientColor + lightColor * NdotL;
 
     vec3 color = baseColor.rgb * litColor;
+#endif
 
 #ifdef USE_ENVMAP_ATLAS
     vec3 viewDir = normalize(vWorldPos - eyePosition);
@@ -106,6 +120,17 @@ void main() {
     color += sampleEnvAtlas(reflectionCoords) * reflectionLevel;
 #endif
 
+#ifdef MESH_RIM
+    // Fresnel: strongest where the surface turns away from the camera.
+    vec3 V = normalize(eyePosition - vWorldPos);
+    float rim = pow(1.0 - abs(dot(N, V)), rimParams.x) * rimParams.y;
+    #ifdef MESH_RIM_MIX
+    color = mix(color, rimColor, clamp(rim, 0.0, 1.0));
+    #else
+    color += rimColor * rim;
+    #endif
+#endif
+
     gl_FragColor = vec4(color, baseColor.a);
 
 #ifdef SOFT_PARTICLES

package/src/shaders/particle_physics_frag.wgsl.ts

@@ -4,9 +4,11 @@ varying vColor: vec4f;
 varying vNormal: vec3f;
 varying vWorldPos: vec3f;
 
+#ifndef MESH_UNLIT
 uniform lightDirection: vec3f;
 uniform lightColor: vec3f;
 uniform ambientColor: vec3f;
+#endif
 
 #ifdef TILE_BLEND
 varying vUV2: vec2f;
@@ -18,10 +20,18 @@ var mapSampler: sampler;
 var map: texture_2d<f32>;
 #endif
 
+#if defined(USE_ENVMAP_ATLAS) || defined(MESH_RIM)
+uniform eyePosition: vec3f;
+#endif
+
+#ifdef MESH_RIM
+uniform rimColor: vec3f;
+uniform rimParams: vec2f;
+#endif
+
 #ifdef USE_ENVMAP_ATLAS
 var envAtlasSampler: sampler;
 var envAtlas: texture_2d<f32>;
-uniform eyePosition: vec3f;
 uniform reflectionLevel: f32;
 
 fn sampleEnvAtlas(r: vec3f) -> vec3f {
@@ -95,11 +105,15 @@ fn main(input: FragmentInputs) -> FragmentOutputs {
 #endif
 
     let N = normalize(fragmentInputs.vNormal);
+#ifdef MESH_UNLIT
+    var color = baseColor.rgb;
+#else
     let L = normalize(-uniforms.lightDirection);
     let NdotL = max(dot(N, L), 0.0);
     let litColor = uniforms.ambientColor + uniforms.lightColor * NdotL;
 
     var color = baseColor.rgb * litColor;
+#endif
 
 #ifdef USE_ENVMAP_ATLAS
     let viewDir = normalize(fragmentInputs.vWorldPos - uniforms.eyePosition);
@@ -107,6 +121,17 @@ fn main(input: FragmentInputs) -> FragmentOutputs {
     color += sampleEnvAtlas(reflectionCoords) * uniforms.reflectionLevel;
 #endif
 
+#ifdef MESH_RIM
+    // Fresnel: strongest where the surface turns away from the camera.
+    let V = normalize(uniforms.eyePosition - fragmentInputs.vWorldPos);
+    let rimTerm = pow(1.0 - abs(dot(N, V)), uniforms.rimParams.x) * uniforms.rimParams.y;
+    #ifdef MESH_RIM_MIX
+    color = mix(color, uniforms.rimColor, clamp(rimTerm, 0.0, 1.0));
+    #else
+    color += uniforms.rimColor * rimTerm;
+    #endif
+#endif
+
     var finalColor = vec4f(color, baseColor.a);
 
 #ifdef SOFT_PARTICLES