babylon.quarks 0.23.0 → 0.24.0

package/src/QuarksUtil.ts

@@ -1,4 +1,6 @@
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Node} from '@babylonjs/core/node';
+import {EmitSubParticleSystem} from 'quarks.core';
 import {BatchedRenderer} from './BatchedRenderer';
 import {ParticleEmitter} from './ParticleEmitter';
 import {ParticleSystem} from './ParticleSystem';
@@ -54,24 +56,70 @@ export class QuarksUtil {
         });
     }
 
-    /** True when every emitter under `root` is a finished non-looping system (or looping). */
+    /**
+     * True when every system under `root` is finished: non-looping ones that
+     * ran their course, looping ones whose emission was ended (see
+     * {@link endEmit}) and whose particles are gone. A looping system still
+     * emitting keeps the effect unfinished.
+     */
     static isEffectFinished(root: Node): boolean {
         let found = false;
         let finished = true;
         QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
             found = true;
-            const system = emitter.system as unknown as ParticleSystem;
-            if (system.looping) {
-                finished = false;
-                return;
-            }
-            if (!system.isFinished()) {
+            if (!(emitter.system as unknown as ParticleSystem).isFinished()) {
                 finished = false;
             }
         });
         return found && finished;
     }
 
+    /**
+     * 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.
+     */
+    static instantiate(root: TransformNode, name?: string): TransformNode {
+        const copies = new Map<ParticleEmitter, ParticleEmitter>();
+        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 TransformNode) {
+                copy = new TransformNode(copyName ?? node.name, node.getScene());
+                copy.position.copyFrom(node.position);
+                copy.rotation.copyFrom(node.rotation);
+                copy.scaling.copyFrom(node.scaling);
+                if (node.rotationQuaternion) {
+                    copy.rotationQuaternion = node.rotationQuaternion.clone();
+                }
+                copy.setEnabled(node.isEnabled(false));
+            } else {
+                return null;
+            }
+            copy.parent = parent;
+            for (const child of node.getChildren()) {
+                copyNode(child, copy);
+            }
+            return copy;
+        };
+        const copy = copyNode(root, null, name) as TransformNode;
+        // 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) {
+                if (behavior instanceof EmitSubParticleSystem) {
+                    const target = copies.get(behavior.subParticleSystem as unknown as ParticleEmitter);
+                    if (target !== undefined) {
+                        behavior.subParticleSystem = target as unknown as typeof behavior.subParticleSystem;
+                    }
+                }
+            }
+        }
+        return copy;
+    }
+
     private static traverseNode(node: Node, callback: (node: Node) => void): void {
         callback(node);
         const children = node.getChildren();

package/src/SpriteBatch.ts

@@ -17,6 +17,7 @@ import {
     Vector3,
 } from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
+import {gather, sortByKey, SortScratch} from './instanceSort';
 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';
@@ -75,7 +76,7 @@ export class SpriteBatch extends VFXBatch {
     setupBuffers(): void {
         this.mesh.dispose();
         this.mesh = new Mesh('spriteBatch', this.scene);
-        this.mesh.alwaysSelectAsActiveMesh = true;
+        this.configureMesh();
 
         const vertexData = new VertexData();
         vertexData.positions = this.settings.instancingGeometry;
@@ -153,6 +154,113 @@ export class SpriteBatch extends VFXBatch {
         }
         this.disposeExpandableBuffers();
         this.buildExpandableBuffers();
+        this.sortScratch = undefined;
+        this.gatherScratch.length = 0;
+    }
+
+    /** The screen-size limits as a uniform value, or null when the batch has none that apply. */
+    private sizeLimits(): BVector2 | null {
+        const {minParticleSize, maxParticleSize} = this.settings;
+        if (!SpriteBatch.takesPivotAndFlip(this.settings.renderMode)) {
+            return null;
+        }
+        if (minParticleSize <= 0 && maxParticleSize === Infinity) {
+            return null;
+        }
+        // The shader clamps; an unlimited maximum is just a very large one.
+        return new BVector2(Math.max(0, minParticleSize), Math.min(maxParticleSize, 1e9));
+    }
+
+    private sortScratch?: SortScratch;
+    /** One spare array per attribute buffer, gathered into and swapped in; indexed by buffer slot. */
+    private readonly gatherScratch: Float32Array[] = [];
+
+    /**
+     * Reorders the `count` filled instances by the batch's sort mode, so that
+     * the later (covering) draws are the nearer or the chosen-age particles.
+     * The order is computed once as a permutation and every attribute buffer
+     * is gathered through it into a spare array that then takes its place.
+     */
+    private sortInstances(count: number, isMeshRender: boolean, isStretchedRender: boolean): void {
+        if (count < 2) {
+            return;
+        }
+        const scratch = (this.sortScratch ??= new SortScratch(this.maxParticles));
+        scratch.ensure(count);
+        const keys = scratch.keys;
+        const mode = this.settings.sortMode;
+        if (mode === 'distance') {
+            const camera = this.scene.activeCameras?.[0] ?? this.scene.activeCamera;
+            if (!camera) {
+                return;
+            }
+            const eye = camera.globalPosition;
+            const ex = eye.x;
+            const ey = eye.y;
+            const ez = eye.z;
+            const offsets = this.offsetBuffer;
+            // Farthest first: the nearer particle is drawn last and covers.
+            for (let i = 0, o = 0; i < count; i++, o += 3) {
+                const dx = offsets[o] - ex;
+                const dy = offsets[o + 1] - ey;
+                const dz = offsets[o + 2] - ez;
+                keys[i] = scratch.floatKey(dx * dx + dy * dy + dz * dz, true);
+            }
+        } else {
+            // Ages in the order the systems were filled, which is the instance order.
+            const youngestInFront = mode === 'youngestInFront';
+            const systems = this.visibleSystems;
+            let i = 0;
+            for (let s = 0; s < systems.length; s++) {
+                const system = systems[s];
+                const particleNum = system.particleNum;
+                const store = system.store;
+                if (particleNum === 0) {
+                    continue;
+                }
+                if (store === undefined) {
+                    const particles = system.particles;
+                    for (let j = 0; j < particleNum; j++) {
+                        keys[i++] = scratch.floatKey(particles[j].age, youngestInFront);
+                    }
+                    continue;
+                }
+                const scalars = store.scalars;
+                const stride = ParticleStore.SCALAR_STRIDE;
+                for (let j = 0, a = ParticleStore.AGE; j < particleNum; j++, a += stride) {
+                    keys[i++] = scratch.floatKey(scalars[a], youngestInFront);
+                }
+            }
+            if (i !== count) {
+                return;
+            }
+        }
+        const order = sortByKey(scratch, count);
+        this.offsetBuffer = this.gatherInto(0, this.offsetBuffer, order, count, 3);
+        this.sizeBuffer = this.gatherInto(1, this.sizeBuffer, order, count, 3);
+        this.colorBuffer = this.gatherInto(2, this.colorBuffer, order, count, 4);
+        this.uvTileBuffer = this.gatherInto(3, this.uvTileBuffer, order, count, 1);
+        this.rotationBuffer = this.gatherInto(4, this.rotationBuffer, order, count, isMeshRender ? 4 : 1);
+        if (isStretchedRender && this.velocityBuffer) {
+            this.velocityBuffer = this.gatherInto(5, this.velocityBuffer, order, count, 4);
+        }
+    }
+
+    /** Gathers `source` in `order` into the spare array of `slot` and returns it; the source becomes the spare. */
+    private gatherInto(
+        slot: number,
+        source: Float32Array,
+        order: Uint32Array,
+        count: number,
+        stride: number
+    ): Float32Array {
+        let spare = this.gatherScratch[slot];
+        if (spare === undefined || spare.length !== source.length) {
+            spare = new Float32Array(source.length);
+        }
+        gather(source, spare, order, count, stride);
+        this.gatherScratch[slot] = source;
+        return spare;
     }
 
     rebuildMaterial(): void {
@@ -161,7 +269,7 @@ export class SpriteBatch extends VFXBatch {
         // Effect.ShadersStore and defeat Babylon's compiled-effect cache.
         const shaderName = `quarksParticle_${this.settings.renderMode}`;
         this.lastStretchedSpeedFactor = Number.NaN;
-        const defines: string[] = [];
+        const defines: string[] = this.fogDefines();
 
         let vertexShader: ShaderSources;
         let fragmentShader: ShaderSources;
@@ -218,6 +326,10 @@ export class SpriteBatch extends VFXBatch {
         if (pivot) {
             defines.push('PIVOT');
         }
+        const sizeLimits = this.sizeLimits();
+        if (sizeLimits) {
+            defines.push('SIZE_LIMITS');
+        }
         const isMesh = this.settings.renderMode === RenderMode.Mesh;
         const lighting = this.settings.lighting ?? 'fixed';
         const lit = isMesh && lighting !== 'unlit';
@@ -244,7 +356,7 @@ export class SpriteBatch extends VFXBatch {
             attributes.push('velocity');
         }
 
-        const uniforms = ['world', 'view', 'projection', 'worldView', 'worldViewProjection'];
+        const uniforms = ['world', 'view', 'projection', 'worldView', 'worldViewProjection', ...VFXBatch.FOG_UNIFORMS];
         const samplers: string[] = [];
 
         if (this.settings.uTileCount > 1 || this.settings.vTileCount > 1) {
@@ -279,6 +391,9 @@ export class SpriteBatch extends VFXBatch {
         if (pivot) {
             uniforms.push('pivot');
         }
+        if (sizeLimits) {
+            uniforms.push('sizeLimits');
+        }
         if (lit) {
             uniforms.push('lightDirection');
             uniforms.push('lightColor');
@@ -354,6 +469,9 @@ export class SpriteBatch extends VFXBatch {
         if (pivot) {
             mat.setVector3('pivot', new BVector3(pivot.x, pivot.y, pivot.z));
         }
+        if (sizeLimits) {
+            mat.setVector2('sizeLimits', sizeLimits);
+        }
         if (lit) {
             this.writeFixedLighting(mat);
             if (lighting === 'scene') {
@@ -372,6 +490,7 @@ export class SpriteBatch extends VFXBatch {
             }
         }
 
+        this.bindFog(mat);
         mat.backFaceCulling = false;
 
         if (this.settings.materialTransparent) {
@@ -801,6 +920,7 @@ export class SpriteBatch extends VFXBatch {
         // Keep the mesh enabled even when count is 0 — toggling visibility off for a
         // single frame (common with short lifetimes + low emission overlap) causes flicker.
         this.mesh.forcedInstanceCount = index;
+        this.refreshBoundingInfo();
 
         if (index === 0) {
             // Slot 0 only needs clearing once per stretch of empty frames; re-uploading it every
@@ -813,6 +933,10 @@ export class SpriteBatch extends VFXBatch {
         }
         this.clearedInstanceUploaded = false;
 
+        if (this.settings.sortMode !== 'none') {
+            this.sortInstances(index, isMeshRender, isStretchedRender);
+        }
+
         // Upload only the slots actually filled this frame: the buffers are sized
         // for the high-water mark and are usually far larger than the live count.
         this.offsetVB.update(this.offsetBuffer.subarray(0, index * 3));

package/src/TrailBatch.ts

@@ -1,12 +1,12 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
-import {BoundingInfo} from '@babylonjs/core/Culling/boundingInfo';
 import {Constants} from '@babylonjs/core/Engines/constants';
 import {ShaderMaterial} from '@babylonjs/core/Materials/shaderMaterial';
-import {Vector2 as BVector2, Vector3 as BVector3} from '@babylonjs/core/Maths/math.vector';
+import {Vector2 as BVector2} from '@babylonjs/core/Maths/math.vector';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Matrix4, Quaternion, TrailParticle, TrailSettings, Vector3} from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
+import type {ParticleSystem} from './ParticleSystem';
 import {registerShaders, shaderLanguageFor} from './shaders/shaderLanguageSupport';
 import trail_frag from './shaders/trail_frag.glsl';
 import trail_frag_wgsl from './shaders/trail_frag.wgsl';
@@ -43,7 +43,7 @@ export class TrailBatch extends VFXBatch {
     setupBuffers(): void {
         this.mesh.dispose();
         this.mesh = new Mesh('trailBatch', this.scene);
-        this.mesh.alwaysSelectAsActiveMesh = true;
+        this.configureMesh();
         this.buildGeometryBuffers();
     }
 
@@ -110,15 +110,10 @@ export class TrailBatch extends VFXBatch {
         this.mesh.setVerticesBuffer(this.sideVB);
         this.mesh.setVerticesBuffer(this.widthVB);
 
-        // Disable bounding info recomputation
-        this.mesh.doNotSyncBoundingInfo = true;
-        const min = new BVector3(-10000, -10000, -10000);
-        const max = new BVector3(10000, 10000, 10000);
-        this.mesh.setBoundingInfo(new BoundingInfo(min, max));
+        // The bounds come from the ribbons each fill writes (configureMesh set
+        // the placeholder); the sub meshes have to share them.
         if (this.mesh.subMeshes) {
-            for (const sub of this.mesh.subMeshes) {
-                (sub as any)._boundingInfo = this.mesh.getBoundingInfo();
-            }
+            this.adoptMeshBounds();
         }
     }
 
@@ -139,7 +134,7 @@ export class TrailBatch extends VFXBatch {
         // Stable name: the trail shader source never varies, so registering it once
         // keeps Effect.ShadersStore bounded and lets Babylon reuse compiled effects.
         const shaderName = 'quarksTrail';
-        const defines: string[] = [];
+        const defines: string[] = this.fogDefines();
 
         if (this.settings.texture) {
             defines.push('USE_MAP');
@@ -162,6 +157,7 @@ export class TrailBatch extends VFXBatch {
             'lineWidth',
             'resolution',
             'sizeAttenuation',
+            ...VFXBatch.FOG_UNIFORMS,
         ];
         const samplers: string[] = [];
 
@@ -203,6 +199,7 @@ export class TrailBatch extends VFXBatch {
             }
         });
 
+        this.bindFog(mat);
         mat.backFaceCulling = false;
 
         if (this.settings.materialTransparent) {
@@ -266,6 +263,7 @@ export class TrailBatch extends VFXBatch {
 
         for (let s = 0; s < visibleSystems.length; s++) {
             const system = visibleSystems[s];
+            const firstVertex = index;
             TrailBatch.ensureWorldMatrix(system);
             const rotation = this.quaternion_;
             const translation = this.vector2_;
@@ -554,11 +552,50 @@ export class TrailBatch extends VFXBatch {
                     index += 2;
                 }
             }
+            this.measureSystemBounds(system as ParticleSystem, firstVertex, index);
         }
 
+        this.refreshBoundingInfo();
         this.uploadGeometry(index, triangles);
     }
 
+    /**
+     * Records a system's world bounds from the ribbon vertices just written for
+     * it, padded by the widest ribbon. The store only holds each trail's head,
+     * so this is where a trail's extent is known.
+     */
+    private measureSystemBounds(system: ParticleSystem, fromVertex: number, toVertex: number): void {
+        if (toVertex <= fromVertex || typeof system.setWorldBounds !== 'function') {
+            return;
+        }
+        const positions = this.positionBuffer;
+        let minX = Infinity;
+        let minY = Infinity;
+        let minZ = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        let maxZ = -Infinity;
+        // Each sample writes its position twice (both ribbon edges); one of the pair is enough.
+        for (let o = fromVertex * 3, end = toVertex * 3; o < end; o += 6) {
+            const x = positions[o];
+            const y = positions[o + 1];
+            const z = positions[o + 2];
+            if (x < minX) minX = x;
+            if (x > maxX) maxX = x;
+            if (y < minY) minY = y;
+            if (y > maxY) maxY = y;
+            if (z < minZ) minZ = z;
+            if (z > maxZ) maxZ = z;
+        }
+        const widths = this.widthBuffer;
+        let maxWidth = 0;
+        for (let v = fromVertex; v < toVertex; v += 2) {
+            const w = widths[v];
+            if (w > maxWidth) maxWidth = w;
+        }
+        system.setWorldBounds(minX, minY, minZ, maxX, maxY, maxZ, maxWidth);
+    }
+
     /**
      * Uploads the vertex data written by `update` and resizes the sub mesh.
      *

package/src/VFXBatch.ts

@@ -1,3 +1,5 @@
+import {BoundingInfo} from '@babylonjs/core/Culling/boundingInfo';
+import {Constants} from '@babylonjs/core/Engines/constants';
 import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {ShaderMaterial} from '@babylonjs/core/Materials/shaderMaterial';
 import {Color3} from '@babylonjs/core/Maths/math.color';
@@ -6,6 +8,20 @@ import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Vector3} from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
+import type {ParticleSystem} from './ParticleSystem';
+
+/**
+ * The order the particles of a batch are drawn in (Unity's Sort Mode). Alpha
+ * blended particles cover what was drawn before them, so the order shows.
+ *
+ * - `'none'`: as they are, system by system. Right for additive blending.
+ * - `'distance'`: farthest from the active camera first, so nearer particles
+ *   cover farther ones.
+ * - `'oldestInFront'` / `'youngestInFront'`: by age.
+ *
+ * Sorting runs over the whole batch after each fill. Trails are not sorted.
+ */
+export type SortMode = 'none' | 'distance' | 'oldestInFront' | 'youngestInFront';
 
 export enum RenderMode {
     BillBoard = 0,
@@ -130,8 +146,18 @@ export interface StoredBatchSettings {
     reflectionFaces: BaseTexture[] | null;
     reflectionAtlas: BaseTexture | null;
     layerMask: number;
+    /** Babylon rendering group the batch mesh draws in, see {@link VFXBatchSettings.renderingGroupId}. */
+    renderingGroupId: number;
+    /** Whether the scene's fog is applied, see {@link VFXBatchSettings.applyFog}. */
+    applyFog: boolean;
     /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
     pivot?: Vector3;
+    /** Draw order within the batch, see {@link SortMode}. */
+    sortMode: SortMode;
+    /** Smallest size a particle may have on screen, see {@link VFXBatchSettings.minParticleSize}. */
+    minParticleSize: number;
+    /** Largest size a particle may have on screen, see {@link VFXBatchSettings.maxParticleSize}. */
+    maxParticleSize: number;
     /** Mesh particle lighting, see {@link VFXBatchSettings.lighting}. */
     lighting?: MeshLighting;
     /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
@@ -144,7 +170,7 @@ export abstract class VFXBatch {
     settings: StoredBatchSettings;
     protected maxParticles: number;
     protected scene: Scene;
-    private readonly visibleSystems: IParticleSystem[] = [];
+    protected readonly visibleSystems: IParticleSystem[] = [];
 
     protected constructor(settings: VFXBatchSettings, scene: Scene) {
         this.scene = scene;
@@ -174,12 +200,135 @@ export abstract class VFXBatch {
             reflectionFaces: settings.reflectionFaces ?? null,
             reflectionAtlas: settings.reflectionAtlas ?? null,
             pivot: settings.pivot?.clone(),
+            sortMode: settings.sortMode ?? 'none',
+            minParticleSize: settings.minParticleSize ?? 0,
+            maxParticleSize: settings.maxParticleSize ?? Infinity,
             layerMask: settings.layerMask,
+            renderingGroupId: settings.renderingGroupId ?? 0,
+            applyFog: settings.applyFog ?? true,
             lighting: settings.lighting,
             rim: normalizeMeshRim(settings.rim),
         };
         this.mesh = new Mesh('vfxBatch', scene);
-        this.mesh.alwaysSelectAsActiveMesh = true;
+        this.configureMesh();
+    }
+
+    /**
+     * Applies the batch-level scene settings to {@link mesh}. Called on every
+     * mesh the batch creates, since the buffers rebuild it.
+     *
+     * The bounds of a batch mesh are not kept, so Babylon cannot sort it among
+     * the scene's transparent meshes by distance; `alphaIndex` from the
+     * system's render order puts it where the author said, and the rendering
+     * group and layer mask reach the mesh at all (they used to stop at the
+     * settings).
+     */
+    protected configureMesh(): void {
+        const mesh = this.mesh;
+        // Until the first fill measures the particles, the batch has no bounds
+        // to cull by and is drawn regardless. The instance data is already in
+        // world space, so the bounds never need the mesh's own matrix.
+        mesh.alwaysSelectAsActiveMesh = true;
+        mesh.doNotSyncBoundingInfo = true;
+        mesh.setBoundingInfo(new BoundingInfo(BVector3.Zero(), BVector3.Zero()));
+        mesh.layerMask = this.settings.layerMask;
+        mesh.renderingGroupId = this.settings.renderingGroupId;
+        mesh.alphaIndex = this.settings.renderOrder;
+        // The shaders fog themselves; Babylon's own fog pass does not apply to a ShaderMaterial.
+        mesh.applyFog = false;
+    }
+
+    private readonly boundsMin_ = new Vector3();
+    private readonly boundsMax_ = new Vector3();
+
+    /**
+     * Sets the batch mesh's bounds to the union of its filled systems' world
+     * bounds, so Babylon skips the draw when none of them is in view. Called
+     * after each fill, over the systems {@link getVisibleSystems} last returned.
+     * A batch whose systems have no measured bounds stays always drawn.
+     */
+    protected refreshBoundingInfo(): void {
+        const min = this.boundsMin_;
+        const max = this.boundsMax_;
+        let minX = Infinity;
+        let minY = Infinity;
+        let minZ = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        let maxZ = -Infinity;
+        let any = false;
+        const systems = this.visibleSystems;
+        for (let i = 0; i < systems.length; i++) {
+            const system = systems[i] as ParticleSystem;
+            if (system.particleNum === 0 || typeof system.getWorldBounds !== 'function') {
+                continue;
+            }
+            if (!system.getWorldBounds(min, max)) {
+                // Drawn but not measured: the batch cannot be culled this frame.
+                this.mesh.alwaysSelectAsActiveMesh = true;
+                return;
+            }
+            any = true;
+            if (min.x < minX) minX = min.x;
+            if (min.y < minY) minY = min.y;
+            if (min.z < minZ) minZ = min.z;
+            if (max.x > maxX) maxX = max.x;
+            if (max.y > maxY) maxY = max.y;
+            if (max.z > maxZ) maxZ = max.z;
+        }
+        if (!any) {
+            return;
+        }
+        const info = this.mesh.getBoundingInfo();
+        const bmin = info.minimum;
+        const bmax = info.maximum;
+        if (
+            bmin.x !== minX ||
+            bmin.y !== minY ||
+            bmin.z !== minZ ||
+            bmax.x !== maxX ||
+            bmax.y !== maxY ||
+            bmax.z !== maxZ
+        ) {
+            bmin.set(minX, minY, minZ);
+            bmax.set(maxX, maxY, maxZ);
+            info.reConstruct(bmin, bmax);
+        }
+        this.mesh.alwaysSelectAsActiveMesh = false;
+    }
+
+    /**
+     * Fog defines and uniforms for a material of this batch, and the per-bind
+     * upload of the scene's current fog. Mode 0 (none) when the scene has fog
+     * disabled, so toggling fog at runtime needs no recompile.
+     */
+    protected static readonly FOG_UNIFORMS = ['vFogInfos', 'vFogColor'];
+
+    protected fogDefines(): string[] {
+        if (!this.settings.applyFog) {
+            return [];
+        }
+        const additive =
+            this.settings.materialTransparent &&
+            (this.settings.materialBlendMode === Constants.ALPHA_ADD ||
+                this.settings.materialBlendMode === Constants.ALPHA_ONEONE);
+        return additive ? ['FOG', 'FOG_ADDITIVE'] : ['FOG'];
+    }
+
+    protected bindFog(material: ShaderMaterial): void {
+        if (!this.settings.applyFog) {
+            return;
+        }
+        const scene = this.scene;
+        material.onBindObservable.add(() => {
+            const effect = material.getEffect();
+            if (!effect) {
+                return;
+            }
+            const mode = scene.fogEnabled ? scene.fogMode : Scene.FOGMODE_NONE;
+            effect.setFloat4('vFogInfos', mode, scene.fogStart, scene.fogEnd, scene.fogDensity);
+            effect.setColor3('vFogColor', scene.fogColor);
+        });
     }
 
     addSystem(system: IParticleSystem) {
@@ -199,7 +348,9 @@ export abstract class VFXBatch {
         const visibleSystems = this.visibleSystems;
         let count = 0;
         for (const system of this.systems) {
-            if (system.emitter.visible) {
+            // A culled system's particles are off every camera's screen; filling
+            // them in would only cost the copy and widen the batch's bounds.
+            if (system.emitter.visible && (system as ParticleSystem).culled !== true) {
                 visibleSystems[count++] = system;
             }
         }

package/src/index.ts

@@ -6,6 +6,8 @@ export * from 'quarks.core';
 export {BatchedParticleRenderer} from './BatchedParticleRenderer';
 export {BatchedRenderer} from './BatchedRenderer';
 export type {AdaptivePerformanceOptions, AdaptivePerformanceState, VFXBatchSettings} from './BatchedRenderer';
+export {EffectPool} from './EffectPool';
+export type {EffectPoolOptions} from './EffectPool';
 export {
     cacheEnvAtlas,
     createEnvAtlasFromFaceUrls,
@@ -21,6 +23,7 @@ export type {
     BabylonMetaData,
     BurstParameters,
     BurstParametersJSON,
+    CullingMode,
     ParticleSystemJSONParameters,
     ParticleSystemParameters,
 } from './ParticleSystem';
@@ -39,7 +42,7 @@ export * from './shaders/';
 export {SpriteBatch} from './SpriteBatch';
 export {TrailBatch} from './TrailBatch';
 export {defaultMeshLighting, meshRimEqual, normalizeMeshRim, RenderMode, VFXBatch} from './VFXBatch';
-export type {MeshLighting, MeshLightingSettings, MeshRim, StoredBatchSettings} from './VFXBatch';
+export type {MeshLighting, MeshLightingSettings, MeshRim, SortMode, StoredBatchSettings} from './VFXBatch';
 
 // Re-export quarks.core types (interfaces - type-only)
 export type {