babylon.quarks 0.27.0 → 0.28.0

package/src/system/materialResolve.ts

@@ -1,5 +1,5 @@
 import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
-import type {Texture} from '@babylonjs/core/Materials/Textures/texture';
+import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import type {VFXBatchSettings} from '../BatchedRenderer';
 
 /** Settings given next to a material, which win over what is read from it. */
@@ -14,6 +14,52 @@ export interface MaterialOverrides {
     layerMask?: number;
 }
 
+/**
+ * What a {@link ParticleSystem} reads its draw settings from: a Babylon material (`StandardMaterial`,
+ * `PBRMaterial`, a node material, …), or a material entry of an effect file once its texture slots
+ * are resolved to textures, as `ParticleSystem.fromJSON` does. Each field is read only when it is
+ * there, so any material fits; the particles are still drawn with quarks' own shaders. The particle
+ * texture is the first slot that holds a `Texture`.
+ */
+export interface ParticleMaterialSource {
+    /** A PBR material's base colour texture. */
+    albedoTexture?: BaseTexture | null;
+    /** A standard material's diffuse texture. */
+    diffuseTexture?: BaseTexture | null;
+    /** An emissive texture, read when there is no albedo or diffuse texture. */
+    emissiveTexture?: BaseTexture | null;
+    /** An opacity texture, read when there is none of the above. */
+    opacityTexture?: BaseTexture | null;
+    /** A base texture, read last. */
+    baseTexture?: BaseTexture | null;
+    /** The reflection texture; a cube is drawn through a 3×2 atlas built from it. */
+    reflectionTexture?: BaseTexture | null;
+    /** A PBR material's environment texture, read when there is no reflection texture. */
+    environmentTexture?: BaseTexture | null;
+    /** How strong the reflection is; the reflection texture's `level` when unset. */
+    reflectionLevel?: number;
+    /** A 3×2 env atlas for the reflection; the system stores the atlas it builds from a cube here. */
+    reflectionAtlas?: BaseTexture | null;
+    /** A Babylon alpha mode constant. */
+    alphaMode?: number;
+    /** Whether the material blends; decides `transparent`. */
+    needAlphaBlending?(): boolean;
+    /** Opacity, read for `transparent` when there is no `needAlphaBlending`. */
+    alpha?: number;
+    /** Inverted into `depthTest`. */
+    disableDepthTest?: boolean;
+    /** Inverted into `depthWrite`. */
+    disableDepthWrite?: boolean;
+    /** Read for `depthWrite` when there is no `disableDepthWrite`. */
+    forceDepthWrite?: boolean;
+    /** The alpha test cutoff is read only in an alpha-test mode (1 or 3). */
+    transparencyMode?: number | null;
+    /** The alpha test cutoff. */
+    alphaCutOff?: number;
+    /** The alpha test cutoff, as some materials name it. */
+    alphaCutOffValue?: number;
+}
+
 /** The draw settings a {@link ParticleSystem} takes from a material, before the env atlas is built. */
 export interface ResolvedMaterialSettings {
     texture: Texture | null;
@@ -39,18 +85,21 @@ export function liveAtlas<T extends BaseTexture>(atlas: T | null | undefined): T
  * material does not have keeps its `current` value.
  */
 export function resolveMaterialSettings(
-    material: any,
+    material: ParticleMaterialSource | null | undefined,
     overrides: MaterialOverrides,
     current: VFXBatchSettings
 ): ResolvedMaterialSettings {
+    // The particle texture is a `Texture`: the first slot that holds one, so a cube in a slot is passed over.
     const texture =
         overrides.texture !== undefined
             ? overrides.texture
-            : (material?.albedoTexture ??
-              material?.diffuseTexture ??
-              material?.emissiveTexture ??
-              material?.opacityTexture ??
-              material?.baseTexture ??
+            : ([
+                  material?.albedoTexture,
+                  material?.diffuseTexture,
+                  material?.emissiveTexture,
+                  material?.opacityTexture,
+                  material?.baseTexture,
+              ].find((slot): slot is Texture => slot instanceof Texture) ??
               current.texture ??
               null);
     const reflectionTexture =

package/src/system/normalize.ts

@@ -1,5 +1,5 @@
 import {ConstantValue, FunctionValueGenerator, ValueGenerator, Vector2, Vector3} from 'quarks.core';
-import type {MeshLighting, SortMode} from '../VFXBatch';
+import type {MeshLighting, RenderFace, SortMode} from '../batchSettings';
 import type {BurstParameters, CullingMode} from './types';
 
 // Normalisers shared by the ParticleSystem constructor, its setters and its JSON reader, so a
@@ -15,6 +15,11 @@ export function validSortMode(mode: unknown): SortMode {
     return mode === 'distance' || mode === 'oldestInFront' || mode === 'youngestInFront' ? mode : 'none';
 }
 
+/** `face` if it is one of the render faces, else `'both'`. */
+export function validRenderFace(face: unknown): RenderFace {
+    return face === 'front' || face === 'back' ? face : 'both';
+}
+
 /** `mode` if it is one of the culling modes, else `'always'`. */
 export function validCullingMode(mode: unknown): CullingMode {
     return mode === 'pause' || mode === 'pauseAndCatchUp' ? mode : 'always';

package/src/system/serialization.ts

@@ -3,14 +3,20 @@ import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import type {Scene} from '@babylonjs/core/scene';
 import {
+    BehaviorToJSON,
     ConstantValue,
     EmitterFromJSON,
+    EmitterToJSON,
+    readFormatPart,
     RendererEmitterSettings,
     StretchedBillBoardSettings,
     TrailSettings,
     ValueGeneratorFromJSON,
     Vector3,
+    Vector3ArrayJSON,
+    warnFormat,
 } from 'quarks.core';
+import type {MaterialTextureRef} from '../effectDocumentJSON';
 import type {ParticleSystem} from '../ParticleSystem';
 import {
     trailCurveTension,
@@ -19,6 +25,7 @@ import {
     trailTessellation,
     trailTextureMode,
     trailTextureScale,
+    type TrailOptions,
 } from '../trailSettings';
 import {
     EROSION_DEFAULT_SOFTNESS,
@@ -28,8 +35,15 @@ import {
     UV_DISTORTION_DEFAULT_UV,
 } from '../VFXBatch';
 import {resolveGeometryData} from './geometry';
+import type {ParticleMaterialSource} from './materialResolve';
 import {settingsFromJSON, settingsToJSON} from './settingsSchema';
-import type {BabylonMetaData, ParticleSystemJSONParameters, ParticleSystemParameters} from './types';
+import type {
+    BabylonMetaData,
+    ParticleSystemJSONParameters,
+    ParticleSystemParameters,
+    RendererEmitterSettingsJSON,
+    TrailSettingsJSON,
+} from './types';
 
 // Reading and writing a ParticleSystem's JSON. The class's toJSON and fromJSON call these.
 
@@ -49,8 +63,8 @@ function nextSerializationId(meta: BabylonMetaData, prefix: string): string {
 }
 
 /** The optional trail flags that are switched on, so JSON and clones only carry the ones in use. */
-export function trailFlags(settings: TrailSettings | undefined): Partial<TrailSettings> {
-    const flags: Partial<TrailSettings> = {};
+export function trailFlags(settings: Partial<TrailOptions> | undefined): Partial<TrailOptions> {
+    const flags: Partial<TrailOptions> = {};
     if (settings?.uvFromHead) flags.uvFromHead = true;
     if (settings?.colorFromParticle) flags.colorFromParticle = true;
     if (settings?.dieWithParticle) flags.dieWithParticle = true;
@@ -59,8 +73,8 @@ export function trailFlags(settings: TrailSettings | undefined): Partial<TrailSe
 }
 
 /** A trail's tessellation and curve tension, normalised, each only when it differs from the default. */
-export function trailCurve(settings: TrailSettings | undefined): Partial<TrailSettings> {
-    const curve: Partial<TrailSettings> = {};
+export function trailCurve(settings: Partial<TrailOptions> | undefined): Partial<TrailOptions> {
+    const curve: Partial<TrailOptions> = {};
     const tessellation = trailTessellation(settings);
     const curveTension = trailCurveTension(settings);
     if (tessellation > 0) curve.tessellation = tessellation;
@@ -72,8 +86,8 @@ export function trailCurve(settings: TrailSettings | undefined): Partial<TrailSe
  * A trail's texture mode and scale, minimum vertex distance and lifetime, normalised, each only
  * when it differs from the default.
  */
-export function trailSampling(settings: TrailSettings | undefined): Partial<TrailSettings> {
-    const out: Partial<TrailSettings> = {};
+export function trailSampling(settings: Partial<TrailOptions> | undefined): Partial<TrailOptions> {
+    const out: Partial<TrailOptions> = {};
     const textureMode = trailTextureMode(settings);
     const textureScale = trailTextureScale(settings);
     const minVertexDistance = trailMinVertexDistance(settings);
@@ -86,12 +100,12 @@ export function trailSampling(settings: TrailSettings | undefined): Partial<Trai
 }
 
 /** A trail's `followLocalOrigin`, only when on: off is the default. */
-export function trailFollowLocalOrigin(settings: TrailSettings | undefined): Partial<TrailSettings> {
+export function trailFollowLocalOrigin(settings: Partial<TrailOptions> | undefined): Partial<TrailOptions> {
     return settings?.followLocalOrigin ? {followLocalOrigin: true} : {};
 }
 
 /** A trail's side axis as JSON `[x, y, z]`, or nothing when unset. */
-function trailSideAxisJSON(settings: TrailSettings | undefined): {sideAxis?: number[]} {
+function trailSideAxisJSON(settings: TrailSettings | undefined): {sideAxis?: Vector3ArrayJSON} {
     const axis = settings?.sideAxis;
     return axis ? {sideAxis: [axis.x, axis.y, axis.z]} : {};
 }
@@ -120,7 +134,7 @@ function trailSideAxisFromJSON(value: unknown): {sideAxis?: Vector3} {
     if (Number.isFinite(nx) && Number.isFinite(ny) && Number.isFinite(nz) && nx * nx + ny * ny + nz * nz > 0) {
         return {sideAxis: new Vector3(nx, ny, nz)};
     }
-    console.warn(`[quarks] sideAxis ${JSON.stringify(value)} is not a direction and is ignored`);
+    warnFormat(`sideAxis ${JSON.stringify(value)} is not a direction and is ignored`);
     return {};
 }
 
@@ -149,15 +163,17 @@ export function particleSystemToJSON(
 
     // Only what differs from the defaults the constructor and fromJSON give a setting left out.
     // The shape, the settings the table marks `always`, the geometry, the material and the
-    // behaviors are always written: the loaders of 0.27 and earlier, and three.quarks, need them.
+    // behaviors list are always written: the loaders of 0.27 and earlier need them. Within the
+    // shape and each behavior, only the fields that differ from their defaults, which 0.27 reads
+    // and three.quarks may not (see docs/FORMAT.md).
     return {
         version: '3.0',
-        shape: system.emitterShape.toJSON(),
+        shape: EmitterToJSON(system.emitterShape),
         ...settingsToJSON(system),
         instancingGeometry: geometryUUID,
-        ...(Object.keys(rendererSettingsJSON).length > 0 ? {rendererEmitterSettings: rendererSettingsJSON} : {}),
+        ...(rendererSettingsJSON ? {rendererEmitterSettings: rendererSettingsJSON} : {}),
         material: materialUUID,
-        behaviors: system.behaviors.map((b) => b.toJSON()),
+        behaviors: system.behaviors.map((b) => BehaviorToJSON(b, system)),
     };
 }
 
@@ -172,10 +188,10 @@ export function particleSystemParametersFromJSON(
     scene?: Scene
 ): ParticleSystemParameters {
     // A part the file leaves out takes the constructor's default, as a system made in code does.
-    const shape = json.shape ? EmitterFromJSON(json.shape, meta as any) : undefined;
+    const shape = json.shape ? readFormatPart('shape', () => EmitterFromJSON(json.shape!, meta)) : undefined;
     let rendererEmitterSettings: RendererEmitterSettings;
     if (json.renderMode === RenderMode.Trail) {
-        const trailSettings = json.rendererEmitterSettings as TrailSettings;
+        const trailSettings = json.rendererEmitterSettings as TrailSettingsJSON | undefined;
         rendererEmitterSettings = {
             startLength:
                 trailSettings?.startLength !== undefined
@@ -185,26 +201,31 @@ export function particleSystemParametersFromJSON(
             ...trailFlags(trailSettings),
             ...trailCurve(trailSettings),
             ...trailSampling(trailSettings),
-            ...trailSideAxisFromJSON((trailSettings as {sideAxis?: unknown} | undefined)?.sideAxis),
+            ...trailSideAxisFromJSON(trailSettings?.sideAxis),
         };
     } else if (json.renderMode === RenderMode.StretchedBillBoard) {
-        rendererEmitterSettings = {...(json.rendererEmitterSettings ?? {})};
+        // The render mode says which settings the file holds.
+        const stretched: Partial<StretchedBillBoardSettings> = {
+            ...(json.rendererEmitterSettings as StretchedBillBoardSettings | undefined),
+        };
         if (json.speedFactor !== undefined) {
-            (rendererEmitterSettings as StretchedBillBoardSettings).speedFactor = json.speedFactor;
+            stretched.speedFactor = json.speedFactor;
         }
+        rendererEmitterSettings = stretched;
     } else {
         rendererEmitterSettings = {};
     }
 
     const materialMeta = json.material ? meta.materials?.[json.material] : undefined;
-    const materialTextureRef = materialMeta?.texture ?? json.texture;
-    const texture =
-        typeof materialTextureRef === 'string'
-            ? (meta.textures?.[materialTextureRef] ?? null)
-            : (materialTextureRef ?? null);
-    // Texture effects reference textures by uuid in a serialised meta, or hold them once a loader resolved them.
-    const resolveTexture = (ref: unknown): BaseTexture | null =>
-        typeof ref === 'string' ? (meta.textures?.[ref] ?? null) : ((ref as BaseTexture | null) ?? null);
+    // Texture slots reference textures by uuid in a serialised meta, or hold them once a loader resolved them.
+    const resolveTexture = (ref: MaterialTextureRef | undefined): BaseTexture | null =>
+        typeof ref === 'string' ? (meta.textures?.[ref] ?? null) : (ref ?? null);
+    const mainTexture = resolveTexture(materialMeta?.texture ?? json.texture);
+    // Particles sample a 2D texture.
+    const texture = mainTexture instanceof Texture ? mainTexture : null;
+    const material: ParticleMaterialSource | undefined =
+        materialMeta?.sourceMaterial ??
+        (materialMeta ? {...materialMeta, reflectionAtlas: resolveTexture(materialMeta.reflectionAtlas)} : undefined);
     const erosionMeta = materialMeta?.erosion;
     const gradientMeta = materialMeta?.gradientMap;
     const distortionMeta = materialMeta?.uvDistortion;
@@ -226,7 +247,7 @@ export function particleSystemParametersFromJSON(
         instancingNormals: resolvedGeometry.normals,
         rendererEmitterSettings,
         texture,
-        material: materialMeta?.sourceMaterial ?? materialMeta,
+        material,
         // The material entry wins over the system's own fields, which older files wrote too.
         blendMode: materialMeta?.alphaMode ?? settings.blendMode ?? Constants.ALPHA_ADD,
         transparent: materialMeta?.transparent ?? settings.transparent ?? true,
@@ -253,7 +274,7 @@ export function particleSystemParametersFromJSON(
 }
 
 /** The render mode's own settings as JSON: a trail's or a stretched billboard's, else none. */
-function rendererEmitterSettingsJSON(system: ParticleSystem): RendererEmitterSettings {
+function rendererEmitterSettingsJSON(system: ParticleSystem): RendererEmitterSettingsJSON | undefined {
     if (system.renderMode === RenderMode.Trail) {
         const settings = system.rendererEmitterSettings as TrailSettings;
         // `startLength` always, for loaders that read it without a default; the rest only when on.
@@ -263,8 +284,8 @@ function rendererEmitterSettingsJSON(system: ParticleSystem): RendererEmitterSet
             ...trailFlags(settings),
             ...trailCurve(settings),
             ...trailSampling(settings),
-            ...(trailSideAxisJSON(settings) as {sideAxis?: any}),
-        } as TrailSettings;
+            ...trailSideAxisJSON(settings),
+        };
     }
     if (system.renderMode === RenderMode.StretchedBillBoard) {
         return {
@@ -272,7 +293,7 @@ function rendererEmitterSettingsJSON(system: ParticleSystem): RendererEmitterSet
             lengthFactor: (system.rendererEmitterSettings as StretchedBillBoardSettings).lengthFactor,
         };
     }
-    return {};
+    return undefined;
 }
 
 /** Writes the system's geometry into `meta` once per document, and returns its uuid. */
@@ -337,7 +358,7 @@ function materialMeta(system: ParticleSystem, meta: BabylonMetaData): string {
         if (uuid === undefined) {
             uuid = nextSerializationId(meta, 'quarks_texture');
             textures.set(value, uuid);
-            meta.textures[uuid] = value as Texture;
+            meta.textures[uuid] = value;
         }
         return uuid;
     };

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,20 @@ 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,
+    validRenderFace,
+    validSortMode,
+    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 +68,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 +114,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 +128,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(),
     };
 }
@@ -152,19 +170,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 +213,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'
@@ -228,6 +248,7 @@ export const SETTINGS: ReadonlyArray<SettingDescriptor> = [
     ),
     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,7 +320,8 @@ 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;
         }

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,6 +91,12 @@ 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';
 
@@ -169,7 +202,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. */
@@ -236,6 +269,8 @@ export interface ParticleSystemParameters {
     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. */
@@ -255,13 +290,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;
 }
 
 /**
@@ -288,23 +325,23 @@ 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}. */
@@ -312,12 +349,12 @@ export interface ParticleSystemJSONParameters {
     /** 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}. */
@@ -336,6 +373,8 @@ export interface ParticleSystemJSONParameters {
     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 +390,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 +414,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 +431,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};
 }