babylon.quarks 0.19.0 → 0.20.0

package/src/BatchedRenderer.ts

@@ -2,7 +2,7 @@ import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
-import {EmitSubParticleSystem, IParticleSystem} from 'quarks.core';
+import {EmitSubParticleSystem, IParticleSystem, Vector3} from 'quarks.core';
 import {ParticleSystem} from './ParticleSystem';
 import {SpriteBatch} from './SpriteBatch';
 import {TrailBatch} from './TrailBatch';
@@ -47,6 +47,14 @@ export interface VFXBatchSettings {
      */
     reflectionAtlas: BaseTexture | null;
     layerMask: number;
+    /**
+     * Offset of billboard quads from their particle, in particle-size units
+     * (Unity's renderer Pivot). On billboards x/y move the quad in its own plane
+     * before it is rotated and z moves it toward the camera (up for horizontal
+     * billboards). On stretched billboards x runs from the head to the tail and
+     * y across, and z is unused. Absent or zero: no offset. Meshes ignore it.
+     */
+    pivot?: Vector3;
 }
 
 export interface AdaptivePerformanceOptions {
@@ -57,6 +65,11 @@ export interface AdaptivePerformanceOptions {
     increaseStep: number;
 }
 
+/** True when both pivots put the quad in the same place; a missing pivot is zero. */
+function pivotEqual(a: Vector3 | undefined, b: Vector3 | undefined): boolean {
+    return (a?.x ?? 0) === (b?.x ?? 0) && (a?.y ?? 0) === (b?.y ?? 0) && (a?.z ?? 0) === (b?.z ?? 0);
+}
+
 /** True when both face lists are the same six texture references (or both empty). */
 function reflectionFacesEqual(a: BaseTexture[] | null | undefined, b: BaseTexture[] | null | undefined): boolean {
     if (a === b) {
@@ -147,7 +160,8 @@ export class BatchedRenderer extends TransformNode {
             a.vTileCount === b.vTileCount &&
             a.instancingGeometry === b.instancingGeometry &&
             a.renderOrder === b.renderOrder &&
-            a.layerMask === b.layerMask
+            a.layerMask === b.layerMask &&
+            pivotEqual(a.pivot, b.pivot)
         );
     }
 

package/src/MeshSurfaceEmitter.ts

@@ -1,6 +1,6 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
-import {EmitterShape, IParticleSystem, Particle, Plugin, ShapeJSON, Vector3} from 'quarks.core';
+import {EmitterShape, IParticleSystem, Particle, Plugin, ShapeJSON, ShapeTransform, Vector3} from 'quarks.core';
 
 export class MeshSurfaceEmitter implements EmitterShape {
     type = 'mesh_surface';
@@ -10,6 +10,8 @@ export class MeshSurfaceEmitter implements EmitterShape {
     private _positions?: Float32Array;
     private _indices?: Uint32Array | Int32Array;
     private _meshReferenceId?: string;
+    /** Offset, rotation and scale of the mesh within the particle system. */
+    transform?: ShapeTransform;
 
     get mesh() {
         return this._mesh;
@@ -53,8 +55,9 @@ export class MeshSurfaceEmitter implements EmitterShape {
         }
     }
 
-    constructor(mesh?: Mesh, meshReferenceId?: string) {
+    constructor(mesh?: Mesh, meshReferenceId?: string, transform?: ShapeTransform) {
         this._meshReferenceId = meshReferenceId;
+        this.transform = transform;
         if (mesh) this.mesh = mesh;
     }
 
@@ -62,6 +65,7 @@ export class MeshSurfaceEmitter implements EmitterShape {
         if (!this._positions || !this._indices) {
             p.position.set(0, 0, 0);
             p.velocity.set(0, 0, 1).multiplyScalar(p.startSpeed);
+            this.transform?.apply(p);
             return;
         }
 
@@ -107,21 +111,23 @@ export class MeshSurfaceEmitter implements EmitterShape {
         const nz = bx * cy - by * cx;
         const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
         p.velocity.set(nx / len, ny / len, nz / len).multiplyScalar(p.startSpeed);
+        this.transform?.apply(p);
     }
 
     toJSON(): ShapeJSON {
         return {
             type: 'mesh_surface',
             mesh: this._mesh ? (this._mesh as any).uniqueId?.toString() : (this._meshReferenceId ?? ''),
+            ...ShapeTransform.toShapeJSON(this.transform),
         };
     }
 
     static fromJSON(json: any): MeshSurfaceEmitter {
-        return new MeshSurfaceEmitter(undefined, json?.mesh);
+        return new MeshSurfaceEmitter(undefined, json?.mesh, ShapeTransform.fromJSON(json?.transform));
     }
 
     clone(): EmitterShape {
-        return new MeshSurfaceEmitter(this._mesh, this._meshReferenceId);
+        return new MeshSurfaceEmitter(this._mesh, this._meshReferenceId, this.transform?.clone());
     }
 
     update(_system: IParticleSystem, _delta: number): void {}

package/src/ParticleSystem.ts

@@ -38,6 +38,7 @@ import {
     TrailSettings,
     ValueGenerator,
     ValueGeneratorFromJSON,
+    Vector2,
     Vector3,
     Vector3Generator,
     Vector4,
@@ -83,6 +84,16 @@ function fallbackUVsForPositions(positions: Float32Array): Float32Array {
 }
 const DEFAULT_INDICES = new Uint32Array([0, 1, 2, 0, 2, 3]);
 
+/** The optional trail flags that are switched on, so JSON and clones only carry the ones in use. */
+function trailFlags(settings: TrailSettings | undefined): Partial<TrailSettings> {
+    const flags: Partial<TrailSettings> = {};
+    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;
+}
+
 export interface ParticleSystemParameters {
     autoDestroy?: boolean;
     looping?: boolean;
@@ -99,6 +110,8 @@ export interface ParticleSystemParameters {
     emissionOverTime?: ValueGenerator | FunctionValueGenerator;
     emissionOverDistance?: ValueGenerator | FunctionValueGenerator;
     emissionBursts?: Array<BurstParameters>;
+    /** Most particles alive at once; emission past it is dropped. Leave unset for no limit. */
+    maxParticles?: number;
     onlyUsedByOther?: boolean;
     behaviors?: Array<Behavior>;
     instancingGeometry?: Float32Array;
@@ -125,6 +138,10 @@ export interface ParticleSystemParameters {
     depthWrite?: boolean;
     alphaTest?: number;
     layerMask?: number;
+    /** Billboard pivot in particle-size units, see {@link VFXBatchSettings.pivot}. */
+    pivot?: Vector3;
+    /** Fraction of billboard particles mirrored along U (x) and V (y), see {@link ParticleSystem.flip}. */
+    flip?: Vector2;
     scene?: Scene;
 }
 
@@ -152,6 +169,7 @@ export interface ParticleSystemJSONParameters {
     emissionOverTime: FunctionJSON;
     emissionOverDistance: FunctionJSON;
     emissionBursts?: Array<BurstParametersJSON>;
+    maxParticles?: number;
     onlyUsedByOther: boolean;
     rendererEmitterSettings: RendererEmitterSettings;
     instancingGeometry?: any;
@@ -175,6 +193,10 @@ export interface ParticleSystemJSONParameters {
     alphaTest?: number;
     behaviors: Array<any>;
     worldSpace: boolean;
+    /** `[x, y, z]`; written only when non-zero. */
+    pivot?: number[];
+    /** `[u, v]`; written only when non-zero. */
+    flip?: number[];
 }
 
 export interface BabylonMetaData {
@@ -203,9 +225,17 @@ export class ParticleSystem implements IParticleSystem {
     startColor: ColorGenerator | FunctionColorGenerator;
     startTileIndex: ValueGenerator;
     rendererEmitterSettings: RendererEmitterSettings;
+    /**
+     * Fraction of billboard particles mirrored along U (x) and V (y), each
+     * picked at random when the particle is born — Unity's renderer Flip.
+     * Undefined: nothing is mirrored. Meshes ignore it.
+     */
+    flip?: Vector2;
     emissionOverTime: ValueGenerator | FunctionValueGenerator;
     emissionOverDistance: ValueGenerator | FunctionValueGenerator;
     emissionBursts: Array<BurstParameters>;
+    /** Most particles alive at once (Unity's Max Particles); emission past it is dropped. Undefined means no limit. */
+    maxParticles?: number;
     onlyUsedByOther: boolean;
     worldSpace: boolean;
     particleNum: number;
@@ -356,6 +386,28 @@ export class ParticleSystem implements IParticleSystem {
         this.neededToUpdateRender = true;
     }
 
+    /**
+     * Billboard pivot in particle-size units (Unity's renderer Pivot), see
+     * {@link VFXBatchSettings.pivot}. Assign a new vector to change it: editing
+     * the returned one in place does not reach the renderer.
+     */
+    get pivot(): Vector3 | undefined {
+        return this.rendererSettings.pivot;
+    }
+
+    set pivot(v: Vector3 | undefined) {
+        this.rendererSettings.pivot = ParticleSystem.nonZeroPivot(v);
+        this.neededToUpdateRender = true;
+    }
+
+    private static nonZeroPivot(v: Vector3 | undefined): Vector3 | undefined {
+        return v && (v.x !== 0 || v.y !== 0 || v.z !== 0) ? v.clone() : undefined;
+    }
+
+    private static nonZeroFlip(v: Vector2 | undefined): Vector2 | undefined {
+        return v && (v.x > 0 || v.y > 0) ? v.clone() : undefined;
+    }
+
     get softNearFade() {
         return this.rendererSettings.softNearFade;
     }
@@ -468,6 +520,7 @@ export class ParticleSystem implements IParticleSystem {
         this.emissionOverTime = parameters.emissionOverTime ?? new ConstantValue(10);
         this.emissionOverDistance = parameters.emissionOverDistance ?? new ConstantValue(0);
         this.emissionBursts = parameters.emissionBursts ?? [];
+        this.maxParticles = parameters.maxParticles;
         this.onlyUsedByOther = parameters.onlyUsedByOther ?? false;
         this.emitterShape = parameters.shape ?? new SphereEmitter();
         this.behaviors = parameters.behaviors ?? [];
@@ -509,7 +562,9 @@ export class ParticleSystem implements IParticleSystem {
             reflectionFaces: null,
             reflectionAtlas: null,
             layerMask: parameters.layerMask ?? 0x0fffffff,
+            pivot: ParticleSystem.nonZeroPivot(parameters.pivot),
         };
+        this.flip = ParticleSystem.nonZeroFlip(parameters.flip);
         if (this.rendererSettings.renderMode === RenderMode.Mesh && !this.rendererSettings.instancingNormals) {
             this.rendererSettings.instancingNormals = ParticleSystem.createFallbackNormals(
                 this.rendererSettings.instancingGeometry
@@ -724,6 +779,10 @@ export class ParticleSystem implements IParticleSystem {
         const timeRatio = emissionState.time / this.duration;
         const trailSettings = isTrailMode ? (this.rendererEmitterSettings as TrailSettings) : undefined;
         const followLocalOrigin = Boolean(trailSettings?.followLocalOrigin);
+        if (this.maxParticles !== undefined) {
+            // Like Unity, a full system skips the particles it has no room for rather than queueing them.
+            count = Math.min(count, Math.max(0, this.maxParticles - this.particleNum));
+        }
 
         for (let i = 0; i < count; i++) {
             emissionState.burstParticleIndex = i;
@@ -795,6 +854,9 @@ export class ParticleSystem implements IParticleSystem {
                     // Set until a turning behavior says otherwise, so the
                     // renderer never carries a recycled particle's old spin.
                     sprite.angularVelocity = 0;
+                    const flip = this.flip;
+                    sprite.flip =
+                        flip === undefined ? 0 : (Math.random() < flip.x ? 1 : 0) | (Math.random() < flip.y ? 2 : 0);
                 }
             } else if (trailSettings) {
                 const trail = particle as TrailParticle;
@@ -1084,6 +1146,33 @@ export class ParticleSystem implements IParticleSystem {
             }
         }
 
+        // Newborns were snapshotted above with spawn size/color (startSize /
+        // startColor) before SizeOverLife / ColorOverLife ran. That false jump
+        // is then extrapolated by the renderer when simulationResidual is
+        // negative (common with rounded fixed-step) and flashes the start
+        // appearance at the emitter. Collapse it so birth matches t=0 on the
+        // curves. Age is still 0 here — integration below ages them.
+        if (particleCount > 0) {
+            const prevSize = columns.previousSize;
+            const curSize = columns.size;
+            const prevColor = columns.previousColor;
+            const curColor = columns.color;
+            const scalars = columns.scalars;
+            const stride = ParticleStore.SCALAR_STRIDE;
+            for (let i = 0, o3 = 0, o4 = 0, s = 0; i < particleCount; i++, o3 += 3, o4 += 4, s += stride) {
+                if (scalars[s + ParticleStore.AGE] !== 0) {
+                    continue;
+                }
+                prevSize[o3] = curSize[o3];
+                prevSize[o3 + 1] = curSize[o3 + 1];
+                prevSize[o3 + 2] = curSize[o3 + 2];
+                prevColor[o4] = curColor[o4];
+                prevColor[o4 + 1] = curColor[o4 + 1];
+                prevColor[o4 + 2] = curColor[o4 + 2];
+                prevColor[o4 + 3] = curColor[o4 + 3];
+            }
+        }
+
         const followLocalOrigin = isTrailMode && (this.rendererEmitterSettings as TrailSettings).followLocalOrigin;
         if (followLocalOrigin) {
             const emitterMatrix = this.emitter.matrixWorld;
@@ -1114,8 +1203,30 @@ export class ParticleSystem implements IParticleSystem {
         }
 
         if (isTrailMode) {
+            const trailSettings = this.rendererEmitterSettings as TrailSettings;
+            const dieWithParticle = trailSettings.dieWithParticle;
+            // A world-space system records world positions already.
+            const recordWorldSpace = trailSettings.recordWorldSpace && !this.worldSpace;
+            const emitterMatrix = this.emitter.matrixWorld;
             for (let i = 0; i < particleCount; i++) {
-                (particles[i] as TrailParticle).update();
+                const trail = particles[i] as TrailParticle;
+                // Emptying the history lets the removal pass below take the
+                // particle this same step.
+                if (dieWithParticle && trail.age >= trail.life) {
+                    trail.resetHistory();
+                    continue;
+                }
+                trail.update();
+                // update() wrote a sample only while the particle is alive.
+                if (recordWorldSpace && trail.age <= trail.life) {
+                    const offset = ((trail.historyHead + trail.historyCapacity - 1) % trail.historyCapacity) * 3;
+                    const positions = trail.historyPositions;
+                    tempV.set(positions[offset], positions[offset + 1], positions[offset + 2]);
+                    tempV.applyMatrix4(trail.parentMatrix ?? emitterMatrix);
+                    positions[offset] = tempV.x;
+                    positions[offset + 1] = tempV.y;
+                    positions[offset + 2] = tempV.z;
+                }
             }
         }
 
@@ -1281,6 +1392,7 @@ export class ParticleSystem implements IParticleSystem {
                 interval: burst.interval,
                 cycle: burst.cycle,
             })),
+            ...(this.maxParticles !== undefined ? {maxParticles: this.maxParticles} : {}),
             onlyUsedByOther: this.onlyUsedByOther,
             instancingGeometry: geometryUUID,
             renderMode: this.renderMode,
@@ -1302,6 +1414,8 @@ export class ParticleSystem implements IParticleSystem {
             alphaTest: this.rendererSettings.materialAlphaTest,
             behaviors: this.behaviors.map((b) => b.toJSON()),
             worldSpace: this.worldSpace,
+            ...(this.pivot ? {pivot: [this.pivot.x, this.pivot.y, this.pivot.z]} : {}),
+            ...(this.flip ? {flip: [this.flip.x, this.flip.y]} : {}),
         };
     }
 
@@ -1321,6 +1435,7 @@ export class ParticleSystem implements IParticleSystem {
                         ? ValueGeneratorFromJSON(trailSettings.startLength)
                         : new ConstantValue(30),
                 followLocalOrigin: trailSettings?.followLocalOrigin ?? false,
+                ...trailFlags(trailSettings),
             };
         } else if (json.renderMode === RenderMode.StretchedBillBoard) {
             rendererEmitterSettings = {...(json.rendererEmitterSettings ?? {})};
@@ -1371,6 +1486,7 @@ export class ParticleSystem implements IParticleSystem {
                 interval: burst.interval ?? 0.1,
                 cycle: burst.cycle ?? burst.cycleCount ?? 1,
             })),
+            maxParticles: typeof json.maxParticles === 'number' ? json.maxParticles : undefined,
             onlyUsedByOther: json.onlyUsedByOther,
             instancingGeometry: resolvedGeometry.positions,
             instancingIndices: resolvedGeometry.indices,
@@ -1399,6 +1515,8 @@ export class ParticleSystem implements IParticleSystem {
             behaviors: [],
             worldSpace: json.worldSpace,
             layerMask: json.layers,
+            pivot: json.pivot ? new Vector3(json.pivot[0] ?? 0, json.pivot[1] ?? 0, json.pivot[2] ?? 0) : undefined,
+            flip: json.flip ? new Vector2(json.flip[0] ?? 0, json.flip[1] ?? 0) : undefined,
         });
         ps.behaviors = (json.behaviors ?? [])
             .map((behaviorJson) => {
@@ -1432,6 +1550,7 @@ export class ParticleSystem implements IParticleSystem {
             return {
                 startLength: (this.rendererEmitterSettings as TrailSettings).startLength.toJSON(),
                 followLocalOrigin: (this.rendererEmitterSettings as TrailSettings).followLocalOrigin,
+                ...trailFlags(this.rendererEmitterSettings as TrailSettings),
             };
         }
         if (this.renderMode === RenderMode.StretchedBillBoard) {
@@ -1594,6 +1713,7 @@ export class ParticleSystem implements IParticleSystem {
             rendererEmitterSettings = {
                 startLength: (this.rendererEmitterSettings as TrailSettings).startLength.clone(),
                 followLocalOrigin: (this.rendererEmitterSettings as TrailSettings).followLocalOrigin,
+                ...trailFlags(this.rendererEmitterSettings as TrailSettings),
             };
         } else if (this.renderMode === RenderMode.StretchedBillBoard) {
             rendererEmitterSettings = {
@@ -1619,6 +1739,7 @@ export class ParticleSystem implements IParticleSystem {
             emissionOverTime: this.emissionOverTime.clone(),
             emissionOverDistance: this.emissionOverDistance.clone(),
             emissionBursts: this.emissionBursts.map((b) => ({...b})),
+            maxParticles: this.maxParticles,
             onlyUsedByOther: this.onlyUsedByOther,
             instancingGeometry: this.rendererSettings.instancingGeometry,
             instancingIndices: this.rendererSettings.instancingIndices,
@@ -1644,6 +1765,8 @@ export class ParticleSystem implements IParticleSystem {
             depthWrite: this.rendererSettings.materialDepthWrite,
             alphaTest: this.rendererSettings.materialAlphaTest,
             layerMask: this.rendererSettings.layerMask,
+            pivot: this.pivot,
+            flip: this.flip,
             scene: this.emitter.getScene(),
         });
     }

package/src/QuarksLoader.ts

@@ -14,6 +14,15 @@ import {ensureTriangleIndices} from './geometryUtil';
 
 export interface QuarksLoaderOptions {
     baseUrl?: string;
+    /**
+     * Reuse one Texture per scene for every effect that references the same image with the same
+     * sampling, and one copy of the data for identical mesh geometry. The renderer only batches
+     * systems that share the texture (and geometry) object, so without this every loaded effect
+     * gets batches — draw calls and buffer uploads — of its own even when its images are the same
+     * as another effect's. Default true; turn off to give each effect private textures, e.g. to
+     * change one effect's texture settings without touching the others.
+     */
+    shareResources?: boolean;
 }
 
 interface ParsedGeometry {
@@ -23,6 +32,45 @@ interface ParsedGeometry {
     normals?: Float32Array;
 }
 
+/** Textures and geometries reused across loads, per scene. See QuarksLoaderOptions.shareResources. */
+const sharedTextures = new WeakMap<Scene, Map<string, Texture>>();
+const sharedGeometries = new WeakMap<Scene, Map<string, ParsedGeometry>>();
+
+function sceneMap<T>(maps: WeakMap<Scene, Map<string, T>>, scene: Scene): Map<string, T> {
+    let map = maps.get(scene);
+    if (map === undefined) {
+        map = new Map();
+        maps.set(scene, map);
+    }
+    return map;
+}
+
+/** Content key for a geometry: two independent 32-bit hashes over every array's bytes, plus lengths. */
+function geometryKey(geometry: ParsedGeometry): string {
+    let h1 = 0x811c9dc5;
+    let h2 = 0x9e3779b9;
+    const parts: Array<ArrayBufferView | undefined> = [
+        geometry.positions,
+        geometry.indices,
+        geometry.uvs,
+        geometry.normals,
+    ];
+    let lengths = '';
+    for (const part of parts) {
+        if (part === undefined) {
+            lengths += '-,';
+            continue;
+        }
+        const bytes = new Uint8Array(part.buffer, part.byteOffset, part.byteLength);
+        lengths += bytes.length + ',';
+        for (let i = 0; i < bytes.length; i++) {
+            h1 = Math.imul(h1 ^ bytes[i], 0x01000193);
+            h2 = Math.imul(h2 ^ bytes[i], 0x5bd1e995) ^ (h2 >>> 15);
+        }
+    }
+    return `${lengths}${(h1 >>> 0).toString(16)}${(h2 >>> 0).toString(16)}`;
+}
+
 interface LoadedMeta {
     textures: {[uuid: string]: Texture | null};
     geometries: {[uuid: string]: ParsedGeometry};
@@ -42,9 +90,45 @@ export class QuarksLoader {
         const baseUrl = this.options.baseUrl || url.substring(0, url.lastIndexOf('/') + 1);
         const response = await fetch(url);
         const json = await response.json();
+        await QuarksLoader.resolveExternalGeometries(json, async (geometryUrl) => {
+            const geometryResponse = await fetch(QuarksLoader.resolveUrl(baseUrl, geometryUrl));
+            if (!geometryResponse.ok) {
+                throw new Error(`HTTP ${geometryResponse.status}`);
+            }
+            return geometryResponse.json();
+        });
         return this.parse(json, baseUrl);
     }
 
+    /**
+     * Inlines geometries that an export wrote to their own file (`{uuid, type: 'QuarksGeometry',
+     * url}` — e.g. the Unity exporter's "geometries as files"): each `url` is passed to
+     * `loadGeometry`, and the `positions / indices / uvs / normals` it returns replace the url in
+     * place, so `parse()` (which is synchronous) sees an ordinary inline geometry. `load()` does
+     * this with `fetch`; call it yourself before `parse()` when the files come from elsewhere.
+     * A geometry that fails to load is left as is and warned about.
+     */
+    static async resolveExternalGeometries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void> {
+        const geometries: any[] = Array.isArray(json?.geometries) ? json.geometries : [];
+        await Promise.all(
+            geometries
+                .filter((geom) => typeof geom?.url === 'string' && !geom.positions)
+                .map(async (geom) => {
+                    try {
+                        const data = await loadGeometry(geom.url);
+                        for (const key of ['positions', 'indices', 'uvs', 'normals']) {
+                            if (data?.[key] !== undefined) {
+                                geom[key] = data[key];
+                            }
+                        }
+                        delete geom.url;
+                    } catch (err) {
+                        console.warn(`[QuarksLoader] Could not load geometry "${geom.url}":`, err);
+                    }
+                })
+        );
+    }
+
     parse(json: any, baseUrl: string = ''): TransformNode {
         const meta: LoadedMeta = {
             textures: {},
@@ -89,16 +173,47 @@ export class QuarksLoader {
                 const parsed = this.parseBufferGeometry(geom.data);
                 meta.geometries[geom.uuid] = parsed;
             } else if (geom.type === 'QuarksGeometry') {
-                meta.geometries[geom.uuid] = {
+                if (typeof geom.url === 'string' && !geom.positions) {
+                    console.warn(
+                        `[QuarksLoader] Geometry "${geom.url}" is an external file; use load() or ` +
+                            'QuarksLoader.resolveExternalGeometries() before parse().'
+                    );
+                }
+                meta.geometries[geom.uuid] = this.share({
                     positions: new Float32Array(geom.positions ?? []),
                     indices: geom.indices ? new Uint32Array(geom.indices) : new Uint32Array(0),
                     uvs: geom.uvs ? new Float32Array(geom.uvs) : undefined,
                     normals: geom.normals ? new Float32Array(geom.normals) : undefined,
-                };
+                });
             }
         }
     }
 
+    /** The scene's copy of an identical geometry when resources are shared, else `geometry` itself. */
+    private share(geometry: ParsedGeometry): ParsedGeometry {
+        if (this.options.shareResources === false) {
+            return geometry;
+        }
+        const geometries = sceneMap(sharedGeometries, this.scene);
+        const key = geometryKey(geometry);
+        const existing = geometries.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        geometries.set(key, geometry);
+        return geometry;
+    }
+
+    /**
+     * Forgets the textures and geometries shared between loads into `scene` (see
+     * {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep theirs; the next
+     * load creates new ones. Textures are not disposed — they may still be in use.
+     */
+    static clearSharedResources(scene: Scene): void {
+        sharedTextures.delete(scene);
+        sharedGeometries.delete(scene);
+    }
+
     private parseSphereGeometry(geom: any): ParsedGeometry {
         const radius = geom.radius ?? 0.5;
         const widthSegments = Math.max(3, Math.floor(geom.widthSegments ?? 16));
@@ -257,7 +372,7 @@ export class QuarksLoader {
             if (img.url) {
                 QuarksLoader.warnIfNotAnImageUrl(img.url);
             }
-            (this as any)._images[img.uuid] = img.url ? this.resolveImageUrl(baseUrl, img.url) : null;
+            (this as any)._images[img.uuid] = img.url ? QuarksLoader.resolveUrl(baseUrl, img.url) : null;
         }
     }
 
@@ -286,7 +401,7 @@ export class QuarksLoader {
      * babylon.quarks-editor). Prepending baseUrl to those turns e.g.
      * "data:image/png;base64,AAAA" into an invalid path like "/some/dir/data:image/png;base64,AAAA".
      */
-    private resolveImageUrl(baseUrl: string, url: string): string {
+    private static resolveUrl(baseUrl: string, url: string): string {
         if (/^(data|blob):/i.test(url) || /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('/')) {
             return url;
         }
@@ -300,6 +415,28 @@ export class QuarksLoader {
             if (imageUrl) {
                 const invertY = texDef.invertY !== undefined ? !!texDef.invertY : true;
                 const noMipmap = !!texDef.noMipmap;
+                // Everything below that ends up on the Texture object is part of the key, so a
+                // shared texture always looks the way each of its effects asked for.
+                const share = this.options.shareResources !== false;
+                const key = share
+                    ? [
+                          invertY,
+                          noMipmap,
+                          texDef.samplingMode,
+                          texDef.wrap,
+                          texDef.repeat,
+                          texDef.offset,
+                          texDef.rotation,
+                      ].join('|') +
+                      '|' +
+                      imageUrl
+                    : '';
+                const cache = share ? sceneMap(sharedTextures, this.scene) : undefined;
+                const cached = cache?.get(key);
+                if (cached !== undefined) {
+                    meta.textures[texDef.uuid] = cached;
+                    continue;
+                }
                 const texture = new Texture(imageUrl, this.scene, {
                     noMipmap,
                     invertY,
@@ -320,6 +457,15 @@ export class QuarksLoader {
                 if (typeof texDef.rotation === 'number') {
                     texture.wAng = texDef.rotation;
                 }
+                if (cache !== undefined) {
+                    cache.set(key, texture);
+                    // Something outside the library may dispose it; never hand out a dead texture.
+                    texture.onDisposeObservable.addOnce(() => {
+                        if (cache.get(key) === texture) {
+                            cache.delete(key);
+                        }
+                    });
+                }
                 meta.textures[texDef.uuid] = texture;
             } else {
                 meta.textures[texDef.uuid] = null;