babylon.quarks 0.25.0 → 0.27.0

package/src/QuarksLoader.ts

@@ -1,5 +1,7 @@
 import {Constants} from '@babylonjs/core/Engines/constants';
+import type {ITextureCreationOptions} from '@babylonjs/core/Materials/Textures/texture';
 import {Texture} from '@babylonjs/core/Materials/Textures/texture';
+import type {Material} from '@babylonjs/core/Materials/material';
 import {StandardMaterial} from '@babylonjs/core/Materials/standardMaterial';
 import {Matrix, Quaternion, Vector3} from '@babylonjs/core/Maths/math.vector';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
@@ -10,7 +12,10 @@ import {Behavior, EmitSubParticleSystem} from 'quarks.core';
 import {ParticleEmitter} from './ParticleEmitter';
 import {ParticleSystem} from './ParticleSystem';
 import {QuarksPrefab} from './QuarksPrefab';
+import {QUARKS_FORMAT_VERSION} from './QuarksSerializer';
+import {disposeEffect, retainEffectResources} from './effectResources';
 import {ensureTriangleIndices} from './geometryUtil';
+import {setTextureSourceUrl} from './textureSource';
 
 /** Kind of linked asset the loader asks a {@link QuarksResourceResolver} to handle. */
 export type QuarksResourceKind = 'effect' | 'geometry' | 'image';
@@ -22,11 +27,20 @@ export type QuarksResourceKind = 'effect' | 'geometry' | 'image';
 export interface QuarksResourceResolver {
     /** Resolve a relative url to an absolute / blob / data url. Default: {@link QuarksLoader.joinUrl}. */
     resolve?(url: string, kind: QuarksResourceKind, baseUrl: string): string | Promise<string>;
-    /** Load a JSON asset (geometry files). Default: `fetch(resolvedUrl).json()`. */
-    fetchJson?(resolvedUrl: string): Promise<unknown>;
+    /**
+     * Load a JSON asset (effect and geometry files). Default: `fetch(resolvedUrl).json()`.
+     * `options.signal` is passed for an effect document, whose fetch belongs to one load; geometry
+     * fetches are shared between loads and get none.
+     */
+    fetchJson?(resolvedUrl: string, options?: {signal?: AbortSignal}): Promise<unknown>;
 }
 
+/** Options for a {@link QuarksLoader}, shared by every load it does. */
 export interface QuarksLoaderOptions {
+    /**
+     * Prefix joined to relative geometry and image urls (see {@link QuarksLoader.joinUrl}).
+     * Unset, {@link QuarksLoader.load} uses the effect file's own folder and the other loads `''`.
+     */
     baseUrl?: string;
     /**
      * Reuse one Texture per scene for every effect that references the same image with the same
@@ -39,10 +53,34 @@ export interface QuarksLoaderOptions {
     shareResources?: boolean;
     /** Custom url / fetch backend (File picker, CDN, IndexedDB). */
     resolver?: QuarksResourceResolver;
+    /**
+     * Makes `load`, `loadFromJSON`, `loadAll` and `loadFromJSONAll` resolve only once every texture
+     * the effect uses has loaded or failed, so it does not draw its first frames without them.
+     * A texture a scene with `useDelayedTextureLoading` would load only once drawn is loaded at
+     * once. `parse` never waits. Default false: they resolve when the nodes are built.
+     */
+    waitForTextures?: boolean;
+    /**
+     * Called for a geometry file or image that fails to load. The effect still loads: a geometry
+     * keeps its link unresolved, and a texture draws nothing. Default: a console warning.
+     */
+    onResourceError?: (kind: QuarksResourceKind, url: string, error: unknown) => void;
+}
+
+/** Options for one {@link QuarksLoader.load} or {@link QuarksLoader.loadFromJSON}. */
+export interface QuarksLoadOptions {
+    /**
+     * Cancels the load, e.g. on a level change. The promise rejects with the signal's reason as
+     * soon as it is aborted, and no node of the effect is left in the scene. The effect document's
+     * own fetch is cancelled; a geometry fetch shared with other loads runs on, and its result is
+     * dropped. A scene disposed during the load rejects it the same way.
+     */
+    signal?: AbortSignal;
 }
 
 /** One in-memory effect for {@link QuarksLoader.loadFromJSONAll}. */
 export interface QuarksJSONLoadEntry {
+    /** The effect document, as {@link serializeEffect} or the editor writes it. Left unchanged. */
     json: unknown;
     /** Overrides loader `baseUrl` for relative texture / geometry links in this effect. */
     baseUrl?: string;
@@ -53,7 +91,7 @@ export interface QuarksJSONLoadEntry {
  * Batch loads share the per-scene fetch cache and `shareResources`, so N effects that point at
  * the same `assets/geometries/*.json` or texture only pay for that asset once.
  */
-export interface QuarksBatchLoadOptions {
+export interface QuarksBatchLoadOptions extends QuarksLoadOptions {
     /**
      * Max concurrent effect-document fetches (phase 1). Linked geometry/image resolve still runs
      * across the whole pack in parallel so shared urls coalesce. Default: all at once.
@@ -75,6 +113,7 @@ interface ParsedGeometry {
     positions: Float32Array;
     indices: Uint32Array | Uint16Array;
     uvs?: Float32Array;
+    uvs2?: Float32Array;
     normals?: Float32Array;
 }
 
@@ -93,6 +132,12 @@ function sceneMap<T>(maps: WeakMap<Scene, Map<string, T>>, scene: Scene): Map<st
     return map;
 }
 
+/** Image entries {@link QuarksLoader.resolveLinkedResources} rewrote, with the url it wrote. */
+const resolvedImageUrls = new WeakMap<object, string>();
+
+/** Image entries {@link QuarksLoader.resolveLinkedResources} rewrote, with the url the file had. */
+const sourceImageUrls = new WeakMap<object, string>();
+
 /** 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;
@@ -101,6 +146,7 @@ function geometryKey(geometry: ParsedGeometry): string {
         geometry.positions,
         geometry.indices,
         geometry.uvs,
+        geometry.uvs2,
         geometry.normals,
     ];
     let lengths = '';
@@ -119,12 +165,109 @@ function geometryKey(geometry: ParsedGeometry): string {
     return `${lengths}${(h1 >>> 0).toString(16)}${(h2 >>> 0).toString(16)}`;
 }
 
+/**
+ * Thrown for a document the loader cannot read at all, such as one with no `object`. A part it
+ * cannot read (an unknown behavior, shape or curve type, a missing setting) only warns, and that
+ * part takes its default.
+ */
+export class QuarksFormatError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'QuarksFormatError';
+    }
+}
+
+/**
+ * A copy of an effect document that loading can rewrite (resolved image urls, inlined geometry
+ * files) without touching the caller's. Only the entries that change are copied.
+ */
+function detachDocument(json: any): any {
+    if (json === null || typeof json !== 'object') {
+        return json;
+    }
+    const copy = {...json};
+    if (Array.isArray(json.images)) {
+        copy.images = json.images.map((image: unknown) => {
+            if (!image || typeof image !== 'object') {
+                return image;
+            }
+            const imageCopy: {url?: unknown} = {...(image as object)};
+            // An entry resolveResources() already rewrote stays resolved in its copy, so loading the
+            // document it prepared, with the same base, does not join the base a second time.
+            if (resolvedImageUrls.get(image) === imageCopy.url && typeof imageCopy.url === 'string') {
+                resolvedImageUrls.set(imageCopy, imageCopy.url);
+                const source = sourceImageUrls.get(image);
+                if (source !== undefined) {
+                    sourceImageUrls.set(imageCopy, source);
+                }
+            }
+            return imageCopy;
+        });
+    }
+    if (Array.isArray(json.geometries)) {
+        copy.geometries = json.geometries.map((geometry: unknown) =>
+            geometry && typeof geometry === 'object' ? {...(geometry as object)} : geometry
+        );
+    }
+    return copy;
+}
+
+/** Settles when a texture the loader made has loaded or failed. */
+const textureSettled = new WeakMap<Texture, Promise<void>>();
+
+const abortReason = (signal: AbortSignal) => signal.reason ?? new Error('[QuarksLoader] The load was aborted.');
+const sceneDisposed = () => new Error('[QuarksLoader] The scene was disposed while the effect loaded.');
+
+/** Throws the reason a load stops early: its signal was aborted, or its scene disposed. */
+function checkLoad(scene: Scene, signal: AbortSignal | undefined): void {
+    if (signal?.aborted) {
+        throw abortReason(signal);
+    }
+    if (scene.isDisposed) {
+        throw sceneDisposed();
+    }
+}
+
+/** Follows `promise`, or rejects as {@link checkLoad} would as soon as the load is stopped. */
+function untilStopped<T>(promise: Promise<T>, scene: Scene, signal: AbortSignal | undefined): Promise<T> {
+    checkLoad(scene, signal);
+    return new Promise<T>((resolve, reject) => {
+        const aborted = () => reject(abortReason(signal!));
+        signal?.addEventListener('abort', aborted, {once: true});
+        const disposed = scene.onDisposeObservable.addOnce(() => reject(sceneDisposed()));
+        promise.then(resolve, reject).finally(() => {
+            signal?.removeEventListener('abort', aborted);
+            scene.onDisposeObservable.remove(disposed);
+        });
+    });
+}
+
 interface LoadedMeta {
+    /** The materials this load made, which the effect owns. */
+    ownedMaterials: Material[];
+    /** Image uuid to the url its textures load. */
+    images: {[uuid: string]: string | null};
+    /** Image uuid to the url the file wrote, before any base url was joined. */
+    imageSources: {[uuid: string]: string};
     textures: {[uuid: string]: Texture | null};
     geometries: {[uuid: string]: ParsedGeometry};
     materials: {[uuid: string]: any};
 }
 
+/**
+ * Loads effects saved as JSON into a scene: fetches the document and the geometry and image files
+ * it links, builds the nodes, particle systems, textures and materials, and returns the root.
+ * Add the systems to a {@link BatchedRenderer} with {@link QuarksUtil.addToBatchRenderer} to draw
+ * them, and free the effect with {@link QuarksLoader.disposeEffect}.
+ *
+ * @example
+ * ```ts
+ * const loader = new QuarksLoader(scene, {waitForTextures: true});
+ * const effect = await loader.load('effects/fireball.json');
+ * QuarksUtil.addToBatchRenderer(effect, renderer);
+ * QuarksUtil.play(effect);
+ * ```
+ */
 export class QuarksLoader {
     private scene: Scene;
     private options: QuarksLoaderOptions;
@@ -134,20 +277,77 @@ export class QuarksLoader {
         this.options = options;
     }
 
-    /** Fetches an effect JSON from `url`, resolves linked sources, and parses it. */
-    async load(url: string): Promise<TransformNode> {
-        const {json, baseUrl} = await this.fetchEffectDocument(url);
-        return this.loadFromJSON(json, baseUrl);
+    /**
+     * Fetches an effect JSON from `url`, resolves linked sources, and parses it. Free the effect
+     * with {@link disposeEffect}.
+     */
+    async load(url: string, options: QuarksLoadOptions = {}): Promise<TransformNode> {
+        const {json, baseUrl} = await untilStopped(
+            this.fetchEffectDocument(url, options.signal),
+            this.scene,
+            options.signal
+        );
+        return this.loadFromJSON(json, baseUrl, options);
     }
 
     /**
-     * Resolves linked geometry / image urls on `json` (via {@link resolveResources}) then parses.
-     * Use when the effect JSON is already in hand (File, CDN payload, editor import).
+     * Resolves linked geometry / image urls (via {@link resolveResources}) then parses. Use when
+     * the effect JSON is already in hand (File, CDN payload, editor import). `json` itself is
+     * left as it was, so the same document can be loaded again, into another scene or with
+     * another base url.
      */
-    async loadFromJSON(json: any, baseUrl?: string): Promise<TransformNode> {
+    async loadFromJSON(json: any, baseUrl?: string, options: QuarksLoadOptions = {}): Promise<TransformNode> {
+        const signal = options.signal;
+        checkLoad(this.scene, signal);
         const resolvedBase = baseUrl ?? this.options.baseUrl ?? '';
-        await this.resolveResources(json, resolvedBase);
-        return this.parse(json, resolvedBase);
+        json = detachDocument(json);
+        await untilStopped(this.resolveResources(json, resolvedBase), this.scene, signal);
+        // The urls are resolved now; joining them with the base again would load `fx/fx/...`.
+        const loaded = this.parseDocument(json, '');
+        await this.finishLoad(loaded, signal);
+        return loaded.root;
+    }
+
+    /**
+     * Disposes an effect a loader built: its nodes and systems, the materials made for it, and
+     * each texture it uses once no other loaded effect uses it (textures are shared per scene,
+     * see {@link QuarksLoaderOptions.shareResources}). Copies made with
+     * `QuarksUtil.instantiate` hold the textures too, so disposing the source effect leaves them
+     * drawing. The same happens when the root is disposed any other way (`root.dispose()`, its
+     * parent's dispose, the scene's). The materials and textures are freed even when other code
+     * was handed them; give that code its own. For a root the loader did not build, this is
+     * `root.dispose()`.
+     */
+    static disposeEffect(root: TransformNode): void {
+        disposeEffect(root);
+    }
+
+    /**
+     * Waits for the effect's textures when the loader is asked to, and frees the effect when the
+     * load is stopped meanwhile.
+     */
+    private async finishLoad(loaded: {root: TransformNode; textures: Texture[]}, signal?: AbortSignal): Promise<void> {
+        try {
+            if (this.options.waitForTextures) {
+                for (const texture of loaded.textures) {
+                    // A delayed texture would load only once drawn, which it is not until the load resolves.
+                    if (texture.delayLoadState === Constants.DELAYLOADSTATE_NOTLOADED) {
+                        texture.delayLoad();
+                    }
+                }
+                await untilStopped(
+                    Promise.all(loaded.textures.map((texture) => textureSettled.get(texture))),
+                    this.scene,
+                    signal
+                );
+            }
+            checkLoad(this.scene, signal);
+        } catch (err) {
+            if (!this.scene.isDisposed) {
+                disposeEffect(loaded.root);
+            }
+            throw err;
+        }
     }
 
     /**
@@ -168,17 +368,21 @@ export class QuarksLoader {
         options: QuarksBatchLoadOptions & {continueOnError: true}
     ): Promise<(TransformNode | null)[]>;
     async loadAll(urls: string[], options: QuarksBatchLoadOptions = {}): Promise<(TransformNode | null)[]> {
-        const docs = await QuarksLoader.mapPool(urls, options.concurrency, async (url, index) => {
+        checkLoad(this.scene, options.signal);
+        const fetching = QuarksLoader.mapPool(urls, options.concurrency, async (url, index) => {
+            checkLoad(this.scene, options.signal);
             try {
-                return await this.fetchEffectDocument(url);
+                return await this.fetchEffectDocument(url, options.signal);
             } catch (err) {
-                if (!options.continueOnError) {
+                // A stopped load is never one effect's failure.
+                if (!options.continueOnError || options.signal?.aborted || this.scene.isDisposed) {
                     throw err;
                 }
                 console.warn(`[QuarksLoader] Failed to fetch effect "${url}" (${index + 1}/${urls.length}):`, err);
                 return null;
             }
         });
+        const docs = await untilStopped(fetching, this.scene, options.signal);
         return this.loadDocuments(docs, options);
     }
 
@@ -199,44 +403,59 @@ export class QuarksLoader {
         options: QuarksBatchLoadOptions = {}
     ): Promise<(TransformNode | null)[]> {
         const docs: Array<{json: any; baseUrl: string} | null> = entries.map((entry) => {
+            // Copied, as loadFromJSON does, so the caller's documents stay as they were.
             if (entry !== null && typeof entry === 'object' && 'json' in (entry as object)) {
                 const typed = entry as QuarksJSONLoadEntry;
-                return {json: typed.json as any, baseUrl: typed.baseUrl ?? this.options.baseUrl ?? ''};
+                return {json: detachDocument(typed.json), baseUrl: typed.baseUrl ?? this.options.baseUrl ?? ''};
             }
-            return {json: entry as any, baseUrl: this.options.baseUrl ?? ''};
+            return {json: detachDocument(entry), baseUrl: this.options.baseUrl ?? ''};
         });
         return this.loadDocuments(docs, options);
     }
 
     /**
      * Inlines external geometry files and rewrites relative image urls through the loader's
-     * {@link QuarksResourceResolver}. Idempotent for already-inlined geometries. Failures warn
-     * and leave the entry as is.
+     * {@link QuarksResourceResolver}, in place on `json`. Each document is resolved once:
+     * geometries already inlined and image urls this method already rewrote are left alone, so
+     * loading the same document again does not join its base url twice. Failures warn and leave
+     * the entry as is.
      */
     async resolveResources(json: any, baseUrl: string = ''): Promise<void> {
         await QuarksLoader.resolveLinkedResources(json, {
             baseUrl,
             resolver: this.options.resolver,
             scene: this.scene,
+            onResourceError: this.options.onResourceError,
         });
     }
 
     /**
      * Same as instance {@link resolveResources}, but usable without constructing a loader (e.g.
      * editor import that only prepares JSON). Pass `scene` to share the per-scene fetch cache.
+     * Like it, resolves each document once. A geometry file that fails to load goes to
+     * `onResourceError` (default: a console warning) and keeps its link.
      */
     static async resolveLinkedResources(
         json: any,
-        options: {baseUrl?: string; resolver?: QuarksResourceResolver; scene?: Scene} = {}
+        options: {
+            baseUrl?: string;
+            resolver?: QuarksResourceResolver;
+            scene?: Scene;
+            onResourceError?: QuarksLoaderOptions['onResourceError'];
+        } = {}
     ): Promise<void> {
         const baseUrl = options.baseUrl ?? '';
         const resolver = options.resolver;
         const scene = options.scene;
 
-        await QuarksLoader.inlineGeometryEntries(json, async (geometryUrl) => {
-            const resolved = await QuarksLoader.resolveWith(resolver, geometryUrl, 'geometry', baseUrl);
-            return QuarksLoader.fetchJsonWith(resolver, resolved, scene);
-        });
+        await QuarksLoader.inlineGeometryEntries(
+            json,
+            async (geometryUrl) => {
+                const resolved = await QuarksLoader.resolveWith(resolver, geometryUrl, 'geometry', baseUrl);
+                return QuarksLoader.fetchJsonWith(resolver, resolved, scene);
+            },
+            options.onResourceError
+        );
 
         const images: any[] = Array.isArray(json?.images) ? json.images : [];
         await Promise.all(
@@ -244,7 +463,19 @@ export class QuarksLoader {
                 if (typeof img?.url !== 'string' || !img.url) {
                     return;
                 }
+                // An entry this loader already rewrote keeps its url: resolving the same document
+                // again (a second load, or a fetch cached for several loads) would join it twice.
+                if (resolvedImageUrls.get(img) === img.url) {
+                    return;
+                }
+                const source: string = img.url;
                 img.url = await QuarksLoader.resolveWith(resolver, img.url, 'image', baseUrl);
+                resolvedImageUrls.set(img, img.url);
+                // A resolver that inlined the file (`data:`, `blob:`) made the url the image itself;
+                // the file's path no longer names what the texture holds, so a save writes the url.
+                if (!/^(data|blob):/i.test(img.url)) {
+                    sourceImageUrls.set(img, source);
+                }
             })
         );
     }
@@ -259,8 +490,32 @@ export class QuarksLoader {
         await QuarksLoader.inlineGeometryEntries(json, loadGeometry);
     }
 
+    /**
+     * Builds the node tree of an effect document whose linked files are already inline (see
+     * {@link loadFromJSON}). `baseUrl` is joined to relative image urls. Parts the loader cannot
+     * read warn and take their defaults; a document with no `object` throws
+     * {@link QuarksFormatError}. Free the effect with {@link disposeEffect}.
+     */
     parse(json: any, baseUrl: string = ''): TransformNode {
+        return this.parseDocument(json, baseUrl).root;
+    }
+
+    /** {@link parse}, and the textures the effect uses. */
+    private parseDocument(json: any, baseUrl: string): {root: TransformNode; textures: Texture[]} {
+        if (json === null || typeof json !== 'object' || json.object === null || typeof json.object !== 'object') {
+            throw new QuarksFormatError('[QuarksLoader] Not an effect document: it has no "object" to load.');
+        }
+        const format = json.metadata?.quarksFormat;
+        if (typeof format === 'number' && format > QUARKS_FORMAT_VERSION) {
+            console.warn(
+                `[QuarksLoader] This effect was written in format ${format}, newer than the ${QUARKS_FORMAT_VERSION} ` +
+                    'this version of babylon.quarks reads; settings it does not know are left out.'
+            );
+        }
         const meta: LoadedMeta = {
+            ownedMaterials: [],
+            images: {},
+            imageSources: {},
             textures: {},
             geometries: {},
             materials: {},
@@ -281,7 +536,9 @@ export class QuarksLoader {
 
         const root = this.parseObject(json.object, meta);
         this.linkReferences(root);
-        return root;
+        const textures = [...new Set(Object.values(meta.textures).filter((t): t is Texture => t !== null))];
+        retainEffectResources(root, textures, meta.ownedMaterials);
+        return {root, textures};
     }
 
     private parseGeometries(geometries: any[], meta: LoadedMeta): void {
@@ -313,6 +570,7 @@ export class QuarksLoader {
                     positions: new Float32Array(geom.positions ?? []),
                     indices: geom.indices ? new Uint32Array(geom.indices) : new Uint32Array(0),
                     uvs: geom.uvs ? new Float32Array(geom.uvs) : undefined,
+                    uvs2: geom.uvs2 ? new Float32Array(geom.uvs2) : undefined,
                     normals: geom.normals ? new Float32Array(geom.normals) : undefined,
                 });
             }
@@ -427,7 +685,10 @@ export class QuarksLoader {
         let positions = new Float32Array(0);
         let indices: Uint32Array | Uint16Array = new Uint32Array(0);
         let uvs: Float32Array | undefined;
+        let uvs2: Float32Array | undefined;
         let normals: Float32Array | undefined;
+        // three.js names the second UV set `uv1` (r151 on), `uv2` before.
+        const uv2Attribute = data.attributes?.uv1 ?? data.attributes?.uv2;
 
         if (data.interleavedBuffers && data.arrayBuffers) {
             const buffers: {[uuid: string]: {data: Float32Array; stride: number}} = {};
@@ -453,6 +714,16 @@ export class QuarksLoader {
                     const buf = buffers[attr.data];
                     if (buf) uvs = this.extractInterleavedAttribute(buf.data, buf.stride, attr.offset, attr.itemSize);
                 }
+                if (uv2Attribute?.isInterleavedBufferAttribute) {
+                    const buf = buffers[uv2Attribute.data];
+                    if (buf)
+                        uvs2 = this.extractInterleavedAttribute(
+                            buf.data,
+                            buf.stride,
+                            uv2Attribute.offset,
+                            uv2Attribute.itemSize
+                        );
+                }
                 if (data.attributes.normal?.isInterleavedBufferAttribute) {
                     const attr = data.attributes.normal;
                     const buf = buffers[attr.data];
@@ -467,6 +738,9 @@ export class QuarksLoader {
             if (data.attributes.uv?.array) {
                 uvs = new Float32Array(data.attributes.uv.array);
             }
+            if (uv2Attribute?.array) {
+                uvs2 = new Float32Array(uv2Attribute.array);
+            }
             if (data.attributes.normal?.array) {
                 normals = new Float32Array(data.attributes.normal.array);
             }
@@ -482,7 +756,7 @@ export class QuarksLoader {
 
         indices = ensureTriangleIndices(positions, indices);
 
-        return {positions, indices, uvs, normals};
+        return {positions, indices, uvs, uvs2, normals};
     }
 
     private extractInterleavedAttribute(buffer: Float32Array, stride: number, offset: number, itemSize: number): any {
@@ -510,10 +784,10 @@ export class QuarksLoader {
     }
 
     /** Fetches one effect JSON; documents are not fetch-cached because resolve mutates them. */
-    private async fetchEffectDocument(url: string): Promise<{json: any; baseUrl: string}> {
+    private async fetchEffectDocument(url: string, signal?: AbortSignal): Promise<{json: any; baseUrl: string}> {
         const baseUrl = this.options.baseUrl || url.substring(0, url.lastIndexOf('/') + 1);
         const resolvedEffect = await this.resolveResourceUrl(url, 'effect', baseUrl);
-        const json = await QuarksLoader.fetchJsonWith(this.options.resolver, resolvedEffect, undefined);
+        const json = await QuarksLoader.fetchJsonWith(this.options.resolver, resolvedEffect, undefined, signal);
         return {json, baseUrl};
     }
 
@@ -529,12 +803,30 @@ export class QuarksLoader {
         if (total === 0) {
             return [];
         }
+        checkLoad(this.scene, options.signal);
+        // Stops the whole batch on abort, and the effects still waiting for textures once one fails.
+        const stopAll = new AbortController();
+        const abort = () => stopAll.abort(abortReason(options.signal!));
+        options.signal?.addEventListener('abort', abort, {once: true});
+        try {
+            return await this.loadResolvedDocuments(docs, options, stopAll);
+        } finally {
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
 
-        const results: (TransformNode | null)[] = new Array(total);
+    private async loadResolvedDocuments(
+        docs: Array<{json: any; baseUrl: string} | null>,
+        options: QuarksBatchLoadOptions,
+        stopAll: AbortController
+    ): Promise<(TransformNode | null)[]> {
+        const total = docs.length;
+        const signal = stopAll.signal;
+        const results: (TransformNode | null)[] = new Array(total).fill(null);
         const settled = new Array<boolean>(total).fill(false);
         let done = 0;
         const settle = (index: number, value: TransformNode | null) => {
-            if (settled[index]) {
+            if (settled[index] || signal.aborted) {
                 return;
             }
             settled[index] = true;
@@ -543,42 +835,67 @@ export class QuarksLoader {
             options.onProgress?.(done, total);
         };
 
-        await Promise.all(
-            docs.map(async (doc, i) => {
+        await untilStopped(
+            Promise.all(
+                docs.map(async (doc, i) => {
+                    if (!doc) {
+                        return;
+                    }
+                    try {
+                        await this.resolveResources(doc.json, doc.baseUrl);
+                    } catch (err) {
+                        if (!options.continueOnError) {
+                            throw err;
+                        }
+                        console.warn(`[QuarksLoader] Failed to resolve resources for effect ${i + 1}/${total}:`, err);
+                        docs[i] = null;
+                        settle(i, null);
+                    }
+                })
+            ),
+            this.scene,
+            signal
+        );
+
+        const loaded: Array<{root: TransformNode; textures: Texture[]}> = [];
+        const finishing: Promise<void>[] = [];
+        try {
+            for (let i = 0; i < total; i++) {
+                if (settled[i]) {
+                    continue;
+                }
+                const doc = docs[i];
                 if (!doc) {
-                    return;
+                    settle(i, null);
+                    continue;
                 }
+                let effect: {root: TransformNode; textures: Texture[]};
                 try {
-                    await this.resolveResources(doc.json, doc.baseUrl);
+                    // Resolved above, so the base must not be joined a second time.
+                    effect = this.parseDocument(doc.json, '');
                 } catch (err) {
                     if (!options.continueOnError) {
                         throw err;
                     }
-                    console.warn(`[QuarksLoader] Failed to resolve resources for effect ${i + 1}/${total}:`, err);
-                    docs[i] = null;
+                    console.warn(`[QuarksLoader] Failed to parse effect ${i + 1}/${total}:`, err);
                     settle(i, null);
+                    continue;
                 }
-            })
-        );
-
-        for (let i = 0; i < total; i++) {
-            if (settled[i]) {
-                continue;
+                loaded.push(effect);
+                // An effect counts as loaded once its textures have too, when the loader waits for them.
+                finishing.push(this.finishLoad(effect, signal).then(() => settle(i, effect.root)));
             }
-            const doc = docs[i];
-            if (!doc) {
-                settle(i, null);
-                continue;
+            await Promise.all(finishing);
+        } catch (err) {
+            // One failure, or the load stopped: stop the rest and free every effect already built.
+            if (!signal.aborted) {
+                stopAll.abort(err);
             }
-            try {
-                settle(i, this.parse(doc.json, doc.baseUrl));
-            } catch (err) {
-                if (!options.continueOnError) {
-                    throw err;
-                }
-                console.warn(`[QuarksLoader] Failed to parse effect ${i + 1}/${total}:`, err);
-                settle(i, null);
+            void Promise.allSettled(finishing);
+            if (!this.scene.isDisposed) {
+                loaded.forEach((effect) => disposeEffect(effect.root));
             }
+            throw err;
         }
         return results;
     }
@@ -624,13 +941,15 @@ export class QuarksLoader {
     private static fetchJsonWith(
         resolver: QuarksResourceResolver | undefined,
         resolvedUrl: string,
-        scene: Scene | undefined
+        scene: Scene | undefined,
+        signal?: AbortSignal
     ): Promise<unknown> {
         const load = async () => {
             if (resolver?.fetchJson) {
-                return resolver.fetchJson(resolvedUrl);
+                return signal ? resolver.fetchJson(resolvedUrl, {signal}) : resolver.fetchJson(resolvedUrl);
             }
-            const response = await fetch(resolvedUrl);
+            // Only an uncached fetch (an effect document) can be cancelled: a cached one is shared.
+            const response = await (signal ? fetch(resolvedUrl, {signal}) : fetch(resolvedUrl));
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }
@@ -656,7 +975,11 @@ export class QuarksLoader {
         return pending;
     }
 
-    private static async inlineGeometryEntries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void> {
+    private static async inlineGeometryEntries(
+        json: any,
+        loadGeometry: (url: string) => Promise<any>,
+        onResourceError: QuarksLoaderOptions['onResourceError'] = QuarksLoader.warnResourceError
+    ): Promise<void> {
         const geometries: any[] = Array.isArray(json?.geometries) ? json.geometries : [];
         await Promise.all(
             geometries
@@ -666,7 +989,7 @@ export class QuarksLoader {
                         const data = await loadGeometry(geom.url);
                         // Copy arrays so a shared fetch-cache document is not aliased across
                         // effects — mutating one effect's inlined geometry must not corrupt others.
-                        for (const key of ['positions', 'indices', 'uvs', 'normals']) {
+                        for (const key of ['positions', 'indices', 'uvs', 'uvs2', 'normals']) {
                             const value = data?.[key];
                             if (value === undefined) {
                                 continue;
@@ -675,21 +998,34 @@ export class QuarksLoader {
                         }
                         delete geom.url;
                     } catch (err) {
-                        console.warn(`[QuarksLoader] Could not load geometry "${geom.url}":`, err);
+                        onResourceError('geometry', geom.url, err);
                     }
                 })
         );
     }
 
-    private parseImages(images: any[], baseUrl: string, _meta: LoadedMeta): void {
-        (this as any)._images = {};
+    private static warnResourceError(kind: QuarksResourceKind, url: string, error: unknown): void {
+        console.warn(`[QuarksLoader] Could not load ${kind} "${url}":`, error);
+    }
+
+    private reportResourceError(kind: QuarksResourceKind, url: string, error: unknown): void {
+        (this.options.onResourceError ?? QuarksLoader.warnResourceError)(kind, url, error);
+    }
+
+    private parseImages(images: any[], baseUrl: string, meta: LoadedMeta): void {
         for (const img of images) {
             if (img.url) {
                 QuarksLoader.warnIfNotAnImageUrl(img.url);
             }
             // Urls are usually already absolute after resolveResources; joinUrl is a no-op for
             // data/blob/http(s) and still supports callers that use parse() with a baseUrl only.
-            (this as any)._images[img.uuid] = img.url ? QuarksLoader.joinUrl(baseUrl, img.url) : null;
+            meta.images[img.uuid] = img.url ? QuarksLoader.joinUrl(baseUrl, img.url) : null;
+            // The url the file wrote, for serializeEffect to write back. An inlined image
+            // (`data:`, `blob:`) has no path to write; its texture writes its url.
+            const source: string | undefined = sourceImageUrls.get(img) ?? img.url;
+            if (source && !/^(data|blob):/i.test(source)) {
+                meta.imageSources[img.uuid] = source;
+            }
         }
     }
 
@@ -713,9 +1049,8 @@ export class QuarksLoader {
     }
 
     private parseTextures(textures: any[], meta: LoadedMeta): void {
-        const images = (this as any)._images || {};
         for (const texDef of textures) {
-            const imageUrl = images[texDef.image];
+            const imageUrl = meta.images[texDef.image];
             if (imageUrl) {
                 const invertY = texDef.invertY !== undefined ? !!texDef.invertY : true;
                 const noMipmap = !!texDef.noMipmap;
@@ -741,11 +1076,41 @@ export class QuarksLoader {
                     meta.textures[texDef.uuid] = cached;
                     continue;
                 }
-                const texture = new Texture(imageUrl, this.scene, {
+                let settle!: () => void;
+                const settled = new Promise<void>((resolve) => (settle = resolve));
+                let failed = false;
+                // Babylon calls onError from inside the constructor, before `texture` is assigned, and
+                // then throws, when the engine cannot make the texture at all.
+                let texture: Texture | undefined = undefined;
+                const options: ITextureCreationOptions = {
                     noMipmap,
                     invertY,
                     samplingMode: typeof texDef.samplingMode === 'number' ? texDef.samplingMode : undefined,
-                });
+                    onLoad: () => settle(),
+                    onError: (message, exception) => {
+                        failed = true;
+                        // A later load tries the image again rather than reuse the failed texture.
+                        if (cache !== undefined && cache.get(key) === texture) {
+                            cache.delete(key);
+                        }
+                        this.reportResourceError('image', imageUrl, exception ?? message);
+                        settle();
+                    },
+                };
+                try {
+                    texture = new Texture(imageUrl, this.scene, options);
+                } catch {
+                    // Reported through onError: the effect draws without this texture.
+                    meta.textures[texDef.uuid] = null;
+                    continue;
+                }
+                textureSettled.set(texture, settled);
+                const source = meta.imageSources[texDef.image];
+                if (source !== undefined) {
+                    setTextureSourceUrl(texture, source, imageUrl);
+                }
+                // A texture disposed before it loads never will.
+                texture.onDisposeObservable.addOnce(() => settle());
                 if (Array.isArray(texDef.wrap)) {
                     texture.wrapU = this.mapWrapMode(texDef.wrap[0]);
                     texture.wrapV = this.mapWrapMode(texDef.wrap[1] ?? texDef.wrap[0]);
@@ -761,7 +1126,7 @@ export class QuarksLoader {
                 if (typeof texDef.rotation === 'number') {
                     texture.wAng = texDef.rotation;
                 }
-                if (cache !== undefined) {
+                if (cache !== undefined && !failed) {
                     cache.set(key, texture);
                     // Something outside the library may dispose it; never hand out a dead texture.
                     texture.onDisposeObservable.addOnce(() => {
@@ -824,13 +1189,18 @@ export class QuarksLoader {
             if (matDef.rim && typeof matDef.rim === 'object') {
                 matInfo.rim = matDef.rim;
             }
-            // Texture effects (QuarksMaterial): uvScroll [u, v], gradientMap texture uuid,
-            // erosion {mask (texture uuid), softness, edgeWidth, edgeColor, maskScroll}.
-            if (Array.isArray(matDef.uvScroll)) {
-                matInfo.uvScroll = matDef.uvScroll;
+            // Texture effects (QuarksMaterial): mapUV {channel, tiling, offset, scroll},
+            // gradientMap {ramp (texture uuid), channel},
+            // erosion {mask (texture uuid), maskUV {channel, tiling, offset, scroll}, softness, edgeWidth,
+            // edgeColor}.
+            if (matDef.mapUV && typeof matDef.mapUV === 'object') {
+                matInfo.mapUV = matDef.mapUV;
             }
-            if (matDef.gradientMap) {
-                matInfo.gradientMap = meta.textures[matDef.gradientMap] || null;
+            if (matDef.gradientMap && typeof matDef.gradientMap === 'object') {
+                matInfo.gradientMap = {
+                    ...matDef.gradientMap,
+                    ramp: matDef.gradientMap.ramp ? meta.textures[matDef.gradientMap.ramp] || null : null,
+                };
             }
             if (matDef.erosion && typeof matDef.erosion === 'object') {
                 matInfo.erosion = {
@@ -838,8 +1208,15 @@ export class QuarksLoader {
                     mask: matDef.erosion.mask ? meta.textures[matDef.erosion.mask] || null : null,
                 };
             }
+            // uvDistortion {map (texture uuid), mapUV {channel, tiling, offset, scroll}, strength}.
+            if (matDef.uvDistortion && typeof matDef.uvDistortion === 'object') {
+                matInfo.uvDistortion = {
+                    ...matDef.uvDistortion,
+                    map: matDef.uvDistortion.map ? meta.textures[matDef.uvDistortion.map] || null : null,
+                };
+            }
 
-            // QuarksMaterial (what ParticleSystem.ensureMaterialMeta emits) writes `alphaMode`
+            // QuarksMaterial (what `materialMeta` in system/serialization.ts writes) writes `alphaMode`
             // directly as a Babylon alpha-mode constant; three.js materials (MeshBasicMaterial
             // etc.) instead use `blending` with three.js's own 1..4 numbering, which does NOT
             // line up with Babylon's constants (e.g. three.js Additive=2 vs Babylon ALPHA_ADD=1)
@@ -887,6 +1264,9 @@ export class QuarksLoader {
             if (geometry.uvs && geometry.uvs.length > 0) {
                 vertexData.uvs = geometry.uvs;
             }
+            if (geometry.uvs2 && geometry.uvs2.length > 0) {
+                vertexData.uvs2 = geometry.uvs2;
+            }
             if (geometry.normals && geometry.normals.length > 0) {
                 vertexData.normals = geometry.normals;
             }
@@ -896,6 +1276,7 @@ export class QuarksLoader {
         const materialInfo = this.getMaterial(meta, data.material);
         if (materialInfo) {
             const material = new StandardMaterial(`quarks_loader_material_${materialInfo.uuid}`, this.scene);
+            meta.ownedMaterials.push(material);
             material.alphaMode = materialInfo.alphaMode ?? Constants.ALPHA_COMBINE;
             material.backFaceCulling = materialInfo.side !== 2;
             material.alphaCutOff = materialInfo.alphaTest ?? 0;
@@ -983,6 +1364,7 @@ export class QuarksLoader {
         }
 
         if (data.visible !== undefined) node.setEnabled(data.visible);
+        if (data.isVisible === false && node instanceof Mesh) node.isVisible = false;
 
         if (data.children) {
             for (const childData of data.children) {
@@ -1027,6 +1409,12 @@ export class QuarksLoader {
                     const targetNode = nodesMap[meshSurfaceUUID];
                     if (targetNode instanceof Mesh) {
                         (system.emitterShape as any).mesh = targetNode;
+                    } else {
+                        console.warn(
+                            `[QuarksLoader] Emitter "${node.name}" has a mesh surface shape on "${meshSurfaceUUID}", ` +
+                                (targetNode ? 'which is not a mesh' : 'which is not in the effect') +
+                                '; it emits nothing until a mesh is set.'
+                        );
                     }
                 }
                 for (let i = 0; i < system.behaviors.length; i++) {