babylon.quarks 0.24.0 → 0.25.0

package/dist/types/index.d.ts

@@ -1182,6 +1182,14 @@ interface IParticleSystem {
      * @type {number}
      */
     simulationStep?: number;
+    /**
+     * What world-space forces and speed limits are multiplied by: the
+     * emitter's world scale when the system scales its motion with it (a
+     * world-space system in `'hierarchy'` scaling mode), 1 or undefined
+     * otherwise.
+     * @type {number}
+     */
+    motionScale?: number;
     /**
      * Whether this system only emits through another system, which is when its
      * particles carry their own parent transform.
@@ -2114,17 +2122,67 @@ declare class ForceOverLife implements Behavior {
 }
 
 /**
- * apply tile number of particle texture by particles' life.
+ * How {@link FrameOverLife} plays the sheet, beyond sampling `frame` over the
+ * particle's life. Every field is optional, and leaving them all out keeps the
+ * plain life-fraction behaviour.
+ */
+interface FrameOverLifeOptions {
+    /**
+     * Frames per second. Above zero the sheet plays by the particle's age in
+     * seconds instead of its life fraction, Unity's "FPS" time mode: `frame`
+     * then gives the first frame of the segment, and the frame advances by one
+     * every `1 / fps` seconds. Needs {@link frameCount}.
+     */
+    fps?: number;
+    /**
+     * Life mode only: how many times `frame` plays over the particle's life
+     * (Unity's "Cycles"). Default 1.
+     */
+    cycles?: number;
+    /**
+     * Frames in the segment that plays, from the first frame. In FPS mode the
+     * frame wraps (or holds, see {@link loop}) at it, counted from `frame`;
+     * in life mode the curve plus a {@link startFrame} offset wraps into
+     * `[0, frameCount)`, so the curve should start at frame 0. 0, the default,
+     * means no segment.
+     */
+    frameCount?: number;
+    /** FPS mode: wrap back to the first frame of the segment (default) or hold its last. */
+    loop?: boolean;
+    /**
+     * Per-particle frame offset, sampled once at birth: an `IntervalValue(0, n)`
+     * starts each particle on a random frame (Unity's "Start Frame"). Default none.
+     */
+    startFrame?: ValueGenerator;
+}
+/**
+ * Sets the particle's texture tile (`uvTile`) over its life.
+ *
+ * By default `frame` is sampled at the particle's life fraction. The
+ * {@link FrameOverLifeOptions} add the rest of Unity's texture sheet
+ * animation: playing at a fixed frame rate, several cycles per life, a frame
+ * segment that loops or holds, and a random start frame.
  */
 declare class FrameOverLife implements Behavior {
     type: string;
     private _frame;
-    constructor(frame: FunctionValueGenerator | ValueGenerator);
+    fps: number;
+    cycles: number;
+    frameCount: number;
+    loop: boolean;
+    startFrame?: ValueGenerator;
+    constructor(frame: FunctionValueGenerator | ValueGenerator, options?: FrameOverLifeOptions);
     get frame(): FunctionValueGenerator | ValueGenerator;
     set frame(frame: FunctionValueGenerator | ValueGenerator);
+    /** True when no option is in play and the frame is just `frame` at the life fraction. */
+    isPlain(): boolean;
     initialize(particle: Particle): void;
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
+    /** The tile for `particle` at `age` seconds, `t` being that age over its life. */
+    frameAt(particle: Particle, age: number, t: number): number;
+    private offset;
+    private static wrap;
     private sampleFrame;
     frameUpdate(delta: number): void;
     toJSON(): any;
@@ -2188,7 +2246,11 @@ declare class LimitSpeedOverLife implements Behavior {
     speed: FunctionValueGenerator;
     dampen: number;
     type: string;
-    initialize(particle: Particle): void;
+    /** Learned in {@link initialize}; its motion scale multiplies the limit of a world-space system. */
+    ps?: IParticleSystem;
+    initialize(particle: Particle, particleSystem?: IParticleSystem): void;
+    /** What the limit is multiplied by: the system's motion scale in world space, else 1. */
+    motionScale(): number;
     constructor(speed: FunctionValueGenerator, dampen: number);
     update(particle: Particle, delta: number): void;
     updateAll(particles: Array<Particle>, count: number, delta: number): void;
@@ -3262,7 +3324,14 @@ declare enum RenderMode {
     Mesh = 2,
     Trail = 3,
     HorizontalBillBoard = 4,
-    VerticalBillBoard = 5
+    VerticalBillBoard = 5,
+    /**
+     * A quad laid from each particle to the system's {@link ParticleSystem.beamEnd}
+     * and turned about its length to face the camera (a line renderer): U runs
+     * from the particle (0) to the end (1), V across, the particle's size is
+     * the width. Lightning, tethers, lasers.
+     */
+    Beam = 6
 }
 /**
  * How mesh particles are lit.
@@ -3314,6 +3383,36 @@ interface MeshRim {
 declare function normalizeMeshRim(rim: Partial<MeshRim> | null | undefined): MeshRim | undefined;
 /** True when both describe the same rim (or both none). */
 declare function meshRimEqual(a: MeshRim | undefined, b: MeshRim | undefined): boolean;
+/**
+ * Alpha erosion: the particle's alpha decides how much of its shape is left
+ * instead of how transparent it is, so `ColorOverLife` fading alpha out
+ * dissolves (noise mask) or wipes (gradient mask) the shape away. See
+ * {@link VFXBatchSettings.erosion}.
+ */
+interface ParticleErosion {
+    /**
+     * Mask whose red channel orders what goes first, sampled with the
+     * particle's UV (the quad, mesh or trail UV, unscrolled). Null: the map's
+     * own alpha, so a soft shape shrinks from its edges.
+     */
+    mask: BaseTexture | null;
+    /** Width of the soft transition at the cut, in mask units. Default 0.05. */
+    softness: number;
+    /** Width of the glowing band above the cut, in mask units; 0 (default) draws none. */
+    edgeWidth: number;
+    /** Colour added in the edge band, linear RGB, may exceed 1. Default `[1, 1, 1]`. */
+    edgeColor: [number, number, number];
+    /** Mask UV scroll, UV units per second. Default `[0, 0]`. */
+    maskScroll: [number, number];
+}
+/** A complete erosion from a partial one, every field defaulted, or undefined when `erosion` is unset. */
+declare function normalizeErosion(erosion: Partial<ParticleErosion> | null | undefined): ParticleErosion | undefined;
+/** True when both describe the same erosion (or both none). */
+declare function erosionEqual(a: ParticleErosion | undefined, b: ParticleErosion | undefined): boolean;
+/** A UV scroll speed, or undefined when unset or zero. */
+declare function normalizeUVScroll(scroll: ArrayLike<number> | null | undefined): [number, number] | undefined;
+/** True when both scroll the same way (or both not at all). */
+declare function uvScrollEqual(a: [number, number] | undefined, b: [number, number] | undefined): boolean;
 interface StoredBatchSettings {
     instancingGeometry: Float32Array;
     instancingIndices: Uint32Array | Uint16Array;
@@ -3354,6 +3453,12 @@ interface StoredBatchSettings {
     lighting?: MeshLighting;
     /** Mesh particle rim, see {@link VFXBatchSettings.rim}. */
     rim?: MeshRim;
+    /** Map UV scroll, see {@link VFXBatchSettings.uvScroll}. */
+    uvScroll?: [number, number];
+    /** Colour ramp for the map, see {@link VFXBatchSettings.gradientMap}. */
+    gradientMap: BaseTexture | null;
+    /** Alpha erosion, see {@link VFXBatchSettings.erosion}. */
+    erosion?: ParticleErosion;
 }
 declare abstract class VFXBatch {
     mesh: Mesh;
@@ -3391,6 +3496,17 @@ declare abstract class VFXBatch {
     protected static readonly FOG_UNIFORMS: string[];
     protected fogDefines(): string[];
     protected bindFog(material: ShaderMaterial): void;
+    /**
+     * Seconds of renderer time, set by the renderer before each fill; what UV
+     * and erosion mask scrolling advance by.
+     */
+    time: number;
+    /** Defines of the texture effects (see `shaders/chunks/surface.ts`) this batch uses. */
+    protected surfaceDefines(): string[];
+    /** Adds the uniforms and samplers of the texture effects this batch uses. */
+    protected surfaceUniforms(uniforms: string[], samplers: string[]): void;
+    /** Sets the texture effects' textures and constants, and advances their scrolling on every bind. */
+    protected bindSurface(material: ShaderMaterial): void;
     addSystem(system: IParticleSystem): void;
     removeSystem(system: IParticleSystem): void;
     /**
@@ -3488,6 +3604,22 @@ interface VFXBatchSettings {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles; unset draws none. See {@link MeshRim}. */
     rim?: MeshRim;
+    /**
+     * Scrolls the map's UV by this many UV units per second, `[u, v]`, on the
+     * renderer's clock. The texture should wrap; scrolling one tile of a sheet
+     * runs into its neighbours. Unset or zero: no scroll. Systems that differ
+     * are batched apart.
+     */
+    uvScroll?: [number, number];
+    /**
+     * Colour ramp the map is recoloured through: the map's red channel picks
+     * a colour along U of this texture, and its alpha multiplies the map's. The
+     * particle colour still tints the result. Unset: none. Systems that differ
+     * are batched apart.
+     */
+    gradientMap?: BaseTexture | null;
+    /** Alpha erosion (dissolve / wipe), see {@link ParticleErosion}. Unset: none. Systems that differ are batched apart. */
+    erosion?: ParticleErosion;
 }
 interface AdaptivePerformanceOptions {
     targetFrameMs: number;
@@ -3503,6 +3635,8 @@ interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
 }
 declare class BatchedRenderer extends TransformNode {
     batches: Array<VFXBatch>;
+    /** Seconds this renderer has been updated for; the clock UV and erosion scrolling run on. */
+    private elapsed;
     systemToBatchIndex: Map<IParticleSystem, number>;
     depthTexture: BaseTexture | null;
     /** Systems in insertion order — iterated every frame, unlike the map. */
@@ -3778,6 +3912,35 @@ interface BurstParameters {
  * culled either; its parent decides.
  */
 type CullingMode = 'always' | 'pause' | 'pauseAndCatchUp';
+/**
+ * What the emitter's world scale does to a world-space system (Unity's
+ * Scaling Mode, as far as it differs here). A local-space system lives in its
+ * emitter's space, so its scale reaches everything either way.
+ *
+ * - `'shape'` (default): the scale sizes the emission shape and the
+ *   particles; speeds, forces and speed limits stay in world units, so a
+ *   scaled-down effect moves as far as the full-size one.
+ * - `'hierarchy'`: the scale also multiplies start speeds (per axis),
+ *   `ForceOverLife` and `LimitSpeedOverLife` (by the mean of the axes), so the
+ *   whole effect, motion included, scales like a model would.
+ */
+type ScalingMode = 'shape' | 'hierarchy';
+/**
+ * Where a {@link RenderMode.Beam} system's quads end: a point in world space,
+ * or anything with a world position, such as a Babylon `TransformNode`, read
+ * every frame.
+ */
+type BeamEnd = {
+    x: number;
+    y: number;
+    z: number;
+} | {
+    getAbsolutePosition(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
 interface ParticleSystemParameters {
     autoDestroy?: boolean;
     looping?: boolean;
@@ -3830,10 +3993,18 @@ interface ParticleSystemParameters {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles, see {@link ParticleSystem.rim}. Default none. */
     rim?: Partial<MeshRim>;
+    /** Map UV scroll in UV units per second, see {@link ParticleSystem.uvScroll}. Default none. */
+    uvScroll?: [number, number];
+    /** Colour ramp for the map, see {@link ParticleSystem.gradientMap}. Default none. */
+    gradientMap?: BaseTexture | null;
+    /** Alpha erosion, see {@link ParticleSystem.erosion}. Default none. */
+    erosion?: Partial<ParticleErosion>;
     /** Multiplier on the time the system is advanced by, see {@link ParticleSystem.playbackSpeed}. Default 1. */
     playbackSpeed?: number;
     /** What the system does while off screen, see {@link CullingMode}. Default `'always'`. */
     cullingMode?: CullingMode;
+    /** What the emitter's scale does to a world-space system, see {@link ScalingMode}. Default `'shape'`. */
+    scalingMode?: ScalingMode;
     /** Seed for this system's own random generator, see {@link ParticleSystem.seed}. Default none. */
     seed?: number;
     /** Draw order within the batch, see {@link ParticleSystem.sortMode}. Default `'none'`. */
@@ -3887,6 +4058,8 @@ interface ParticleSystemJSONParameters {
     playbackSpeed?: number;
     /** Written only when not `'always'`. */
     cullingMode?: CullingMode;
+    /** Written only when not `'shape'`. */
+    scalingMode?: ScalingMode;
     /** Written only when set. */
     seed?: number;
     /** Written only when not `'none'`. */
@@ -4090,6 +4263,43 @@ declare class ParticleSystem implements IParticleSystem {
      */
     get rim(): MeshRim | undefined;
     set rim(rim: Partial<MeshRim> | undefined);
+    /**
+     * Scrolls the map's UV by `[u, v]` UV units per second on the renderer's
+     * clock: flowing energy, lava, a smear running along a mesh. The texture
+     * should wrap. Undefined (the default) or zero does not scroll. Assign a
+     * new array to change it. Saved with the material in the effect JSON.
+     */
+    get uvScroll(): [number, number] | undefined;
+    set uvScroll(scroll: [number, number] | undefined);
+    /**
+     * Colour ramp the map is recoloured through (a gradient map): the map's
+     * red channel picks a colour along U of this texture, whose alpha
+     * multiplies the map's; the particle colour still tints the result. One
+     * greyscale texture then serves every palette. Null (the default): none.
+     * Saved with the material in the effect JSON.
+     */
+    get gradientMap(): BaseTexture | null;
+    set gradientMap(texture: BaseTexture | null);
+    /**
+     * Alpha erosion, see {@link ParticleErosion}: the particle's alpha decides
+     * how much of the shape is left rather than how transparent it is, so a
+     * `ColorOverLife` alpha curve dissolves the shape through a noise mask or
+     * wipes it through a gradient one — and an effect told to stop can fade
+     * out that way. Undefined (the default): alpha is plain transparency.
+     * Fields left out take their defaults; assign a new object to change it.
+     * Saved with the material in the effect JSON.
+     */
+    get erosion(): ParticleErosion | undefined;
+    set erosion(erosion: Partial<ParticleErosion> | undefined);
+    /**
+     * The emitter's world scale per axis, measured with {@link motionScale}
+     * before every step; what `'hierarchy'` multiplies start speeds by. Taken
+     * from the system's own emitter rather than the emission matrix, whose
+     * columns carry a parent particle's velocity for a sub emitter.
+     */
+    private readonly hierarchyScale;
+    /** The mean world scale of the emitter for a world-space `'hierarchy'` system, else 1. */
+    private measureMotionScale;
     /** `lighting` if it is one of the modes, else the default. */
     private static validLighting;
     private static validSortMode;
@@ -4128,8 +4338,24 @@ declare class ParticleSystem implements IParticleSystem {
      * renderer. 1 by default; saved in the effect JSON only when it differs.
      */
     playbackSpeed: number;
+    /**
+     * Runtime multiplier on how many particles the system emits: bursts,
+     * emission over time and over distance alike. Unlike
+     * {@link setQualityFactor}, which only ever thins an effect, it may go
+     * above 1 to make a stronger version of the same effect. The two multiply.
+     * 1 by default; not saved in the effect JSON.
+     */
+    emissionMultiplier: number;
     /** What this system does while off screen, see {@link CullingMode}. `'always'` by default. */
     cullingMode: CullingMode;
+    /** What the emitter's world scale does to a world-space system, see {@link ScalingMode}. `'shape'` by default. */
+    scalingMode: ScalingMode;
+    /**
+     * What world-space forces and speed limits are multiplied by this step:
+     * the mean of the emitter's world scale axes in `'hierarchy'` mode, 1
+     * otherwise. Updated before every simulation step.
+     */
+    motionScale: number;
     /**
      * Whether each particle starts turned along the direction its shape sends
      * it (Unity's Align To Direction): a mesh particle's +Z is pointed along
@@ -4195,6 +4421,8 @@ declare class ParticleSystem implements IParticleSystem {
     play(): void;
     stop(): void;
     setQualityFactor(qualityFactor: number): void;
+    /** Quality factor times {@link emissionMultiplier}: what emission counts are scaled by. */
+    private emissionFactor;
     /**
      * Appends one particle to the pool, giving it the next row of the store.
      *
@@ -4245,6 +4473,18 @@ declare class ParticleSystem implements IParticleSystem {
      * frame behind the display.
      */
     getWorldBounds(min: Vector3, max: Vector3): boolean;
+    /**
+     * Where a {@link RenderMode.Beam} system's quads end, see {@link BeamEnd}.
+     * Unset (the default), a beam has no length and draws nothing. Not saved
+     * in the effect JSON: it is where this instance is aimed at runtime.
+     */
+    beamEnd?: BeamEnd;
+    private readonly beamEndScratch;
+    /** The world position of {@link beamEnd} into `out`; false when it is unset. */
+    getBeamEnd(out: Vector3): boolean;
+    /** The largest axis of the emitter's world scale. */
+    private emitterMaxScale;
+    private measureWorldBounds;
     /**
      * Records bounds a renderer measured in world space, for systems whose
      * drawn extent the store does not hold (trail ribbons).
@@ -4587,6 +4827,22 @@ declare class QuarksUtil {
      * Nodes that are neither transform nodes nor emitters are skipped.
      */
     static instantiate(root: TransformNode, name?: string): TransformNode;
+    /**
+     * 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;
+    /** The largest value `generator` gives: exact for constants and intervals, sampled otherwise. */
+    private static maxOf;
     private static traverseNode;
 }
 
@@ -4688,7 +4944,17 @@ declare class SpriteBatch extends VFXBatch {
      * optimised code on every frame.
      */
     private syncStretchedSpeedFactor;
-    /** 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;
+    private readonly beamEnd_;
+    /**
+     * 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;
+    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes or beams. */
     private static takesPivotAndFlip;
     /**
      * Negates the size of each flipped particle along the axes it flips on,
@@ -4816,5 +5082,5 @@ declare class TrailBatch extends VFXBatch {
     dispose(): void;
 }
 
-export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedParticleRenderer, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EdgeEmitter, EffectPool, EmitSubParticleSystem, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, GeneratorFromJSON, Gradient, GravityForce, GridEmitter, HemisphereEmitter, InheritVelocity, IntervalValue, LimitSpeedOverLife, MathUtils, Matrix3, Matrix4, MeshSurfaceEmitter, MeshSurfaceEmitterPlugin, NodeParticle, Noise, OrbitOverLife, ParticleEmitter, ParticleMeshPhysicsMaterial, ParticleMeshStandardMaterial, ParticleStore, ParticleSystem, PiecewiseBezier, PiecewiseFunction, Plugins, PointEmitter, QuarksLoader, QuarksPrefab, QuarksUtil, Quaternion, QuaternionView, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteBatch, SpriteParticle, SubEmitterInheritMask, SubParticleEmitMode, TextureSequencer, TrailBatch, TrailParticle, TurbulenceField, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, createSeededRandom, cubeFaceUrls, damp, defaultMeshLighting, degToRad, denormalize, ensureEnvAtlasFromCube, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, meshRimEqual, normalize, normalizeMeshRim, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, random, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, setRandomSource, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, subEmitterInheritMask, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin, withRandomSource };
-export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, CullingMode, DonutEmitterParameters, EdgeEmitterParameters, EffectPoolOptions, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SortMode, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, SubEmitterInheritance, TrailSettings, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };
+export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedParticleRenderer, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EdgeEmitter, EffectPool, EmitSubParticleSystem, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, GeneratorFromJSON, Gradient, GravityForce, GridEmitter, HemisphereEmitter, InheritVelocity, IntervalValue, LimitSpeedOverLife, MathUtils, Matrix3, Matrix4, MeshSurfaceEmitter, MeshSurfaceEmitterPlugin, NodeParticle, Noise, OrbitOverLife, ParticleEmitter, ParticleMeshPhysicsMaterial, ParticleMeshStandardMaterial, ParticleStore, ParticleSystem, PiecewiseBezier, PiecewiseFunction, Plugins, PointEmitter, QuarksLoader, QuarksPrefab, QuarksUtil, Quaternion, QuaternionView, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteBatch, SpriteParticle, SubEmitterInheritMask, SubParticleEmitMode, TextureSequencer, TrailBatch, TrailParticle, TurbulenceField, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, createSeededRandom, cubeFaceUrls, damp, defaultMeshLighting, degToRad, denormalize, ensureEnvAtlasFromCube, erosionEqual, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRandomSource, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, meshRimEqual, normalize, normalizeErosion, normalizeMeshRim, normalizeUVScroll, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, random, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, setRandomSource, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, subEmitterInheritMask, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin, uvScrollEqual, withRandomSource };
+export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, BeamEnd, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, CullingMode, DonutEmitterParameters, EdgeEmitterParameters, EffectPoolOptions, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FrameOverLifeOptions, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshLighting, MeshLightingSettings, MeshRim, MeshSettings, ParameterPair, ParameterType, Particle, ParticleErosion, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RandomSource, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, ScalingMode, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SortMode, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, SubEmitterInheritance, TrailSettings, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.24.0",
+    "version": "0.25.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",

package/src/BatchedRenderer.ts

@@ -11,13 +11,16 @@ import {SpriteBatch} from './SpriteBatch';
 import {TrailBatch} from './TrailBatch';
 import {
     defaultMeshLighting,
+    erosionEqual,
     MeshLighting,
     MeshLightingSettings,
     MeshRim,
     meshRimEqual,
+    ParticleErosion,
     RenderMode,
     SortMode,
     StoredBatchSettings,
+    uvScrollEqual,
     VFXBatch,
 } from './VFXBatch';
 
@@ -100,6 +103,22 @@ export interface VFXBatchSettings {
     lighting?: MeshLighting;
     /** Rim (Fresnel) term on mesh particles; unset draws none. See {@link MeshRim}. */
     rim?: MeshRim;
+    /**
+     * Scrolls the map's UV by this many UV units per second, `[u, v]`, on the
+     * renderer's clock. The texture should wrap; scrolling one tile of a sheet
+     * runs into its neighbours. Unset or zero: no scroll. Systems that differ
+     * are batched apart.
+     */
+    uvScroll?: [number, number];
+    /**
+     * Colour ramp the map is recoloured through: the map's red channel picks
+     * a colour along U of this texture, and its alpha multiplies the map's. The
+     * particle colour still tints the result. Unset: none. Systems that differ
+     * are batched apart.
+     */
+    gradientMap?: BaseTexture | null;
+    /** Alpha erosion (dissolve / wipe), see {@link ParticleErosion}. Unset: none. Systems that differ are batched apart. */
+    erosion?: ParticleErosion;
 }
 
 export interface AdaptivePerformanceOptions {
@@ -139,6 +158,8 @@ export interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
 
 export class BatchedRenderer extends TransformNode {
     batches: Array<VFXBatch> = [];
+    /** Seconds this renderer has been updated for; the clock UV and erosion scrolling run on. */
+    private elapsed = 0;
     systemToBatchIndex: Map<IParticleSystem, number> = new Map<IParticleSystem, number>();
     depthTexture: BaseTexture | null = null;
     /** Systems in insertion order — iterated every frame, unlike the map. */
@@ -311,7 +332,10 @@ export class BatchedRenderer extends TransformNode {
             a.minParticleSize === (b.minParticleSize ?? 0) &&
             a.maxParticleSize === (b.maxParticleSize ?? Infinity) &&
             (a.lighting ?? 'fixed') === (b.lighting ?? 'fixed') &&
-            meshRimEqual(a.rim, b.rim)
+            meshRimEqual(a.rim, b.rim) &&
+            uvScrollEqual(a.uvScroll, b.uvScroll) &&
+            a.gradientMap === (b.gradientMap ?? null) &&
+            erosionEqual(a.erosion, b.erosion)
         );
     }
 
@@ -350,6 +374,7 @@ export class BatchedRenderer extends TransformNode {
             case RenderMode.VerticalBillBoard:
             case RenderMode.HorizontalBillBoard:
             case RenderMode.StretchedBillBoard:
+            case RenderMode.Beam:
                 batch = new SpriteBatch(settings, scene);
                 break;
             default:
@@ -543,6 +568,7 @@ export class BatchedRenderer extends TransformNode {
     }
 
     update(delta: number) {
+        this.elapsed += delta;
         const adaptiveState = this.adaptivePerformanceState;
         const frameStart = adaptiveState.enabled ? performance.now() : 0;
         if (adaptiveState.enabled) {
@@ -602,6 +628,7 @@ export class BatchedRenderer extends TransformNode {
         const emptyFrames = this.batchEmptyFrames;
         for (let i = 0; i < this.batches.length; i++) {
             const batch = this.batches[i];
+            batch.time = this.elapsed;
             if (batch.systems.size > 0) {
                 emptyFrames[i] = 0;
                 batch.update();