babylon.quarks 0.26.0 → 0.28.0

package/src/system/types.ts

@@ -0,0 +1,449 @@
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {Texture} from '@babylonjs/core/Materials/Textures/texture';
+import type {Scene} from '@babylonjs/core/scene';
+import type {
+    Behavior,
+    BehaviorJSON,
+    ColorGenerator,
+    ColorGeneratorJSON,
+    EmitterShape,
+    FunctionColorGenerator,
+    FunctionValueGenerator,
+    RendererEmitterSettings,
+    RotationGenerator,
+    RotationGeneratorJSON,
+    ShapeJSON,
+    StretchedBillBoardSettings,
+    ValueGenerator,
+    ValueGeneratorJSON,
+    Vector2,
+    Vector3,
+    Vector3ArrayJSON,
+    Vector3Generator,
+    Vector3GeneratorJSON,
+    Vector3JSON,
+} from 'quarks.core';
+import type {
+    MeshLighting,
+    MeshRim,
+    ParticleErosionOptions,
+    ParticleGradientMap,
+    ParticleUVDistortionOptions,
+    RenderFace,
+    RenderMode,
+    SortMode,
+    TextureUV,
+} from '../VFXBatch';
+import type {GeometryEntry, QuarksMaterialJSON} from '../effectDocumentJSON';
+import type {TrailOptions} from '../trailSettings';
+import type {ParticleMaterialSource} from './materialResolve';
+
+/** A trail's settings in JSON, each only when not its default: the start length as a generator's JSON, the side axis as `[x, y, z]`. */
+export type TrailSettingsJSON = Partial<TrailOptions> & {
+    /** See `TrailSettings.startLength`. */
+    startLength?: ValueGeneratorJSON;
+    /** See `TrailSettings.sideAxis`; files may hold it as `{x, y, z}`. */
+    sideAxis?: Vector3ArrayJSON | Vector3JSON;
+};
+
+/**
+ * A render mode's own settings in JSON, see {@link RendererEmitterSettings}: a trail's or a
+ * stretched billboard's. The other render modes have none, and their systems leave the field out.
+ */
+export type RendererEmitterSettingsJSON = TrailSettingsJSON | StretchedBillBoardSettings;
+
+/**
+ * One burst of a system's emission (Unity's Emission Bursts): `count` particles at `time` seconds
+ * into each loop, repeated `cycle` times `interval` seconds apart, each wave with the chance
+ * `probability`. A burst given to the constructor or read from a file is normalised (a missing
+ * `interval` is 0.1 s, `probability` is kept to 0..1, `cycle` to at least 1) and the bursts are
+ * kept in time order.
+ */
+export interface BurstParameters {
+    /** Seconds into the system's duration the first wave fires at. */
+    time: number;
+    /**
+     * Particles each wave spawns. The generator is rolled when the system plays or restarts, so
+     * a random count is the same for every loop of one play; a curve is read at the wave's time
+     * as a fraction of the duration, 0 to 1, like the start curves.
+     */
+    count: ValueGenerator | FunctionValueGenerator;
+    /** How many waves the burst fires, at least 1. */
+    cycle: number;
+    /** Seconds between waves; 0 fires them all at once. 0.1 when left out. */
+    interval: number;
+    /** Chance from 0 to 1 that a wave spawns at all, rolled per wave. */
+    probability: number;
+}
+
+/**
+ * What a system does while no camera can see its particles (Unity's Culling
+ * Mode). The {@link BatchedRenderer} tests each system's bounds against the
+ * active cameras' frusta every frame.
+ *
+ * - `'always'` keeps simulating off screen, so an effect is exactly where it
+ *   would have been when it comes back into view. The default, and the only
+ *   safe choice for an emitter whose particles reach the screen from off it.
+ * - `'pause'` freezes the system off screen and resumes it where it left off.
+ * - `'pauseAndCatchUp'` freezes it too, then runs the missed time (up to a few
+ *   seconds) within the renderer's catch-up budget when it is seen again.
+ *
+ * An empty system is never culled, so it can start emitting and grow the
+ * bounds that decide its visibility. A system another one emits into is never
+ * culled either; its parent decides.
+ *
+ * The cameras tested are the scene's active cameras (`scene.activeCameras`, or
+ * `scene.activeCamera`), each only for the systems on a layer it renders
+ * (`camera.layerMask & system.layers.mask`). A camera that renders into a
+ * render target texture (a mirror, a minimap, a portal) is not one of them: a
+ * system seen only through one should keep `'always'`.
+ */
+export 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.
+ */
+export 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.
+ */
+export type BeamEnd =
+    | {
+          /** World x. */
+          x: number;
+          /** World y. */
+          y: number;
+          /** World z. */
+          z: number;
+      }
+    | {
+          /** The world position, read every frame. */
+          getAbsolutePosition(): {
+              /** World x. */
+              x: number;
+              /** World y. */
+              y: number;
+              /** World z. */
+              z: number;
+          };
+      };
+
+/**
+ * Settings for a new {@link ParticleSystem}. Every one is optional: a setting left out takes the
+ * default named on it, the same default `fromJSON` gives a file that leaves it out.
+ */
+export interface ParticleSystemParameters {
+    /** See {@link ParticleSystem.autoDestroy}. Default false. */
+    autoDestroy?: boolean;
+    /** See {@link ParticleSystem.looping}. Default true. */
+    looping?: boolean;
+    /** See {@link ParticleSystem.prewarm}. Default false. */
+    prewarm?: boolean;
+    /** See {@link ParticleSystem.prewarmTime}. Default 0: a whole cycle; only with `prewarm` on a looping system. */
+    prewarmTime?: number;
+    /** See {@link ParticleSystem.duration}. Default 1 second. */
+    duration?: number;
+    /** See {@link ParticleSystem.startDelay}. Default 0. */
+    startDelay?: ValueGenerator | FunctionValueGenerator;
+    /** Where particles are born and which way they start, see {@link ParticleSystem.emitterShape}. Default a `SphereEmitter`. */
+    shape?: EmitterShape;
+    /** See {@link ParticleSystem.startLife}. Default 5 seconds. */
+    startLife?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.startSpeed}. Default 0. */
+    startSpeed?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.startRotation}. Default 0. */
+    startRotation?: ValueGenerator | FunctionValueGenerator | RotationGenerator;
+    /** See {@link ParticleSystem.startSize}. Default 1. */
+    startSize?: ValueGenerator | FunctionValueGenerator | Vector3Generator;
+    /** See {@link ParticleSystem.startColor}. Default opaque white. */
+    startColor?: ColorGenerator | FunctionColorGenerator;
+    /** See {@link ParticleSystem.emissionOverTime}. Default 10 per second. */
+    emissionOverTime?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.emissionOverDistance}. Default 0. */
+    emissionOverDistance?: ValueGenerator | FunctionValueGenerator;
+    /** See {@link ParticleSystem.emissionBursts}. Default none. */
+    emissionBursts?: Array<BurstParameters>;
+    /** Most particles alive at once; emission past it is dropped. Leave unset for no limit. */
+    maxParticles?: number;
+    /** See {@link ParticleSystem.onlyUsedByOther}. Default false. */
+    onlyUsedByOther?: boolean;
+    /** See {@link ParticleSystem.behaviors}. Default none. */
+    behaviors?: Array<Behavior>;
+    /** Mesh particles' vertex positions, three values per vertex. Default a unit quad in XY. */
+    instancingGeometry?: Float32Array;
+    /** Triangle indices into {@link instancingGeometry}. Default the unit quad's two triangles. */
+    instancingIndices?: Uint32Array | Uint16Array;
+    /** Mesh particles' first UV set, two values per vertex. Default the quad's UVs, or zeros for another geometry. */
+    instancingUVs?: Float32Array;
+    /**
+     * A second UV set for the mesh (glTF `TEXCOORD_1`, Unity's `uv2`), what
+     * textures on UV channel 1 read on a mesh particle; see `UVChannel`.
+     * Default none: channel 1 reads the first set.
+     */
+    instancingUVs2?: Float32Array;
+    /** Mesh particles' vertex normals, three values per vertex. Default +Z for every vertex. */
+    instancingNormals?: Float32Array;
+    /** See {@link ParticleSystem.renderMode}. Default `RenderMode.BillBoard`. */
+    renderMode?: RenderMode;
+    /** See {@link ParticleSystem.rendererEmitterSettings}. Default the render mode's own. */
+    rendererEmitterSettings?: RendererEmitterSettings;
+    /** @deprecated Set `speedFactor` in {@link rendererEmitterSettings} instead; this one wins when both are set. */
+    speedFactor?: number;
+    /** See {@link ParticleSystem.material}. Default none. */
+    material?: ParticleMaterialSource | null;
+    /** See {@link ParticleSystem.texture}. Unset takes the material's texture; null draws without one. */
+    texture?: Texture | null;
+    /** See {@link ParticleSystem.startTileIndex}. Default 0. */
+    startTileIndex?: ValueGenerator;
+    /** See {@link ParticleSystem.uTileCount}. Default 1. */
+    uTileCount?: number;
+    /** See {@link ParticleSystem.vTileCount}. Default 1. */
+    vTileCount?: number;
+    /** See {@link ParticleSystem.blendTiles}. Default false. */
+    blendTiles?: boolean;
+    /**
+     * Fade particles out as they near the scene behind them, like Unity's Soft Particles and
+     * Unreal's Depth Fade, between `softNearFade` and `softFarFade` world units. Needs a depth
+     * texture, see `BatchedRenderer.setDepthTexture`; without one particles draw hard. Applies to
+     * every render mode: billboard, stretched, mesh, beam and trail.
+     */
+    softParticles?: boolean;
+    /** See {@link ParticleSystem.softFarFade}. Default 1. */
+    softFarFade?: number;
+    /** See {@link ParticleSystem.softNearFade}. Default 0. */
+    softNearFade?: number;
+    /** See {@link ParticleSystem.renderOrder}. Default 0. */
+    renderOrder?: number;
+    /** See {@link ParticleSystem.worldSpace}. Default false. */
+    worldSpace?: boolean;
+    /** Babylon alpha mode the batch blends with, see {@link ParticleSystem.blending}. Default `Constants.ALPHA_ADD`. */
+    blendMode?: number;
+    /** Whether the batch draws in the transparent pass. Default true. */
+    transparent?: boolean;
+    /**
+     * Whether particles are hidden behind nearer geometry. `false` draws them over everything
+     * (Unity's `ZTest Always`), in every render mode. Default `true`.
+     */
+    depthTest?: boolean;
+    /** Whether the particles write depth. Default false. */
+    depthWrite?: boolean;
+    /** Alpha below which a fragment is discarded, 0 to 1. Default 0: nothing is. */
+    alphaTest?: number;
+    /** Camera layer mask the batch draws for, see {@link ParticleSystem.layers}. Default `0x0fffffff`. */
+    layerMask?: number;
+    /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
+    pivot?: Vector3;
+    /** Fraction of billboard particles mirrored along U (x) and V (y), see {@link ParticleSystem.flip}. */
+    flip?: Vector2;
+    /** How mesh particles are lit, see {@link ParticleSystem.lighting}. Default `'fixed'`. */
+    lighting?: MeshLighting;
+    /** Rim (Fresnel) term on mesh particles, see {@link ParticleSystem.rim}. Default none. */
+    rim?: Partial<MeshRim>;
+    /** The main map's layout, see {@link ParticleSystem.mapUV}. Default as drawn. */
+    mapUV?: Partial<TextureUV>;
+    /** Colour ramp for the map, see {@link ParticleSystem.gradientMap}. Default none. */
+    gradientMap?: Partial<ParticleGradientMap>;
+    /** Alpha erosion, see {@link ParticleSystem.erosion}. Default none. */
+    erosion?: ParticleErosionOptions;
+    /** Map UV distortion, see {@link ParticleSystem.uvDistortion}. Default none. */
+    uvDistortion?: ParticleUVDistortionOptions;
+    /** 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'`. */
+    sortMode?: SortMode;
+    /** Which faces a mesh particle draws, see {@link ParticleSystem.renderFace}. Default `'both'`. */
+    renderFace?: RenderFace;
+    /** Whether particles start turned along their direction of travel, see {@link ParticleSystem.alignToDirection}. Default false. */
+    alignToDirection?: boolean;
+    /** Smallest on-screen size, as a fraction of the viewport height, see {@link ParticleSystem.minParticleSize}. Default 0. */
+    minParticleSize?: number;
+    /** Largest on-screen size, as a fraction of the viewport height, see {@link ParticleSystem.maxParticleSize}. Default unlimited. */
+    maxParticleSize?: number;
+    /** Babylon rendering group of the batch, see {@link ParticleSystem.renderingGroupId}. Default 0. */
+    renderingGroupId?: number;
+    /** Whether the scene's fog applies, see {@link ParticleSystem.applyFog}. Default true. */
+    applyFog?: boolean;
+    /** Scene the emitter node is created in. Default Babylon's last created scene. */
+    scene?: Scene;
+}
+
+/** A {@link BurstParameters} in an effect file. A plain number `count` is read as a constant. */
+export interface BurstParametersJSON {
+    /** See {@link BurstParameters.time}. */
+    time: number;
+    /** See {@link BurstParameters.count}. */
+    count: ValueGeneratorJSON | number;
+    /** See {@link BurstParameters.cycle}. */
+    cycle: number;
+    /** See {@link BurstParameters.interval}. */
+    interval: number;
+    /** See {@link BurstParameters.probability}. */
+    probability: number;
+    /** `cycle`, as files before it was named wrote it; read when there is no `cycle`. */
+    cycleCount?: number;
+}
+
+/**
+ * A particle system in an effect file, as {@link ParticleSystem.toJSON} writes it and
+ * {@link ParticleSystem.fromJSON} reads it; `docs/FORMAT.md` describes the document around it.
+ * Each field mirrors the {@link ParticleSystem} member of the same name. Curves and generators
+ * are written as quarks.core's `FunctionJSON`; textures, materials and geometries as uuids into
+ * the document. Most settings are written only when they differ from their default, and a field
+ * that is missing reads as the default, so every field but `version` is optional. The shape, the
+ * start and emission curves except `startDelay`, `startTileIndex`, `instancingGeometry`, `material`
+ * and `behaviors` are always written, because older loaders and three.quarks need them.
+ */
+export interface ParticleSystemJSONParameters {
+    /** The quarks.core version line the system was written with. */
+    version: string;
+    /** See {@link ParticleSystem.autoDestroy}. */
+    autoDestroy?: boolean;
+    /** See {@link ParticleSystem.looping}. */
+    looping?: boolean;
+    /** See {@link ParticleSystem.prewarm}. */
+    prewarm?: boolean;
+    /** See {@link ParticleSystem.prewarmTime}. */
+    prewarmTime?: number;
+    /** See {@link ParticleSystem.duration}. */
+    duration?: number;
+    /** See {@link ParticleSystem.startDelay}. */
+    startDelay?: ValueGeneratorJSON;
+    /** The emitter shape, as its `toJSON` writes it. */
+    shape?: ShapeJSON;
+    /** See {@link ParticleSystem.startLife}. */
+    startLife?: ValueGeneratorJSON;
+    /** See {@link ParticleSystem.startSpeed}. */
+    startSpeed?: ValueGeneratorJSON;
+    /** See {@link ParticleSystem.startRotation}. */
+    startRotation?: ValueGeneratorJSON | RotationGeneratorJSON;
+    /** See {@link ParticleSystem.startSize}. */
+    startSize?: ValueGeneratorJSON | Vector3GeneratorJSON;
+    /** See {@link ParticleSystem.startColor}. */
+    startColor?: ColorGeneratorJSON;
+    /** See {@link ParticleSystem.emissionOverTime}. */
+    emissionOverTime?: ValueGeneratorJSON;
+    /** See {@link ParticleSystem.emissionOverDistance}. */
+    emissionOverDistance?: ValueGeneratorJSON;
+    /** See {@link ParticleSystem.emissionBursts}. */
+    emissionBursts?: Array<BurstParametersJSON>;
+    /** See {@link ParticleSystem.maxParticles}. */
+    maxParticles?: number;
+    /** See {@link ParticleSystem.onlyUsedByOther}. */
+    onlyUsedByOther?: boolean;
+    /**
+     * Trail, stretched or mesh settings; a trail's `startLength` as `ValueGeneratorJSON`. Left out when
+     * the render mode has none.
+     */
+    rendererEmitterSettings?: RendererEmitterSettingsJSON;
+    /** Uuid of the mesh particles' geometry entry; a document made in code may hold the entry itself. */
+    instancingGeometry?: string | GeometryEntry;
+    /** A {@link RenderMode} value. */
+    renderMode?: number;
+    /** See {@link ParticleSystem.renderOrder}. */
+    renderOrder?: number;
+    /** Written only when not 0. */
+    renderingGroupId?: number;
+    /** Written only when false. */
+    applyFog?: boolean;
+    /** Written only when not 1. */
+    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'`. */
+    sortMode?: SortMode;
+    /** Written only when not `'both'`. */
+    renderFace?: RenderFace;
+    /** Written only when true. */
+    alignToDirection?: boolean;
+    /** Written only when not 0. */
+    minParticleSize?: number;
+    /** Written only when limited. */
+    maxParticleSize?: number;
+    /** A stretched billboard's speed factor, as older files wrote it outside `rendererEmitterSettings`. */
+    speedFactor?: number;
+    /** Uuid of the texture entry. */
+    texture?: string;
+    /** Uuid of the material entry. */
+    material?: string;
+    /** The camera layer mask. */
+    layers?: number;
+    /** See {@link ParticleSystem.startTileIndex}. */
+    startTileIndex?: ValueGeneratorJSON | number;
+    /** See {@link ParticleSystem.uTileCount}. */
+    uTileCount?: number;
+    /** See {@link ParticleSystem.vTileCount}. */
+    vTileCount?: number;
+    /** See {@link ParticleSystem.blendTiles}. */
+    blendTiles?: boolean;
+    /** See {@link ParticleSystem.softParticles}. */
+    softParticles?: boolean;
+    /** See {@link ParticleSystem.softFarFade}. */
+    softFarFade?: number;
+    /** See {@link ParticleSystem.softNearFade}. */
+    softNearFade?: number;
+    /** See {@link ParticleSystem.blending}. */
+    blending?: number;
+    /** See {@link ParticleSystemParameters.transparent}. */
+    transparent?: boolean;
+    /** See {@link ParticleSystemParameters.depthTest}. */
+    depthTest?: boolean;
+    /** See {@link ParticleSystemParameters.depthWrite}. */
+    depthWrite?: boolean;
+    /** See {@link ParticleSystemParameters.alphaTest}. */
+    alphaTest?: number;
+    /** Each behavior as its `toJSON` writes it. */
+    behaviors?: BehaviorJSON[];
+    /** See {@link ParticleSystem.worldSpace}. */
+    worldSpace?: boolean;
+    /** `[x, y, z]`; written only when non-zero. */
+    pivot?: number[];
+    /** `[u, v]`; written only when non-zero. */
+    flip?: number[];
+}
+
+/**
+ * The resources of one effect document, by uuid: what {@link ParticleSystem.toJSON} writes a
+ * system's geometry, material and texture into, and what {@link ParticleSystem.fromJSON} resolves
+ * them from. While writing, entries hold live Babylon objects; `serializeEffect` turns them into
+ * plain data.
+ */
+export interface BabylonMetaData {
+    /** Textures by uuid; null for one that could not be made. */
+    textures: {[uuid: string]: BaseTexture | null};
+    /** Material entries by uuid. */
+    materials: {[uuid: string]: QuarksMaterialJSON};
+    /** Geometry entries by uuid. */
+    geometries: {[uuid: string]: GeometryEntry};
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
+    images?: {[uuid: string]: unknown};
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
+    shapes?: {[uuid: string]: unknown};
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
+    skeletons?: {[uuid: string]: unknown};
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
+    animations?: {[uuid: string]: unknown};
+    /** Not used by babylon.quarks; kept for three.js-shaped documents. */
+    nodes?: {[uuid: string]: unknown};
+}

package/src/textureSource.ts

@@ -0,0 +1,30 @@
+import type {Texture} from '@babylonjs/core/Materials/Textures/texture';
+
+/** Per loaded texture: the url its effect file wrote, and the url the loader gave the texture. */
+const sources = new WeakMap<Texture, {source: string; loaded: string}>();
+
+/**
+ * Remembers the url a texture's image had in the effect file (`tex/a.png`) and the url the texture
+ * was made with (`fx/tex/a.png`). Called by the loader when it makes a texture.
+ */
+export function setTextureSourceUrl(texture: Texture, source: string, loaded: string): void {
+    sources.set(texture, {source, loaded});
+}
+
+/**
+ * The url a texture's image had in the effect file it was loaded from, relative to that file.
+ * `serializeEffect` writes it by default, so a file saved next to the one it was loaded from loads
+ * the same images.
+ *
+ * `undefined` when there is no such url: a texture made in code or loaded another way; a texture
+ * whose image the loader's resolver inlined (`data:` or `blob:`), which holds the image itself; and
+ * a texture whose `url` was changed since it was loaded (`updateURL`, or a `data:` URI assigned
+ * before saving), since the file's path no longer names what it shows.
+ *
+ * A texture shared between effects (see `QuarksLoaderOptions.shareResources`) keeps the url of the
+ * first effect that loaded it; effects in different folders that join to the same image share it.
+ */
+export function textureSourceUrl(texture: Texture): string | undefined {
+    const entry = sources.get(texture);
+    return entry !== undefined && texture.url === entry.loaded ? entry.source : undefined;
+}

package/src/trailSettings.ts

@@ -0,0 +1,54 @@
+import type {TrailSettings, TrailTextureMode} from 'quarks.core';
+
+/** A trail's settings other than its start length and side axis, alike in code and in JSON. */
+export type TrailOptions = Omit<TrailSettings, 'startLength' | 'sideAxis'>;
+
+/**
+ * The normalised values of a trail's optional settings (`TrailSettings`), each read with its
+ * default for a value that is unset or out of range, so the batch, the simulation, JSON and
+ * clones agree on what a setting means.
+ */
+
+/** Most segments one recorded segment of a trail is drawn as, see `TrailSettings.tessellation`. */
+export const MAX_TRAIL_TESSELLATION = 16;
+
+/** A trail's tessellation, a whole number from 0 (the default: none) to {@link MAX_TRAIL_TESSELLATION}. */
+export function trailTessellation(settings: Partial<TrailOptions> | undefined): number {
+    const value = Math.round(Number(settings?.tessellation) || 0);
+    return Math.min(MAX_TRAIL_TESSELLATION, Math.max(0, value));
+}
+
+/** A trail's curve tension, from 0 (the default: Catmull-Rom) to 1 (straight segments). */
+export function trailCurveTension(settings: Partial<TrailOptions> | undefined): number {
+    const value = Number(settings?.curveTension) || 0;
+    return Math.min(1, Math.max(0, value));
+}
+
+const TEXTURE_MODES: readonly TrailTextureMode[] = ['stretch', 'tile', 'distributePerSegment', 'repeatPerSegment'];
+
+/** A trail's texture mode, `'stretch'` (the default) unless set to one of the others. */
+export function trailTextureMode(settings: Partial<TrailOptions> | undefined): TrailTextureMode {
+    const mode = settings?.textureMode;
+    return mode !== undefined && TEXTURE_MODES.includes(mode) ? mode : 'stretch';
+}
+
+/** A trail's texture scale: a finite number above 0, else the default 1. */
+export function trailTextureScale(settings: Partial<TrailOptions> | undefined): number {
+    const value = Number(settings?.textureScale);
+    return Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+/** A trail's minimum distance between samples: a finite number of at least 0, else the default 0. */
+export function trailMinVertexDistance(settings: Partial<TrailOptions> | undefined): number {
+    const value = Number(settings?.minVertexDistance);
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * How long a trail keeps a sample, in seconds: a finite number above 0, else `Infinity` (the
+ * default, as 0 is: until the history is full).
+ */
+export function trailLifetime(settings: Partial<TrailOptions> | undefined): number {
+    const value = Number(settings?.lifetime);
+    return Number.isFinite(value) && value > 0 ? value : Infinity;
+}

package/src/BatchedParticleRenderer.ts

@@ -1,3 +0,0 @@
-import {BatchedRenderer} from './BatchedRenderer';
-
-export const BatchedParticleRenderer = BatchedRenderer;

package/src/materials/ParticleMaterials.ts

@@ -1,23 +0,0 @@
-import {PBRMaterial} from '@babylonjs/core/Materials/PBR/pbrMaterial';
-import {StandardMaterial} from '@babylonjs/core/Materials/standardMaterial';
-import {Scene} from '@babylonjs/core/scene';
-
-export type BabylonParticleMaterialParameters = Record<string, any>;
-
-export class ParticleMeshStandardMaterial extends StandardMaterial {
-    readonly isParticleMeshStandardMaterial = true;
-
-    constructor(name: string, scene?: Scene, parameters: BabylonParticleMaterialParameters = {}) {
-        super(name, scene);
-        Object.assign(this, parameters);
-    }
-}
-
-export class ParticleMeshPhysicsMaterial extends PBRMaterial {
-    readonly isParticleMeshPhysicsMaterial = true;
-
-    constructor(name: string, scene?: Scene, parameters: BabylonParticleMaterialParameters = {}) {
-        super(name, scene);
-        Object.assign(this, parameters);
-    }
-}

package/src/materials/index.ts

@@ -1 +0,0 @@
-export * from './ParticleMaterials';

package/src/shaders/chunks/index.ts

@@ -1 +0,0 @@
-export * from './register-shader-chunks';

package/src/shaders/chunks/register-shader-chunks.ts

@@ -1,32 +0,0 @@
-import softFragment from './soft_fragment.glsl';
-import softParsFragment from './soft_pars_fragment.glsl';
-import softParsVertex from './soft_pars_vertex.glsl';
-import softVertex from './soft_vertex.glsl';
-import tileFragment from './tile_fragment.glsl';
-import tileParsFragment from './tile_pars_fragment.glsl';
-import tileParsVertex from './tile_pars_vertex.glsl';
-import tileVertex from './tile_vertex.glsl';
-
-const shaderChunks: Record<string, string> = {};
-let registered = false;
-
-export function registerShaderChunks(): void {
-    if (registered) return;
-    shaderChunks.tile_pars_vertex = tileParsVertex;
-    shaderChunks.tile_vertex = tileVertex;
-    shaderChunks.tile_pars_fragment = tileParsFragment;
-    shaderChunks.tile_fragment = tileFragment;
-    shaderChunks.soft_pars_vertex = softParsVertex;
-    shaderChunks.soft_vertex = softVertex;
-    shaderChunks.soft_pars_fragment = softParsFragment;
-    shaderChunks.soft_fragment = softFragment;
-    registered = true;
-}
-
-export function getShaderChunk(chunkName: string): string | undefined {
-    return shaderChunks[chunkName];
-}
-
-export function getRegisteredShaderChunks(): Readonly<Record<string, string>> {
-    return shaderChunks;
-}

package/src/shaders/chunks/soft_fragment.glsl.ts

@@ -1,13 +0,0 @@
-export default /* glsl */ `
-#ifdef SOFT_PARTICLES
-
-    vec2 p2 = projPosition.xy / projPosition.w;
-    p2 = 0.5 * p2 + 0.5;
-
-    float readDepth = texture2D(depthTexture, p2.xy).r;
-    float viewDepth = linearize_depth(readDepth);
-    float softParticlesFade = saturate(SOFT_INV_FADE_DISTANCE * ((viewDepth - SOFT_NEAR_FADE) - linearDepth));
-
-    gl_FragColor *= softParticlesFade;
-#endif
-`;

package/src/shaders/chunks/soft_pars_fragment.glsl.ts

@@ -1,20 +0,0 @@
-export default /* glsl */ `
-#ifdef SOFT_PARTICLES
-    uniform sampler2D depthTexture;
-    uniform vec4 projParams;
-    uniform vec2 softParams;
-
-    varying vec4 projPosition;
-    varying float linearDepth;
-
-    #define SOFT_NEAR_FADE softParams.x
-    #define SOFT_INV_FADE_DISTANCE softParams.y
-
-    #define zNear projParams.x
-    #define zFar projParams.y
-
-    float linearize_depth(float d) {
-        return (zFar * zNear) / (zFar - d * (zFar - zNear));
-    }
-#endif
-`;

package/src/shaders/chunks/soft_pars_vertex.glsl.ts

@@ -1,6 +0,0 @@
-export default /* glsl */ `
-#ifdef SOFT_PARTICLES
-    varying vec4 projPosition;
-    varying float linearDepth;
-#endif
-`;

package/src/shaders/chunks/soft_vertex.glsl.ts

@@ -1,6 +0,0 @@
-export default /* glsl */ `
-#ifdef SOFT_PARTICLES
-    projPosition = gl_Position;
-    linearDepth = -mvPosition.z;
-#endif
-`;

package/src/shaders/chunks/tile_fragment.glsl.ts

@@ -1,9 +0,0 @@
-export default /* glsl */ `
-#ifdef USE_MAP
-    vec4 texelColor = texture2D(map, vUv);
-    #ifdef TILE_BLEND
-        texelColor = mix(texelColor, texture2D(map, vUvNext), vUvBlend);
-    #endif
-    diffuseColor *= texelColor;
-#endif
-`;