babylon.quarks 0.26.0 → 0.28.0

package/src/system/materialResolve.ts

@@ -0,0 +1,165 @@
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+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. */
+export interface MaterialOverrides {
+    blendMode?: number;
+    transparent?: boolean;
+    depthTest?: boolean;
+    depthWrite?: boolean;
+    alphaTest?: number;
+    texture?: Texture | null;
+    reflectionAtlas?: BaseTexture | null;
+    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;
+    reflectionTexture: BaseTexture | null;
+    reflectionLevel: number;
+    /** A live atlas the material, the overrides or the current settings already have; null if none. */
+    reflectionAtlas: BaseTexture | null;
+    blendMode: number;
+    transparent: boolean;
+    depthTest: boolean;
+    depthWrite: boolean;
+    alphaTest: number;
+}
+
+/** `atlas` unless it has been disposed (it no longer has a scene). */
+export function liveAtlas<T extends BaseTexture>(atlas: T | null | undefined): T | null {
+    return atlas?.getScene() ? atlas : null;
+}
+
+/**
+ * Reads the draw settings from a Babylon material, or from the material record of a loaded file:
+ * its texture, reflection, alpha mode, depth flags and alpha test. `overrides` win; a setting the
+ * material does not have keeps its `current` value.
+ */
+export function resolveMaterialSettings(
+    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,
+              ].find((slot): slot is Texture => slot instanceof Texture) ??
+              current.texture ??
+              null);
+    const reflectionTexture =
+        material?.reflectionTexture ?? material?.environmentTexture ?? current.reflectionTexture ?? null;
+    const reflectionTextureLevel = typeof reflectionTexture?.level === 'number' ? reflectionTexture.level : 1;
+    const blendMode =
+        overrides.blendMode ??
+        (typeof material?.alphaMode === 'number' ? material.alphaMode : current.materialBlendMode);
+    const transparent =
+        overrides.transparent ??
+        (typeof material?.needAlphaBlending === 'function'
+            ? material.needAlphaBlending()
+            : typeof material?.alpha === 'number'
+              ? material.alpha < 1
+              : current.materialTransparent);
+    const depthTest =
+        overrides.depthTest ??
+        (typeof material?.disableDepthTest === 'boolean' ? !material.disableDepthTest : current.materialDepthTest);
+    const depthWrite =
+        overrides.depthWrite ??
+        (typeof material?.disableDepthWrite === 'boolean'
+            ? !material.disableDepthWrite
+            : typeof material?.forceDepthWrite === 'boolean'
+              ? material.forceDepthWrite
+              : current.materialDepthWrite);
+    const alphaTest =
+        overrides.alphaTest ??
+        (() => {
+            // StandardMaterial always has alphaCutOff (default 0.4). Only treat it as
+            // particle alpha-test when the material is actually in an alpha-test mode —
+            // otherwise Mesh Material demos wrongly enable USE_ALPHATEST.
+            const mode = material?.transparencyMode;
+            const alphaTestMode = mode === 1 || mode === 3;
+            if (alphaTestMode && typeof material?.alphaCutOff === 'number') {
+                return material.alphaCutOff;
+            }
+            if (alphaTestMode && typeof material?.alphaCutOffValue === 'number') {
+                return material.alphaCutOffValue;
+            }
+            if (material) {
+                return 0;
+            }
+            return current.materialAlphaTest;
+        })();
+    return {
+        texture,
+        reflectionTexture,
+        reflectionLevel:
+            typeof material?.reflectionLevel === 'number' ? material.reflectionLevel : reflectionTextureLevel,
+        // A disposed atlas (its cube was disposed, or disposeEnvAtlas ran) is skipped, so a new one is built.
+        reflectionAtlas:
+            liveAtlas(material?.reflectionAtlas) ??
+            liveAtlas(overrides.reflectionAtlas) ??
+            liveAtlas(current.reflectionAtlas),
+        // Do not expand cube files into six face textures anymore — that path
+        // still trips GL_INVALID_OPERATION on iOS. Prefer a single atlas.
+        blendMode,
+        transparent,
+        depthTest,
+        depthWrite,
+        alphaTest,
+    };
+}

package/src/system/normalize.ts

@@ -0,0 +1,100 @@
+import {ConstantValue, FunctionValueGenerator, ValueGenerator, Vector2, Vector3} from 'quarks.core';
+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
+// value read from a file and one set in code end up the same.
+
+/** `lighting` if it is one of the modes, else the default. */
+export function validLighting(lighting: unknown): MeshLighting {
+    return lighting === 'unlit' || lighting === 'scene' ? lighting : 'fixed';
+}
+
+/** `mode` if it is one of the sort modes, else `'none'`. */
+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';
+}
+
+/** `count` as a whole number of particles, or undefined (no limit) when it is unset, NaN or negative. */
+export function validMaxParticles(count: unknown): number | undefined {
+    return typeof count === 'number' && count >= 0 && count < Infinity ? Math.floor(count) : undefined;
+}
+
+/** A copy of `v`, or undefined when it is unset or zero, which is the same as no pivot. */
+export function nonZeroPivot(v: Vector3 | undefined): Vector3 | undefined {
+    return v && (v.x !== 0 || v.y !== 0 || v.z !== 0) ? v.clone() : undefined;
+}
+
+/** A copy of `v`, or undefined when neither axis flips. */
+export function nonZeroFlip(v: Vector2 | undefined): Vector2 | undefined {
+    return v && (v.x > 0 || v.y > 0) ? v.clone() : undefined;
+}
+
+/** `cutoff` kept to 0…1, or 0 (no alpha test) when it is unset, NaN or negative. */
+export function validAlphaTest(cutoff: unknown): number {
+    return typeof cutoff === 'number' && cutoff > 0 ? Math.min(cutoff, 1) : 0;
+}
+
+/** A flipbook's columns or rows: a whole number of cells, at least 1; anything else is 1. */
+export function validTileCount(count: unknown): number {
+    return typeof count === 'number' && Number.isFinite(count) && count >= 1 ? Math.floor(count) : 1;
+}
+
+/** World units in front of the scene over which a soft particle is fully faded by default. */
+export const DEFAULT_SOFT_FAR_FADE = 1;
+
+/** A soft-particle fade distance: finite and at least 0, else `fallback`. */
+export function validSoftFade(distance: unknown, fallback: number): number {
+    return typeof distance === 'number' && Number.isFinite(distance) && distance >= 0 ? distance : fallback;
+}
+
+/** Seconds between a burst's waves when a burst leaves `interval` out, in code and in a file. */
+export const DEFAULT_BURST_INTERVAL = 0.1;
+
+/**
+ * A burst with every field present and in range: a `time` that is a finite number of seconds
+ * (else 0), a `count` generator (a number becomes a constant, nothing becomes 0), `cycle` at least
+ * 1, `interval` {@link DEFAULT_BURST_INTERVAL} when left out and never negative, `probability`
+ * within 0..1 (1 when left out). The same rules apply to a burst given to the constructor and one
+ * read from a file, so both fire alike.
+ */
+export function normalizeBurst(burst: Partial<BurstParameters> & {count?: unknown}): BurstParameters {
+    const count = burst.count;
+    const time = typeof burst.time === 'number' && Number.isFinite(burst.time) && burst.time > 0 ? burst.time : 0;
+    const cycle = typeof burst.cycle === 'number' && Number.isFinite(burst.cycle) && burst.cycle >= 1 ? burst.cycle : 1;
+    const interval =
+        typeof burst.interval === 'number' && Number.isFinite(burst.interval)
+            ? Math.max(0, burst.interval)
+            : DEFAULT_BURST_INTERVAL;
+    const probability =
+        typeof burst.probability === 'number' && Number.isFinite(burst.probability)
+            ? Math.min(1, Math.max(0, burst.probability))
+            : 1;
+    return {
+        time,
+        count:
+            typeof count === 'number'
+                ? new ConstantValue(count)
+                : count !== undefined && count !== null
+                  ? (count as ValueGenerator | FunctionValueGenerator)
+                  : new ConstantValue(0),
+        cycle,
+        interval,
+        probability,
+    };
+}
+
+/** The bursts normalised (see {@link normalizeBurst}) and in time order, which emission relies on. */
+export function normalizeBursts(bursts: ReadonlyArray<Partial<BurstParameters>> | undefined): BurstParameters[] {
+    return (bursts ?? []).map(normalizeBurst).sort((a, b) => a.time - b.time);
+}

package/src/system/serialization.ts

@@ -0,0 +1,422 @@
+import {Constants} from '@babylonjs/core/Engines/constants';
+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,
+    trailLifetime,
+    trailMinVertexDistance,
+    trailTessellation,
+    trailTextureMode,
+    trailTextureScale,
+    type TrailOptions,
+} from '../trailSettings';
+import {
+    EROSION_DEFAULT_SOFTNESS,
+    RenderMode,
+    textureUVToJSON,
+    UV_DISTORTION_DEFAULT_STRENGTH,
+    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,
+    RendererEmitterSettingsJSON,
+    TrailSettingsJSON,
+} from './types';
+
+// Reading and writing a ParticleSystem's JSON. The class's toJSON and fromJSON call these.
+
+/** Per document being written: the last id handed out, and the geometries and textures written. */
+const serializationCounters = new WeakMap<object, number>();
+const serializedGeometries = new WeakMap<object, Array<{arrays: unknown[]; uuid: string}>>();
+const serializedTextures = new WeakMap<object, Map<BaseTexture, string>>();
+
+/**
+ * The next id for an entry of `meta`. Counted per document, so serialising the same effect
+ * twice writes the same ids.
+ */
+function nextSerializationId(meta: BabylonMetaData, prefix: string): string {
+    const id = (serializationCounters.get(meta) ?? 0) + 1;
+    serializationCounters.set(meta, id);
+    return `${prefix}_${id}`;
+}
+
+/** The optional trail flags that are switched on, so JSON and clones only carry the ones in use. */
+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;
+    if (settings?.recordWorldSpace) flags.recordWorldSpace = true;
+    return flags;
+}
+
+/** A trail's tessellation and curve tension, normalised, each only when it differs from the default. */
+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;
+    if (curveTension > 0) curve.curveTension = curveTension;
+    return curve;
+}
+
+/**
+ * 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: Partial<TrailOptions> | undefined): Partial<TrailOptions> {
+    const out: Partial<TrailOptions> = {};
+    const textureMode = trailTextureMode(settings);
+    const textureScale = trailTextureScale(settings);
+    const minVertexDistance = trailMinVertexDistance(settings);
+    const lifetime = trailLifetime(settings);
+    if (textureMode !== 'stretch') out.textureMode = textureMode;
+    if (textureScale !== 1) out.textureScale = textureScale;
+    if (minVertexDistance > 0) out.minVertexDistance = minVertexDistance;
+    if (lifetime !== Infinity) out.lifetime = lifetime;
+    return out;
+}
+
+/** A trail's `followLocalOrigin`, only when on: off is the default. */
+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?: Vector3ArrayJSON} {
+    const axis = settings?.sideAxis;
+    return axis ? {sideAxis: [axis.x, axis.y, axis.z]} : {};
+}
+
+/**
+ * A trail's side axis from JSON `[x, y, z]` (or an object with x, y, z), or nothing: an axis
+ * that is not three finite numbers, or has no length, cannot sweep a ribbon and is dropped with
+ * a warning, so the trail faces the camera instead of vanishing.
+ */
+function trailSideAxisFromJSON(value: unknown): {sideAxis?: Vector3} {
+    if (value === undefined || value === null) {
+        return {};
+    }
+    let x: unknown;
+    let y: unknown;
+    let z: unknown;
+    if (Array.isArray(value)) {
+        [x, y, z] = value;
+    } else if (typeof value === 'object') {
+        ({x, y, z} = value as {x?: unknown; y?: unknown; z?: unknown});
+    }
+    // A number, or a numeric string, as an older file could hold.
+    const component = (v: unknown): number =>
+        typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN;
+    const [nx, ny, nz] = [component(x), component(y), component(z)];
+    if (Number.isFinite(nx) && Number.isFinite(ny) && Number.isFinite(nz) && nx * nx + ny * ny + nz * nz > 0) {
+        return {sideAxis: new Vector3(nx, ny, nz)};
+    }
+    warnFormat(`sideAxis ${JSON.stringify(value)} is not a direction and is ignored`);
+    return {};
+}
+
+/** {@link ParticleSystem.toJSON}: the system's settings, its geometry, material and textures written into the document's meta. */
+export function particleSystemToJSON(
+    system: ParticleSystem,
+    metaData?: BabylonMetaData | string
+): ParticleSystemJSONParameters {
+    const isRootObject = metaData === undefined || typeof metaData === 'string';
+    const meta: BabylonMetaData = isRootObject
+        ? {
+              geometries: {},
+              materials: {},
+              textures: {},
+              images: {},
+              shapes: {},
+              skeletons: {},
+              animations: {},
+              nodes: {},
+          }
+        : metaData;
+
+    const geometryUUID = geometryMeta(system, meta);
+    const materialUUID = materialMeta(system, meta);
+    const rendererSettingsJSON = rendererEmitterSettingsJSON(system);
+
+    // 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 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: EmitterToJSON(system.emitterShape),
+        ...settingsToJSON(system),
+        instancingGeometry: geometryUUID,
+        ...(rendererSettingsJSON ? {rendererEmitterSettings: rendererSettingsJSON} : {}),
+        material: materialUUID,
+        behaviors: system.behaviors.map((b) => BehaviorToJSON(b, system)),
+    };
+}
+
+/**
+ * The constructor parameters {@link ParticleSystem.fromJSON} builds a system from: a setting the file
+ * leaves out takes the constructor's default, and geometry, material and texture uuids are resolved
+ * through `meta`. Behaviors are read by `fromJSON` itself, since they need the system.
+ */
+export function particleSystemParametersFromJSON(
+    json: ParticleSystemJSONParameters,
+    meta: BabylonMetaData,
+    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 ? readFormatPart('shape', () => EmitterFromJSON(json.shape!, meta)) : undefined;
+    let rendererEmitterSettings: RendererEmitterSettings;
+    if (json.renderMode === RenderMode.Trail) {
+        const trailSettings = json.rendererEmitterSettings as TrailSettingsJSON | undefined;
+        rendererEmitterSettings = {
+            startLength:
+                trailSettings?.startLength !== undefined
+                    ? ValueGeneratorFromJSON(trailSettings.startLength)
+                    : new ConstantValue(30),
+            followLocalOrigin: Boolean(trailSettings?.followLocalOrigin),
+            ...trailFlags(trailSettings),
+            ...trailCurve(trailSettings),
+            ...trailSampling(trailSettings),
+            ...trailSideAxisFromJSON(trailSettings?.sideAxis),
+        };
+    } else if (json.renderMode === RenderMode.StretchedBillBoard) {
+        // The render mode says which settings the file holds.
+        const stretched: Partial<StretchedBillBoardSettings> = {
+            ...(json.rendererEmitterSettings as StretchedBillBoardSettings | undefined),
+        };
+        if (json.speedFactor !== undefined) {
+            stretched.speedFactor = json.speedFactor;
+        }
+        rendererEmitterSettings = stretched;
+    } else {
+        rendererEmitterSettings = {};
+    }
+
+    const materialMeta = json.material ? meta.materials?.[json.material] : undefined;
+    // 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;
+    const resolvedGeometryEntry =
+        typeof json.instancingGeometry === 'string'
+            ? meta.geometries?.[json.instancingGeometry]
+            : json.instancingGeometry;
+    const resolvedGeometry = resolveGeometryData(resolvedGeometryEntry);
+
+    const settings = settingsFromJSON(json);
+    return {
+        ...settings,
+        scene,
+        shape,
+        instancingGeometry: resolvedGeometry.positions,
+        instancingIndices: resolvedGeometry.indices,
+        instancingUVs: resolvedGeometry.uvs,
+        instancingUVs2: resolvedGeometry.uvs2,
+        instancingNormals: resolvedGeometry.normals,
+        rendererEmitterSettings,
+        texture,
+        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,
+        depthTest: materialMeta?.depthTest ?? settings.depthTest ?? true,
+        depthWrite: materialMeta?.depthWrite ?? settings.depthWrite ?? false,
+        alphaTest: materialMeta?.alphaTest ?? settings.alphaTest ?? 0,
+        behaviors: [],
+        lighting: materialMeta?.lighting,
+        rim: materialMeta?.rim,
+        mapUV: materialMeta?.mapUV,
+        gradientMap:
+            gradientMeta && typeof gradientMeta === 'object'
+                ? {...gradientMeta, ramp: resolveTexture(gradientMeta.ramp)}
+                : undefined,
+        erosion:
+            erosionMeta && typeof erosionMeta === 'object'
+                ? {...erosionMeta, mask: resolveTexture(erosionMeta.mask)}
+                : undefined,
+        uvDistortion:
+            distortionMeta && typeof distortionMeta === 'object'
+                ? {...distortionMeta, map: resolveTexture(distortionMeta.map)}
+                : undefined,
+    };
+}
+
+/** The render mode's own settings as JSON: a trail's or a stretched billboard's, else none. */
+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.
+        return {
+            startLength: settings.startLength.toJSON(),
+            ...trailFollowLocalOrigin(settings),
+            ...trailFlags(settings),
+            ...trailCurve(settings),
+            ...trailSampling(settings),
+            ...trailSideAxisJSON(settings),
+        };
+    }
+    if (system.renderMode === RenderMode.StretchedBillBoard) {
+        return {
+            speedFactor: (system.rendererEmitterSettings as StretchedBillBoardSettings).speedFactor,
+            lengthFactor: (system.rendererEmitterSettings as StretchedBillBoardSettings).lengthFactor,
+        };
+    }
+    return undefined;
+}
+
+/** Writes the system's geometry into `meta` once per document, and returns its uuid. */
+function geometryMeta(system: ParticleSystem, meta: BabylonMetaData): string {
+    // Systems that share geometry arrays (the default quad, a loaded mesh) share one entry.
+    const rs = system.rendererSettings;
+    const arrays = [
+        rs.instancingGeometry,
+        rs.instancingIndices,
+        rs.instancingUVs,
+        rs.instancingUVs2,
+        rs.instancingNormals,
+    ];
+    let written = serializedGeometries.get(meta);
+    if (written === undefined) {
+        written = [];
+        serializedGeometries.set(meta, written);
+    }
+    const same = written.find((entry) => entry.arrays.every((array, i) => array === arrays[i]));
+    if (same !== undefined) {
+        return same.uuid;
+    }
+    const geometryUUID = nextSerializationId(meta, 'quarks_geometry');
+    written.push({arrays, uuid: geometryUUID});
+    meta.geometries[geometryUUID] = {
+        uuid: geometryUUID,
+        type: 'QuarksGeometry',
+        positions: Array.from(system.rendererSettings.instancingGeometry),
+        indices: Array.from(system.rendererSettings.instancingIndices),
+        uvs: system.rendererSettings.instancingUVs ? Array.from(system.rendererSettings.instancingUVs) : undefined,
+        ...(system.rendererSettings.instancingUVs2 ? {uvs2: Array.from(system.rendererSettings.instancingUVs2)} : {}),
+        normals: system.rendererSettings.instancingNormals
+            ? Array.from(system.rendererSettings.instancingNormals)
+            : undefined,
+    };
+    return geometryUUID;
+}
+
+/** Writes the system's material, and each texture it uses once per document, into `meta`; returns the material's uuid. */
+function materialMeta(system: ParticleSystem, meta: BabylonMetaData): string {
+    // One entry per texture in a document, however many systems and slots use it.
+    let written = serializedTextures.get(meta);
+    if (written === undefined) {
+        written = new Map();
+        serializedTextures.set(meta, written);
+    }
+    const textures = written;
+    const textureRef = (
+        value: BaseTexture | null | undefined,
+        anyKind = false,
+        slot = 'texture'
+    ): string | undefined => {
+        if (!(value instanceof Texture) && !(anyKind && value)) {
+            if (value) {
+                // A RawTexture or a render target has no url a file can point at, so the slot is left
+                // out; silently, the effect would just lose it on reload.
+                console.warn(`[quarks] ${slot} is not a url-backed Texture and is not written to the file`);
+            }
+            return undefined;
+        }
+        let uuid = textures.get(value);
+        if (uuid === undefined) {
+            uuid = nextSerializationId(meta, 'quarks_texture');
+            textures.set(value, uuid);
+            meta.textures[uuid] = value;
+        }
+        return uuid;
+    };
+    const textureUUID = textureRef(system.rendererSettings.texture, true);
+    const reflectionAtlasUUID = textureRef(system.rendererSettings.reflectionAtlas);
+    const erosion = system.erosion;
+    const distortion = system.uvDistortion;
+    const gradientMap = system.gradientMap;
+    const optional = <T>(key: string, value: T | undefined) => (value !== undefined ? {[key]: value} : {});
+
+    const materialUUID = nextSerializationId(meta, 'quarks_material');
+    meta.materials[materialUUID] = {
+        uuid: materialUUID,
+        type: 'QuarksMaterial',
+        transparent: system.rendererSettings.materialTransparent,
+        alphaMode: system.rendererSettings.materialBlendMode,
+        depthTest: system.rendererSettings.materialDepthTest,
+        depthWrite: system.rendererSettings.materialDepthWrite,
+        alphaTest: system.rendererSettings.materialAlphaTest,
+        texture: textureUUID,
+        reflectionAtlas: reflectionAtlasUUID,
+        reflectionLevel: system.rendererSettings.reflectionLevel,
+        // Written only when not the default, so existing effects serialise as before.
+        ...(system.lighting !== 'fixed' ? {lighting: system.lighting} : {}),
+        ...(system.rim ? {rim: {...system.rim, color: [...system.rim.color]}} : {}),
+        ...optional('mapUV', system.mapUV ? textureUVToJSON(system.mapUV) : undefined),
+        ...(gradientMap
+            ? {
+                  gradientMap: {
+                      ramp: textureRef(gradientMap.ramp, false, 'gradientMap.ramp'),
+                      ...(gradientMap.channel !== 'r' ? {channel: gradientMap.channel} : {}),
+                  },
+              }
+            : {}),
+        ...(erosion
+            ? {
+                  erosion: {
+                      ...optional('mask', textureRef(erosion.mask, false, 'erosion.mask')),
+                      ...optional('maskUV', textureUVToJSON(erosion.maskUV)),
+                      // Written only when not the default, like every other setting.
+                      ...(erosion.softness !== EROSION_DEFAULT_SOFTNESS ? {softness: erosion.softness} : {}),
+                      ...(erosion.edgeWidth !== 0 ? {edgeWidth: erosion.edgeWidth} : {}),
+                      ...(erosion.edgeColor.some((c) => c !== 1) ? {edgeColor: [...erosion.edgeColor]} : {}),
+                  },
+              }
+            : {}),
+        ...(distortion
+            ? {
+                  uvDistortion: {
+                      map: textureRef(distortion.map, false, 'uvDistortion.map'),
+                      ...optional('mapUV', textureUVToJSON(distortion.mapUV, UV_DISTORTION_DEFAULT_UV)),
+                      ...(distortion.strength !== UV_DISTORTION_DEFAULT_STRENGTH
+                          ? {strength: distortion.strength}
+                          : {}),
+                  },
+              }
+            : {}),
+        sourceMaterial: system.material ?? undefined,
+    };
+    return materialUUID;
+}