babylon.quarks 0.27.0 → 0.29.0

package/src/system/settingsSchema.ts

@@ -1,4 +1,5 @@
 import {Constants} from '@babylonjs/core/Engines/constants';
+import type {ColorGeneratorJSON, RotationGeneratorJSON, ValueGeneratorJSON, Vector3GeneratorJSON} from 'quarks.core';
 import {
     ColorGenerator,
     ColorGeneratorFromJSON,
@@ -7,6 +8,7 @@ import {
     FunctionColorGenerator,
     FunctionValueGenerator,
     GeneratorFromJSON,
+    readFormatPart,
     RotationGenerator,
     ValueGenerator,
     ValueGeneratorFromJSON,
@@ -17,8 +19,24 @@ import {
 } from 'quarks.core';
 import type {ParticleSystem} from '../ParticleSystem';
 import {RenderMode} from '../VFXBatch';
-import {DEFAULT_SOFT_FAR_FADE, normalizeBursts, validCullingMode, validSortMode, validTileCount} from './normalize';
-import type {BurstParameters, ParticleSystemJSONParameters, ParticleSystemParameters} from './types';
+import {
+    DEFAULT_SOFT_FAR_FADE,
+    normalizeBursts,
+    validCullingMode,
+    validLoopRange,
+    validRenderFace,
+    validRingBufferMode,
+    validScalingMode,
+    validSortMode,
+    validStopAction,
+    validTileCount,
+} from './normalize';
+import type {
+    BurstParameters,
+    BurstParametersJSON,
+    ParticleSystemJSONParameters,
+    ParticleSystemParameters,
+} from './types';
 
 /**
  * One setting of a {@link ParticleSystem} that is a plain value or a generator: how to read it
@@ -54,6 +72,9 @@ export interface SettingDescriptor {
 
 type Generator = {toJSON(): unknown; clone(): unknown};
 
+/** A burst as files hold it, any field left out. */
+type BurstJSON = Partial<BurstParametersJSON>;
+
 /** A number, boolean or string compared by value. */
 function plain<T>(
     param: keyof ParticleSystemParameters,
@@ -97,11 +118,11 @@ function boolean(json: unknown): boolean | undefined {
  * A generator, compared with its default through its JSON. `read` turns the JSON back into one;
  * a bare number is read as a constant.
  */
-function generator(
+function generator<J>(
     param: keyof ParticleSystemParameters,
     get: (system: ParticleSystem) => Generator,
     defaultValue: () => Generator,
-    read: (json: any) => unknown,
+    read: (json: J) => unknown,
     always = true
 ): SettingDescriptor {
     const defaultJSON = JSON.stringify(defaultValue().toJSON());
@@ -111,7 +132,8 @@ function generator(
         get,
         isDefault: (value) => JSON.stringify((value as Generator).toJSON()) === defaultJSON,
         toJSON: (value) => (value as Generator).toJSON(),
-        fromJSON: (json) => (typeof json === 'number' ? new ConstantValue(json) : read(json)),
+        // The generator readers check the JSON they are given, and warn about what they cannot read.
+        fromJSON: (json) => (typeof json === 'number' ? new ConstantValue(json) : read(json as J)),
         clone: (value) => (value as Generator).clone(),
     };
 }
@@ -124,7 +146,7 @@ function vectorJSON(value: unknown): number[] | undefined {
 
 /** Every plain and generator setting, in the order `toJSON` writes them. */
 export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
-    plain('autoDestroy', (s) => s.autoDestroy, false, boolean),
+    plain('stopAction', (s) => s.stopAction, 'none', validStopAction),
     plain('looping', (s) => s.looping, true, boolean),
     plain('prewarm', (s) => s.prewarm, false, boolean),
     plain('prewarmTime', (s) => s.prewarmTime, 0, number),
@@ -152,19 +174,21 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
         'startRotation',
         (s) => s.startRotation,
         () => new ConstantValue(0),
-        (json) => GeneratorFromJSON(json) as RotationGenerator | ValueGenerator | FunctionValueGenerator
+        (json: ValueGeneratorJSON | RotationGeneratorJSON) =>
+            GeneratorFromJSON(json) as RotationGenerator | ValueGenerator | FunctionValueGenerator
     ),
     generator(
         'startSize',
         (s) => s.startSize,
         () => new ConstantValue(1),
-        (json) => GeneratorFromJSON(json) as Vector3Generator | ValueGenerator | FunctionValueGenerator
+        (json: ValueGeneratorJSON | Vector3GeneratorJSON) =>
+            GeneratorFromJSON(json) as Vector3Generator | ValueGenerator | FunctionValueGenerator
     ),
     generator(
         'startColor',
         (s) => s.startColor,
         () => new ConstantColor(new Vector4(1, 1, 1, 1)),
-        (json) => ColorGeneratorFromJSON(json) as ColorGenerator | FunctionColorGenerator
+        (json: ColorGeneratorJSON) => ColorGeneratorFromJSON(json) as ColorGenerator | FunctionColorGenerator
     ),
     generator(
         'emissionOverTime',
@@ -193,7 +217,7 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
         fromJSON: (json) =>
             Array.isArray(json)
                 ? normalizeBursts(
-                      json.map((burst: any) => ({
+                      json.map((burst: BurstJSON) => ({
                           time: burst.time,
                           count:
                               typeof burst.count === 'number'
@@ -208,6 +232,15 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
         clone: (value) => (value as BurstParameters[]).map((burst) => ({...burst, count: burst.count.clone()})),
     },
     plain('maxParticles', (s) => s.maxParticles, undefined, number),
+    plain('ringBufferMode', (s) => s.ringBufferMode, 'disabled', validRingBufferMode),
+    {
+        param: 'ringBufferLoopRange',
+        get: (s) => s.ringBufferLoopRange,
+        isDefault: (value) => (value as Vector2).x === 0 && (value as Vector2).y === 1,
+        toJSON: vectorJSON,
+        fromJSON: (json) => (Array.isArray(json) ? validLoopRange(new Vector2(json[0], json[1])) : undefined),
+        clone: (value) => (value as Vector2).clone(),
+    },
     plain('onlyUsedByOther', (s) => s.onlyUsedByOther, false, boolean),
     plain('renderMode', (s) => s.renderMode, RenderMode.BillBoard, number),
     plain('renderOrder', (s) => s.renderOrder, 0, number),
@@ -218,16 +251,18 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
         true,
         (json) => json !== false
     ),
-    plain('playbackSpeed', (s) => s.playbackSpeed, 1, number),
-    plain('cullingMode', (s) => s.cullingMode, 'always', validCullingMode),
     plain(
-        'scalingMode',
-        (s) => s.scalingMode,
-        'shape',
-        (json) => (json === 'hierarchy' ? 'hierarchy' : 'shape')
+        'applyImageProcessing',
+        (s) => s.applyImageProcessing,
+        true,
+        (json) => json !== false
     ),
+    plain('playbackSpeed', (s) => s.playbackSpeed, 1, number),
+    plain('cullingMode', (s) => s.cullingMode, 'always', validCullingMode),
+    plain('scalingMode', (s) => s.scalingMode, 'local', validScalingMode),
     plain('seed', (s) => s.seed, undefined, number),
     plain('sortMode', (s) => s.sortMode, 'none', validSortMode),
+    plain('renderFace', (s) => s.renderFace, 'both', validRenderFace),
     plain(
         'alignToDirection',
         (s) => s.alignToDirection,
@@ -299,11 +334,16 @@ export function settingsFromJSON(json: ParticleSystemJSONParameters): Partial<Pa
         if (value === undefined || value === null) {
             continue;
         }
-        const read = setting.fromJSON(value);
+        const key = settingJSONKey(setting);
+        const read = readFormatPart(key, () => setting.fromJSON(value));
         if (read !== undefined) {
             parameters[setting.param] = read;
         }
     }
+    // Files before 0.29 wrote the stop action as `autoDestroy`.
+    if (parameters.stopAction === undefined && fields.autoDestroy === true) {
+        parameters.stopAction = 'destroy';
+    }
     return parameters as Partial<ParticleSystemParameters>;
 }
 

package/src/system/types.ts

@@ -1,18 +1,27 @@
+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,
-    FunctionJSON,
     FunctionValueGenerator,
     RendererEmitterSettings,
     RotationGenerator,
+    RotationGeneratorJSON,
+    ShapeJSON,
+    StretchedBillBoardSettings,
     ValueGenerator,
+    ValueGeneratorJSON,
     Vector2,
     Vector3,
+    Vector3ArrayJSON,
     Vector3Generator,
+    Vector3GeneratorJSON,
+    Vector3JSON,
 } from 'quarks.core';
 import type {
     MeshLighting,
@@ -20,10 +29,28 @@ import type {
     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
@@ -64,22 +91,78 @@ export interface BurstParameters {
  * 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.
+ * What a system does once it has finished, its emission over and its last particle dead (Unity's
+ * Stop Action):
+ *
+ * - `'none'` (the default): nothing; {@link ParticleSystem.restart} plays it again.
+ * - `'disable'`: disables its emitter node (`setEnabled(false)`), and with it the nodes under it.
+ *   A disabled system is not advanced or drawn; enable the emitter again before playing it.
+ * - `'destroy'`: disposes the system and its emitter, as `ParticleSystem.dispose()` does.
+ *
+ * Unity's Callback is the system's `finished` event, which fires whatever the stop action. The
+ * action waits for the system's sub emitters, see {@link ParticleSystem.stopAction}. A disabled
+ * emitter is state like any other: saved as not visible, and copied disabled by `clone`.
+ */
+export type StopAction = 'none' | 'disable' | 'destroy';
+
+/**
+ * What a full system does with the particles it emits next (Unity's Ring Buffer Mode). It needs
+ * {@link ParticleSystemParameters.maxParticles}; without a limit it is ignored.
+ *
+ * - `'disabled'` (the default): particles die at the end of their life, and a full system drops
+ *   what it would emit.
+ * - `'pauseUntilReplaced'`: a particle at the end of its life stays where and as it is, frozen,
+ *   until a new particle replaces it, the oldest first. For footprints, decals and bullet holes.
+ * - `'loopUntilReplaced'`: a particle at the end of its life goes back to an earlier point of it
+ *   and plays that part again, over and over, until a new particle replaces it; see
+ *   {@link ParticleSystem.ringBufferLoopRange}.
+ *
+ * Particles are never killed by age, so a system in either mode keeps its particles and does not
+ * finish while it has any: a non-looping ring effect never fires `finished`, and an
+ * `EffectPool` copy of it returns to the pool only when it is released. A replaced particle
+ * does not fire `particleDied`, nor Death sub emitters, which never fire in either mode since
+ * no particle dies. Lowering `maxParticles` drops the oldest particles over the new limit, also
+ * without `particleDied`. Particles are replaced oldest first in the order they were emitted;
+ * switching a mode on in a system whose particles have already died in a different order
+ * replaces them in row order the first time round. `'oldestInFront'` and `'youngestInFront'`
+ * sorting reads age, so a looping particle sorts by its age in the loop. Applies in every
+ * render mode but Trail, whose particles always die at the end of their life.
+ */
+export type RingBufferMode = 'disabled' | 'pauseUntilReplaced' | 'loopUntilReplaced';
+
+/**
+ * What the emitter's scale does to the system, as Unity's Scaling Mode, in world and local space
+ * alike. The scale reaches the emission shape, the particles' size, their start speed and, in world
+ * space, `ForceOverLife`, `ApplyForce` and `LimitSpeedOverLife` (by the mean of the axes), so a
+ * scaled effect looks and moves like a scaled model, except where a mode leaves it out:
  *
- * - `'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.
+ * - `'local'` (default, as in Unity): only the emitter's own `scaling`; its parents' scale is left
+ *   out, so an effect keeps its size under a scaled character or prop.
+ * - `'hierarchy'`: the emitter's whole world scale, its parents' included.
+ * - `'shape'`: the world scale sizes the emission shape alone; the particles keep their size and
+ *   speed, so a bigger emitter spreads the same particles over a larger area.
+ *
+ * Under every mode the emitter's position, rotation and any mirroring come from the whole
+ * hierarchy; only the length of each axis changes. A sub emission starts in its parent particle's
+ * frame and takes its size and speed from that, not from the sub emitter's scale; `'shape'` still
+ * scales its shape by the sub emitter's world scale. With a non-uniform scale `'shape'` stretches
+ * where particles start, not the directions the shape sends them.
+ *
+ * Known differences from Unity: a world force (`ForceOverLife`, `ApplyForce`, and so the gravity
+ * the Unity exporter writes) is scaled with the motion in `'local'` and `'hierarchy'`, where
+ * Unity's gravity is not.
  */
-export type ScalingMode = 'shape' | 'hierarchy';
+export type ScalingMode = 'local' | 'hierarchy' | 'shape';
 
 /**
  * Where a {@link RenderMode.Beam} system's quads end: a point in world space,
@@ -112,7 +195,12 @@ export type BeamEnd =
  * default named on it, the same default `fromJSON` gives a file that leaves it out.
  */
 export interface ParticleSystemParameters {
-    /** See {@link ParticleSystem.autoDestroy}. Default false. */
+    /** What the system does once it has finished, see {@link StopAction}. Default `'none'`. */
+    stopAction?: StopAction;
+    /**
+     * `true` is `stopAction: 'destroy'`; read only when `stopAction` is left out.
+     * @deprecated Use `stopAction: 'destroy'`.
+     */
     autoDestroy?: boolean;
     /** See {@link ParticleSystem.looping}. Default true. */
     looping?: boolean;
@@ -144,6 +232,10 @@ export interface ParticleSystemParameters {
     emissionBursts?: Array<BurstParameters>;
     /** Most particles alive at once; emission past it is dropped. Leave unset for no limit. */
     maxParticles?: number;
+    /** What a full system does with new particles, see {@link RingBufferMode}. Default `'disabled'`. */
+    ringBufferMode?: RingBufferMode;
+    /** See {@link ParticleSystem.ringBufferLoopRange}. Default the whole life, (0, 1). */
+    ringBufferLoopRange?: Vector2;
     /** See {@link ParticleSystem.onlyUsedByOther}. Default false. */
     onlyUsedByOther?: boolean;
     /** See {@link ParticleSystem.behaviors}. Default none. */
@@ -169,7 +261,7 @@ export interface ParticleSystemParameters {
     /** @deprecated Set `speedFactor` in {@link rendererEmitterSettings} instead; this one wins when both are set. */
     speedFactor?: number;
     /** See {@link ParticleSystem.material}. Default none. */
-    material?: unknown;
+    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. */
@@ -230,12 +322,14 @@ export interface ParticleSystemParameters {
     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'`. */
+    /** What the emitter's scale does to the system, see {@link ScalingMode}. Default `'local'`. */
     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. */
@@ -246,6 +340,8 @@ export interface ParticleSystemParameters {
     renderingGroupId?: number;
     /** Whether the scene's fog applies, see {@link ParticleSystem.applyFog}. Default true. */
     applyFog?: boolean;
+    /** Whether the scene's image processing applies, see {@link ParticleSystem.applyImageProcessing}. Default true. */
+    applyImageProcessing?: boolean;
     /** Scene the emitter node is created in. Default Babylon's last created scene. */
     scene?: Scene;
 }
@@ -255,13 +351,15 @@ export interface BurstParametersJSON {
     /** See {@link BurstParameters.time}. */
     time: number;
     /** See {@link BurstParameters.count}. */
-    count: FunctionJSON | number;
+    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;
 }
 
 /**
@@ -277,7 +375,9 @@ export interface BurstParametersJSON {
 export interface ParticleSystemJSONParameters {
     /** The quarks.core version line the system was written with. */
     version: string;
-    /** See {@link ParticleSystem.autoDestroy}. */
+    /** Written only when not `'none'`. */
+    stopAction?: StopAction;
+    /** Read from older files: `true` is `stopAction: 'destroy'`. No longer written. */
     autoDestroy?: boolean;
     /** See {@link ParticleSystem.looping}. */
     looping?: boolean;
@@ -288,36 +388,40 @@ export interface ParticleSystemJSONParameters {
     /** See {@link ParticleSystem.duration}. */
     duration?: number;
     /** See {@link ParticleSystem.startDelay}. */
-    startDelay?: FunctionJSON;
+    startDelay?: ValueGeneratorJSON;
     /** The emitter shape, as its `toJSON` writes it. */
-    shape?: any;
+    shape?: ShapeJSON;
     /** See {@link ParticleSystem.startLife}. */
-    startLife?: FunctionJSON;
+    startLife?: ValueGeneratorJSON;
     /** See {@link ParticleSystem.startSpeed}. */
-    startSpeed?: FunctionJSON;
+    startSpeed?: ValueGeneratorJSON;
     /** See {@link ParticleSystem.startRotation}. */
-    startRotation?: FunctionJSON;
+    startRotation?: ValueGeneratorJSON | RotationGeneratorJSON;
     /** See {@link ParticleSystem.startSize}. */
-    startSize?: FunctionJSON;
+    startSize?: ValueGeneratorJSON | Vector3GeneratorJSON;
     /** See {@link ParticleSystem.startColor}. */
-    startColor?: FunctionJSON;
+    startColor?: ColorGeneratorJSON;
     /** See {@link ParticleSystem.emissionOverTime}. */
-    emissionOverTime?: FunctionJSON;
+    emissionOverTime?: ValueGeneratorJSON;
     /** See {@link ParticleSystem.emissionOverDistance}. */
-    emissionOverDistance?: FunctionJSON;
+    emissionOverDistance?: ValueGeneratorJSON;
     /** See {@link ParticleSystem.emissionBursts}. */
     emissionBursts?: Array<BurstParametersJSON>;
     /** See {@link ParticleSystem.maxParticles}. */
     maxParticles?: number;
+    /** Written only when not `'disabled'`. */
+    ringBufferMode?: RingBufferMode;
+    /** `[start, end]`; written only when not `[0, 1]`. */
+    ringBufferLoopRange?: [number, number];
     /** See {@link ParticleSystem.onlyUsedByOther}. */
     onlyUsedByOther?: boolean;
     /**
-     * Trail, stretched or mesh settings; a trail's `startLength` as `FunctionJSON`. Left out when
+     * Trail, stretched or mesh settings; a trail's `startLength` as `ValueGeneratorJSON`. Left out when
      * the render mode has none.
      */
-    rendererEmitterSettings?: RendererEmitterSettings;
-    /** Uuid of the mesh particles' geometry entry. */
-    instancingGeometry?: any;
+    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}. */
@@ -326,16 +430,20 @@ export interface ParticleSystemJSONParameters {
     renderingGroupId?: number;
     /** Written only when false. */
     applyFog?: boolean;
+    /** Written only when false. */
+    applyImageProcessing?: boolean;
     /** Written only when not 1. */
     playbackSpeed?: number;
     /** Written only when not `'always'`. */
     cullingMode?: CullingMode;
-    /** Written only when not `'shape'`. */
+    /** Written only when not `'local'`. */
     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. */
@@ -351,7 +459,7 @@ export interface ParticleSystemJSONParameters {
     /** The camera layer mask. */
     layers?: number;
     /** See {@link ParticleSystem.startTileIndex}. */
-    startTileIndex?: FunctionJSON | number;
+    startTileIndex?: ValueGeneratorJSON | number;
     /** See {@link ParticleSystem.uTileCount}. */
     uTileCount?: number;
     /** See {@link ParticleSystem.vTileCount}. */
@@ -375,7 +483,7 @@ export interface ParticleSystemJSONParameters {
     /** See {@link ParticleSystemParameters.alphaTest}. */
     alphaTest?: number;
     /** Each behavior as its `toJSON` writes it. */
-    behaviors?: Array<any>;
+    behaviors?: BehaviorJSON[];
     /** See {@link ParticleSystem.worldSpace}. */
     worldSpace?: boolean;
     /** `[x, y, z]`; written only when non-zero. */
@@ -392,19 +500,19 @@ export interface ParticleSystemJSONParameters {
  */
 export interface BabylonMetaData {
     /** Textures by uuid; null for one that could not be made. */
-    textures: {[uuid: string]: Texture | null};
+    textures: {[uuid: string]: BaseTexture | null};
     /** Material entries by uuid. */
-    materials: {[uuid: string]: any};
+    materials: {[uuid: string]: QuarksMaterialJSON};
     /** Geometry entries by uuid. */
-    geometries: {[uuid: string]: any};
-    /** Image entries by uuid. */
-    images?: {[uuid: string]: any};
+    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. */
-    shapes?: {[uuid: string]: any};
+    skeletons?: {[uuid: string]: unknown};
     /** Not used by babylon.quarks; kept for three.js-shaped documents. */
-    skeletons?: {[uuid: string]: any};
+    animations?: {[uuid: string]: unknown};
     /** Not used by babylon.quarks; kept for three.js-shaped documents. */
-    animations?: {[uuid: string]: any};
-    /** Nodes by uuid, which a mesh surface shape links to. */
-    nodes?: {[uuid: string]: any};
+    nodes?: {[uuid: string]: unknown};
 }

package/src/trailSettings.ts

@@ -1,5 +1,8 @@
 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
@@ -10,13 +13,13 @@ import type {TrailSettings, TrailTextureMode} from 'quarks.core';
 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: TrailSettings | undefined): number {
+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: TrailSettings | undefined): number {
+export function trailCurveTension(settings: Partial<TrailOptions> | undefined): number {
     const value = Number(settings?.curveTension) || 0;
     return Math.min(1, Math.max(0, value));
 }
@@ -24,19 +27,19 @@ export function trailCurveTension(settings: TrailSettings | undefined): number {
 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: TrailSettings | undefined): TrailTextureMode {
+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: TrailSettings | undefined): number {
+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: TrailSettings | undefined): number {
+export function trailMinVertexDistance(settings: Partial<TrailOptions> | undefined): number {
     const value = Number(settings?.minVertexDistance);
     return Number.isFinite(value) && value > 0 ? value : 0;
 }
@@ -45,7 +48,7 @@ export function trailMinVertexDistance(settings: TrailSettings | undefined): num
  * 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: TrailSettings | undefined): number {
+export function trailLifetime(settings: Partial<TrailOptions> | undefined): number {
     const value = Number(settings?.lifetime);
     return Number.isFinite(value) && value > 0 ? value : Infinity;
 }