babylon.quarks 0.27.0 → 0.29.0

package/src/system/geometry.ts

@@ -1,3 +1,4 @@
+import type {BufferGeometryDataJSON, GeometryArrays, GeometryEntry} from '../effectDocumentJSON';
 import {ensureTriangleIndices} from '../geometryUtil';
 
 /** Positions of the unit quad billboards are drawn with, and the default mesh. */
@@ -47,19 +48,19 @@ export function isFallbackNormals(normals: Float32Array | undefined, positions:
     return normals !== undefined && normals === fallbackNormals.get(positions);
 }
 
+/** `values` as a Float32Array: itself when it is one, else a copy. */
+function floats(values: number[] | Float32Array | undefined): Float32Array | undefined {
+    return values ? (values instanceof Float32Array ? values : new Float32Array(values)) : undefined;
+}
+
 /**
  * Typed arrays from a geometry entry of an effect document: quarks' own `{positions, indices, uvs,
- * uvs2, normals}`, or a three.js `BufferGeometry` JSON. Anything else gives the default quad.
+ * uvs2, normals}`, or a three.js `BufferGeometry` JSON or its `data`. Anything else gives the
+ * default quad.
  */
-export function resolveGeometryData(entry: any): {
-    positions: Float32Array;
-    indices: Uint32Array | Uint16Array;
-    uvs?: Float32Array;
-    uvs2?: Float32Array;
-    normals?: Float32Array;
-} {
-    if (entry?.positions) {
-        const positions = entry.positions instanceof Float32Array ? entry.positions : new Float32Array(entry.positions);
+export function resolveGeometryData(entry: GeometryEntry | BufferGeometryDataJSON | undefined): GeometryArrays {
+    if (entry && 'positions' in entry && entry.positions) {
+        const positions = floats(entry.positions)!;
         const rawIndices =
             entry.indices instanceof Uint16Array || entry.indices instanceof Uint32Array
                 ? entry.indices
@@ -69,23 +70,17 @@ export function resolveGeometryData(entry: any): {
         return {
             positions,
             indices: ensureTriangleIndices(positions, rawIndices),
-            uvs: entry.uvs ? (entry.uvs instanceof Float32Array ? entry.uvs : new Float32Array(entry.uvs)) : undefined,
-            uvs2: entry.uvs2
-                ? entry.uvs2 instanceof Float32Array
-                    ? entry.uvs2
-                    : new Float32Array(entry.uvs2)
-                : undefined,
-            normals: entry.normals
-                ? entry.normals instanceof Float32Array
-                    ? entry.normals
-                    : new Float32Array(entry.normals)
-                : undefined,
+            uvs: floats(entry.uvs),
+            uvs2: floats(entry.uvs2),
+            normals: floats(entry.normals),
         };
     }
 
-    const data = entry?.data ?? entry;
-    if (data?.attributes?.position?.array) {
-        const positions = new Float32Array(data.attributes.position.array);
+    const data = entry && 'data' in entry ? entry.data : entry;
+    const attributes = data && 'attributes' in data ? data.attributes : undefined;
+    const position = attributes?.position?.array;
+    if (data && 'attributes' in data && attributes && position) {
+        const positions = new Float32Array(position);
         let indices: Uint32Array | Uint16Array | undefined;
         if (data.index?.array) {
             const indexType = data.index.type === 'Uint16Array' ? Uint16Array : Uint32Array;
@@ -94,12 +89,10 @@ export function resolveGeometryData(entry: any): {
         return {
             positions,
             indices: ensureTriangleIndices(positions, indices),
-            uvs: data.attributes.uv?.array ? new Float32Array(data.attributes.uv.array) : undefined,
+            uvs: floats(attributes.uv?.array),
             // three.js names the second set `uv1` (r151 on), `uv2` before.
-            uvs2: (data.attributes.uv1 ?? data.attributes.uv2)?.array
-                ? new Float32Array((data.attributes.uv1 ?? data.attributes.uv2).array)
-                : undefined,
-            normals: data.attributes.normal?.array ? new Float32Array(data.attributes.normal.array) : undefined,
+            uvs2: floats((attributes.uv1 ?? attributes.uv2)?.array),
+            normals: floats(attributes.normal?.array),
         };
     }
 

package/src/system/integrate.ts

@@ -129,6 +129,34 @@ function retire(particles: Particle[], store: ParticleStore, i: number, last: nu
     return particle;
 }
 
+/**
+ * What a ring buffer does to a particle at the end of its life (see `RingBufferMode`): `pause`
+ * holds it frozen at its end, else it goes back to `loopStart` (a fraction of its life) once it
+ * reaches `loopEnd`.
+ */
+export interface RingBufferStep {
+    /** Freeze at the end of life rather than loop. */
+    pause: boolean;
+    /** Where a looping particle goes back to, a fraction of its life, 0 to 1. */
+    loopStart: number;
+    /**
+     * Where a looping particle goes back from, a fraction of its life, `loopStart` to 1. Equal to
+     * `loopStart`, the particle is held there.
+     */
+    loopEnd: number;
+}
+
+/** The least age a held particle keeps, as a fraction of its life: past 0, a newborn's age. */
+const HELD_AGE = 1e-6;
+
+/**
+ * The age a looping ring particle is held at, or Infinity when it loops: a loop range of no
+ * length holds it at that point of its life, as a pause does at the end.
+ */
+function holdAge(ring: RingBufferStep, life: number): number {
+    return ring.loopEnd > ring.loopStart ? Infinity : Math.max(ring.loopEnd, HELD_AGE) * life;
+}
+
 /**
  * The sprite path's step after the behaviors, as one pass over the columns that does three
  * things, none of which touches a particle object until a death. Returns the live count.
@@ -142,7 +170,8 @@ function retire(particles: Particle[], store: ParticleStore, i: number, last: nu
  * Position is integrated along the velocity.
  *
  * A particle whose age reached its life is swapped with the last live one, rows included. The
- * survivor moved into the slot has not been visited yet, so the slot is processed again.
+ * survivor moved into the slot has not been visited yet, so the slot is processed again. With a
+ * `ring` buffer no particle dies: it is frozen at the end of its life, or sent back into it.
  *
  * The bounds fall out of the same pass. Measuring every particle on every step costs about as
  * much as the integration itself, so the full measurement runs every few steps; in between,
@@ -158,9 +187,11 @@ export function integrateSprites(
     collapseColor: boolean,
     bounds: BoundsTracker,
     settings: BoundsSettings,
-    onDied: DeathListener | undefined
+    onDied: DeathListener | undefined,
+    ring?: RingBufferStep
 ): number {
     const scalars = store.scalars;
+    const pause = ring !== undefined && ring.pause;
     const stride = ParticleStore.SCALAR_STRIDE;
     const positions = store.position;
     const velocities = store.velocity;
@@ -198,7 +229,12 @@ export function integrateSprites(
                 prevColor[o4 + 3] = curColor[o4 + 3];
             }
         }
-        const step = delta * scalars[scalar + ParticleStore.SPEED_MODIFIER];
+        const life = scalars[scalar + ParticleStore.LIFE];
+        // Frozen until a newborn replaces it, no motion and no ageing: at the end of its life when
+        // paused, or at a loop range of no length, held a hair past 0 so Birth fires only once.
+        const hold = ring === undefined ? Infinity : pause ? life : holdAge(ring, life);
+        const frozen = age >= hold;
+        const step = frozen ? 0 : delta * scalars[scalar + ParticleStore.SPEED_MODIFIER];
         const vx = velocities[offset];
         const vy = velocities[offset + 1];
         const vz = velocities[offset + 2];
@@ -219,10 +255,31 @@ export function integrateSprites(
         }
         // Speed is tracked every step: it bounds how far the particles
         // can have moved since the last measurement.
+        if (frozen) {
+            continue;
+        }
         maxSpeedSq = Math.max(maxSpeedSq, vx * vx + vy * vy + vz * vz);
         age += delta;
         scalars[scalar + ParticleStore.AGE] = age;
-        if (age >= scalars[scalar + ParticleStore.LIFE]) {
+        if (ring !== undefined) {
+            if (age > hold) {
+                scalars[scalar + ParticleStore.AGE] = hold;
+            } else if (!pause && hold === Infinity && age >= ring.loopEnd * life) {
+                const loopStart = ring.loopStart * life;
+                const wrapped = loopStart + ((age - ring.loopEnd * life) % ((ring.loopEnd - ring.loopStart) * life));
+                // Never exactly 0, which is a newborn's age: Birth sub emitters would fire again.
+                scalars[scalar + ParticleStore.AGE] = wrapped > 0 ? wrapped : HELD_AGE * life;
+                // The jump back is not motion: the renderer must not extrapolate size or colour across it.
+                prevSize[offset] = curSize[offset];
+                prevSize[offset + 1] = curSize[offset + 1];
+                prevSize[offset + 2] = curSize[offset + 2];
+                const o4 = i * 4;
+                prevColor[o4] = curColor[o4];
+                prevColor[o4 + 1] = curColor[o4 + 1];
+                prevColor[o4 + 2] = curColor[o4 + 2];
+                prevColor[o4 + 3] = curColor[o4 + 3];
+            }
+        } else if (age >= life) {
             const particle = retire(particles, store, i, liveParticleCount - 1);
             liveParticleCount--;
             i--;

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,6 +1,6 @@
 import {ConstantValue, FunctionValueGenerator, ValueGenerator, Vector2, Vector3} from 'quarks.core';
-import type {MeshLighting, SortMode} from '../VFXBatch';
-import type {BurstParameters, CullingMode} from './types';
+import type {MeshLighting, RenderFace, SortMode} from '../batchSettings';
+import type {BurstParameters, CullingMode, RingBufferMode, ScalingMode, StopAction} 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.
@@ -15,11 +15,43 @@ 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';
 }
 
+/** `action` if it is one of the stop actions, else `'none'`. */
+export function validStopAction(action: unknown): StopAction {
+    return action === 'disable' || action === 'destroy' ? action : 'none';
+}
+
+/** `mode` if it is one of the ring buffer modes, else `'disabled'`. */
+export function validRingBufferMode(mode: unknown): RingBufferMode {
+    return mode === 'pauseUntilReplaced' || mode === 'loopUntilReplaced' ? mode : 'disabled';
+}
+
+/**
+ * A ring buffer loop range within 0..1, start no later than end; a missing or non-finite bound
+ * takes its default (0 or 1).
+ */
+export function validLoopRange(range: {x: number; y: number} | undefined): Vector2 {
+    const clamp = (value: number | undefined, fallback: number) =>
+        typeof value === 'number' && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : fallback;
+    const start = clamp(range?.x, 0);
+    const end = clamp(range?.y, 1);
+    return new Vector2(Math.min(start, end), Math.max(start, end));
+}
+
+/** `mode` if it is one of the scaling modes, else `'local'`. */
+export function validScalingMode(mode: unknown): ScalingMode {
+    return mode === 'hierarchy' || mode === 'shape' ? mode : 'local';
+}
+
 /** `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;

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;
     };