babylon.quarks 0.26.0 → 0.28.0

package/src/QuarksLoader.ts

@@ -1,16 +1,44 @@
 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';
 import {VertexData} from '@babylonjs/core/Meshes/mesh.vertexData';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
-import {Behavior, EmitSubParticleSystem} from 'quarks.core';
+import {
+    Behavior,
+    currentFormatPath,
+    EmitSubParticleSystem,
+    QuarksFormatError,
+    readFormat,
+    readFormatPart,
+    warnFormat,
+} from 'quarks.core';
+import {MeshSurfaceEmitter} from './MeshSurfaceEmitter';
 import {ParticleEmitter} from './ParticleEmitter';
 import {ParticleSystem} from './ParticleSystem';
 import {QuarksPrefab} from './QuarksPrefab';
+import type {QuarksNodeJSON, QuarksTextureJSON} from './QuarksSerializer';
+import {QUARKS_FORMAT_VERSION} from './QuarksSerializer';
+import type {
+    BufferAttributeJSON,
+    BufferGeometryDataJSON,
+    EffectDocumentJSON,
+    EffectGeometryJSON,
+    EffectImageJSON,
+    GeometryArrays,
+    MaterialTextureRef,
+    QuarksMaterialJSON,
+    SphereGeometryJSON,
+} from './effectDocumentJSON';
+import {disposeEffect, retainEffectResources} from './effectResources';
 import {ensureTriangleIndices} from './geometryUtil';
+import {fileNodeId, setQuarksNodeId} from './nodeId';
+import type {ParticleSystemJSONParameters} from './system/types';
+import {setTextureSourceUrl} from './textureSource';
 
 /** Kind of linked asset the loader asks a {@link QuarksResourceResolver} to handle. */
 export type QuarksResourceKind = 'effect' | 'geometry' | 'image';
@@ -22,11 +50,32 @@ 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 {@link QuarksLoader.resolveLinkedResources}. */
+export interface QuarksResolveOptions {
+    /** Joined to relative urls. Default `''`. */
+    baseUrl?: string;
+    /** Resolves and fetches the linked files; default: join with `baseUrl` and `fetch`. */
+    resolver?: QuarksResourceResolver;
+    /** Shares the per-scene fetch cache when set. */
+    scene?: Scene;
+    /** Called for a geometry file that fails to load; default: a console warning. */
+    onResourceError?: QuarksLoaderOptions['onResourceError'];
 }
 
+/** 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 +88,50 @@ 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;
+    /**
+     * Called for each part of an effect file that cannot be read as written (an unknown behavior,
+     * shape or curve type, a sub emitter or mesh surface shape whose target is not in the effect, a
+     * newer format), with what was used instead and the part's JSON path, such as
+     * `object.children[2].ps.behaviors[3]`. The effect still loads, with that part at its default.
+     * Default: a console warning that names the path.
+     */
+    onFormatWarning?: (message: string, path: string) => void;
+    /**
+     * Makes a load of a file with a part that cannot be read as written throw a
+     * {@link QuarksFormatError} instead of loading on with a warning: for checks that a set of
+     * assets loads cleanly, such as in CI. The whole effect is read first, so the error's message
+     * names the first such part and its `problems` list them all; what the load built is freed
+     * before it throws. `onFormatWarning` still hears each part. Default false.
+     */
+    strict?: boolean;
+}
+
+/** 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 +142,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.
@@ -71,17 +160,60 @@ export interface QuarksBatchLoadOptions {
     continueOnError?: boolean;
 }
 
-interface ParsedGeometry {
-    positions: Float32Array;
-    indices: Uint32Array | Uint16Array;
-    uvs?: Float32Array;
-    uvs2?: Float32Array;
-    normals?: Float32Array;
+/** An object with fields of unknown types, as a file's JSON may hold anywhere. */
+type JSONRecord = {[key: string]: unknown};
+
+function isRecord(value: unknown): value is JSONRecord {
+    return value !== null && typeof value === 'object';
+}
+
+/**
+ * Whether `value` has the root node an effect document needs. The other parts are checked as they
+ * are read, so a part of the wrong kind warns instead of failing the load.
+ */
+function isEffectDocument(value: unknown): value is EffectDocumentJSON {
+    return isRecord(value) && isRecord(value.object);
+}
+
+/** Whether `value` can be read as a node; its fields are checked as they are read. */
+function isNodeJSON(value: unknown): value is QuarksNodeJSON {
+    return isRecord(value);
+}
+
+/**
+ * The entries of a list in an effect document. A list that is not an array, or an entry that is
+ * not an object, warns and is left out; the fields of each entry are checked as they are read.
+ */
+function documentEntries<T>(list: unknown): T[] {
+    if (!Array.isArray(list)) {
+        warnFormat('This part is not a list; it is skipped.');
+        return [];
+    }
+    const entries: T[] = [];
+    list.forEach((entry: unknown, index) => {
+        if (isRecord(entry)) {
+            entries.push(entry as T);
+        } else {
+            readFormatPart(`[${index}]`, () => warnFormat('This entry is not an object; it is skipped.'));
+        }
+    });
+    return entries;
+}
+
+/** `json[key]` when it is an array, else an empty one. */
+function documentList(json: unknown, key: 'images' | 'geometries'): unknown[] {
+    const list = isRecord(json) ? json[key] : undefined;
+    return Array.isArray(list) ? list : [];
 }
 
+/** The uuid of the mesh each loaded system's mesh surface shape names, until the effect links it. */
+const meshSurfaceLinks = new WeakMap<ParticleSystem, string>();
+/** The JSON path each loaded system was read from, for the warnings of linking it. */
+const systemPaths = new WeakMap<ParticleSystem, string>();
+
 /** 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>>();
+const sharedGeometries = new WeakMap<Scene, Map<string, GeometryArrays>>();
 /** In-flight / completed JSON fetches keyed by `json|resolvedUrl`, per scene. */
 const sharedFetches = new WeakMap<Scene, Map<string, Promise<unknown>>>();
 
@@ -94,8 +226,14 @@ 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 {
+function geometryKey(geometry: GeometryArrays): string {
     let h1 = 0x811c9dc5;
     let h2 = 0x9e3779b9;
     const parts: Array<ArrayBufferView | undefined> = [
@@ -121,12 +259,100 @@ function geometryKey(geometry: ParsedGeometry): string {
     return `${lengths}${(h1 >>> 0).toString(16)}${(h2 >>> 0).toString(16)}`;
 }
 
+// Defined in quarks.core, whose readers throw it in a strict read; exported here as before.
+export {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: unknown): unknown {
+    if (!isRecord(json)) {
+        return json;
+    }
+    const copy: JSONRecord = {...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};
+    geometries: {[uuid: string]: GeometryArrays};
+    materials: {[uuid: string]: QuarksMaterialJSON};
 }
 
+/**
+ * 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;
@@ -136,20 +362,79 @@ 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` is an
+     * {@link EffectDocumentJSON} as parsed from its file; anything else throws
+     * {@link QuarksFormatError}, and a part of the wrong kind warns. `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: unknown, 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);
+        const document = detachDocument(json);
+        await untilStopped(this.resolveResources(document, resolvedBase), this.scene, signal);
+        // The urls are resolved now; joining them with the base again would load `fx/fx/...`.
+        const loaded = this.parseDocument(document, '');
+        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;
+        }
     }
 
     /**
@@ -170,17 +455,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);
     }
 
@@ -200,53 +489,72 @@ export class QuarksLoader {
         entries: Array<QuarksJSONLoadEntry | unknown>,
         options: QuarksBatchLoadOptions = {}
     ): Promise<(TransformNode | null)[]> {
-        const docs: Array<{json: any; baseUrl: string} | null> = entries.map((entry) => {
+        const docs: Array<{json: unknown; 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> {
+    async resolveResources(json: unknown, 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} = {}
-    ): Promise<void> {
+    static async resolveLinkedResources(json: unknown, options: QuarksResolveOptions = {}): 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(
-            images.map(async (img) => {
-                if (typeof img?.url !== 'string' || !img.url) {
+            documentList(json, 'images').map(async (img) => {
+                if (!isRecord(img) || 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;
                 }
-                img.url = await QuarksLoader.resolveWith(resolver, img.url, 'image', baseUrl);
+                const source = img.url;
+                const url = await QuarksLoader.resolveWith(resolver, source, 'image', baseUrl);
+                img.url = url;
+                resolvedImageUrls.set(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(url)) {
+                    sourceImageUrls.set(img, source);
+                }
             })
         );
     }
@@ -257,36 +565,88 @@ export class QuarksLoader {
      * the loader's resolver and fetch cache. Kept for callers that already have a custom
      * `loadGeometry` and no `QuarksLoader` instance.
      */
-    static async resolveExternalGeometries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void> {
+    static async resolveExternalGeometries(
+        json: unknown,
+        loadGeometry: (url: string) => Promise<unknown>
+    ): Promise<void> {
         await QuarksLoader.inlineGeometryEntries(json, loadGeometry);
     }
 
-    parse(json: any, baseUrl: string = ''): TransformNode {
+    /**
+     * 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: unknown, baseUrl: string = ''): TransformNode {
+        return this.parseDocument(json, baseUrl).root;
+    }
+
+    /** {@link parse}, and the textures the effect uses. */
+    private parseDocument(json: unknown, baseUrl: string): {root: TransformNode; textures: Texture[]} {
+        const {strict, onFormatWarning} = this.options;
+        const problems: string[] = [];
+        const onWarning = (message: string, path: string): void => {
+            const located = path ? `${message} (at ${path})` : message;
+            if (strict) problems.push(located);
+            if (onFormatWarning) onFormatWarning(message, path);
+            else if (!strict) console.warn(`[quarks] ${located}`);
+        };
+        const loaded = readFormat({onWarning}, () => this.readDocument(json, baseUrl));
+        if (problems.length > 0) {
+            // The whole effect is read first, so a strict load frees what it built the same way any
+            // other effect is freed, and reports how many parts failed.
+            QuarksLoader.disposeEffect(loaded.root);
+            const more = problems.length > 1 ? ` (and ${problems.length - 1} more)` : '';
+            throw new QuarksFormatError(`${problems[0]}${more}`, problems);
+        }
+        return loaded;
+    }
+
+    /** {@link parseDocument} inside its format read. */
+    private readDocument(document: unknown, baseUrl: string): {root: TransformNode; textures: Texture[]} {
+        if (!isEffectDocument(document)) {
+            throw new QuarksFormatError('[QuarksLoader] Not an effect document: it has no "object" to load.');
+        }
+        const json = document;
+        const format = json.metadata?.quarksFormat;
+        if (typeof format === 'number' && format > QUARKS_FORMAT_VERSION) {
+            warnFormat(
+                `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: {},
         };
 
-        if (json.geometries) {
-            this.parseGeometries(json.geometries, meta);
+        const {geometries, images, textures: textureList, materials} = json;
+        if (geometries) {
+            readFormatPart('geometries', () => this.parseGeometries(documentEntries(geometries), meta));
         }
-        if (json.images) {
-            this.parseImages(json.images, baseUrl, meta);
+        if (images) {
+            readFormatPart('images', () => this.parseImages(documentEntries(images), baseUrl, meta));
         }
-        if (json.textures) {
-            this.parseTextures(json.textures, meta);
+        if (textureList) {
+            readFormatPart('textures', () => this.parseTextures(documentEntries(textureList), meta));
         }
-        if (json.materials) {
-            this.parseMaterials(json.materials, meta);
+        if (materials) {
+            readFormatPart('materials', () => this.parseMaterials(documentEntries(materials), meta));
         }
 
-        const root = this.parseObject(json.object, meta);
+        const root = readFormatPart('object', () => 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 {
+    private parseGeometries(geometries: EffectGeometryJSON[], meta: LoadedMeta): void {
         for (const geom of geometries) {
             if (geom.type === 'PlaneGeometry') {
                 const w = geom.width || 1;
@@ -306,8 +666,8 @@ export class QuarksLoader {
                 meta.geometries[geom.uuid] = parsed;
             } else if (geom.type === 'QuarksGeometry') {
                 if (typeof geom.url === 'string' && !geom.positions) {
-                    console.warn(
-                        `[QuarksLoader] Geometry "${geom.url}" is an external file; use load(), ` +
+                    warnFormat(
+                        `Geometry "${geom.url}" is an external file; use load(), ` +
                             'loadFromJSON(), or resolveResources() before parse().'
                     );
                 }
@@ -323,7 +683,7 @@ export class QuarksLoader {
     }
 
     /** The scene's copy of an identical geometry when resources are shared, else `geometry` itself. */
-    private share(geometry: ParsedGeometry): ParsedGeometry {
+    private share(geometry: GeometryArrays): GeometryArrays {
         if (this.options.shareResources === false) {
             return geometry;
         }
@@ -356,7 +716,7 @@ export class QuarksLoader {
         return baseUrl + url;
     }
 
-    private parseSphereGeometry(geom: any): ParsedGeometry {
+    private parseSphereGeometry(geom: SphereGeometryJSON): GeometryArrays {
         const radius = geom.radius ?? 0.5;
         const widthSegments = Math.max(3, Math.floor(geom.widthSegments ?? 16));
         const heightSegments = Math.max(2, Math.floor(geom.heightSegments ?? 8));
@@ -426,8 +786,8 @@ export class QuarksLoader {
         };
     }
 
-    private parseBufferGeometry(data: any): ParsedGeometry {
-        let positions = new Float32Array(0);
+    private parseBufferGeometry(data: BufferGeometryDataJSON): GeometryArrays {
+        let positions: Float32Array = new Float32Array(0);
         let indices: Uint32Array | Uint16Array = new Uint32Array(0);
         let uvs: Float32Array | undefined;
         let uvs2: Float32Array | undefined;
@@ -437,7 +797,7 @@ export class QuarksLoader {
 
         if (data.interleavedBuffers && data.arrayBuffers) {
             const buffers: {[uuid: string]: {data: Float32Array; stride: number}} = {};
-            for (const [uuid, ibDef] of Object.entries(data.interleavedBuffers) as any[]) {
+            for (const [uuid, ibDef] of Object.entries(data.interleavedBuffers)) {
                 const arrayBuffer = data.arrayBuffers[ibDef.buffer];
                 if (arrayBuffer) {
                     const floatArray = new Float32Array(
@@ -447,35 +807,17 @@ export class QuarksLoader {
                 }
             }
 
-            if (data.attributes) {
-                if (data.attributes.position?.isInterleavedBufferAttribute) {
-                    const attr = data.attributes.position;
-                    const buf = buffers[attr.data];
-                    if (buf)
-                        positions = this.extractInterleavedAttribute(buf.data, buf.stride, attr.offset, attr.itemSize);
-                }
-                if (data.attributes.uv?.isInterleavedBufferAttribute) {
-                    const attr = data.attributes.uv;
-                    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];
-                    if (buf)
-                        normals = this.extractInterleavedAttribute(buf.data, buf.stride, attr.offset, attr.itemSize);
-                }
-            }
+            const readInterleaved = (attr: BufferAttributeJSON | undefined): Float32Array | undefined => {
+                const buf =
+                    attr?.isInterleavedBufferAttribute && attr.data !== undefined ? buffers[attr.data] : undefined;
+                return buf
+                    ? this.extractInterleavedAttribute(buf.data, buf.stride, attr?.offset, attr?.itemSize)
+                    : undefined;
+            };
+            positions = readInterleaved(data.attributes?.position) ?? positions;
+            uvs = readInterleaved(data.attributes?.uv);
+            uvs2 = readInterleaved(uv2Attribute);
+            normals = readInterleaved(data.attributes?.normal);
         } else if (data.attributes) {
             if (data.attributes.position?.array) {
                 positions = new Float32Array(data.attributes.position.array);
@@ -504,7 +846,12 @@ export class QuarksLoader {
         return {positions, indices, uvs, uvs2, normals};
     }
 
-    private extractInterleavedAttribute(buffer: Float32Array, stride: number, offset: number, itemSize: number): any {
+    private extractInterleavedAttribute(
+        buffer: Float32Array,
+        stride: number,
+        offset: number = 0,
+        itemSize: number = 0
+    ): Float32Array {
         const count = Math.floor(buffer.length / stride);
         const result = new Float32Array(count * itemSize);
         for (let i = 0; i < count; i++) {
@@ -521,7 +868,7 @@ export class QuarksLoader {
         for (let i = 0; i < intArray.length; i++) {
             int32View[i] = intArray[i];
         }
-        return new Float32Array(buffer) as any;
+        return new Float32Array(buffer);
     }
 
     private async resolveResourceUrl(url: string, kind: QuarksResourceKind, baseUrl: string): Promise<string> {
@@ -529,10 +876,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: unknown; 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};
     }
 
@@ -541,19 +888,37 @@ export class QuarksLoader {
      * scene fetch cache), then parse. Each index settles exactly once for `onProgress`.
      */
     private async loadDocuments(
-        docs: Array<{json: any; baseUrl: string} | null>,
+        docs: Array<{json: unknown; baseUrl: string} | null>,
         options: QuarksBatchLoadOptions
     ): Promise<(TransformNode | null)[]> {
         const total = docs.length;
         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: unknown; 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;
@@ -562,42 +927,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;
     }
@@ -643,13 +1033,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}`);
             }
@@ -675,40 +1067,59 @@ export class QuarksLoader {
         return pending;
     }
 
-    private static async inlineGeometryEntries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void> {
-        const geometries: any[] = Array.isArray(json?.geometries) ? json.geometries : [];
+    private static async inlineGeometryEntries(
+        json: unknown,
+        loadGeometry: (url: string) => Promise<unknown>,
+        onResourceError: QuarksLoaderOptions['onResourceError'] = QuarksLoader.warnResourceError
+    ): Promise<void> {
         await Promise.all(
-            geometries
-                .filter((geom) => typeof geom?.url === 'string' && !geom.positions)
-                .map(async (geom) => {
-                    try {
-                        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', 'uvs2', 'normals']) {
-                            const value = data?.[key];
-                            if (value === undefined) {
-                                continue;
-                            }
-                            geom[key] = Array.isArray(value) ? value.slice() : value;
+            documentList(json, 'geometries').map(async (geom) => {
+                if (!isRecord(geom) || typeof geom.url !== 'string' || geom.positions) {
+                    return;
+                }
+                const url = geom.url;
+                try {
+                    const data = await loadGeometry(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', 'uvs2', 'normals']) {
+                        const value = isRecord(data) ? data[key] : undefined;
+                        if (value === undefined) {
+                            continue;
                         }
-                        delete geom.url;
-                    } catch (err) {
-                        console.warn(`[QuarksLoader] Could not load geometry "${geom.url}":`, err);
+                        geom[key] = Array.isArray(value) ? value.slice() : value;
                     }
-                })
+                    delete geom.url;
+                } catch (err) {
+                    onResourceError('geometry', url, err);
+                }
+            })
         );
     }
 
-    private parseImages(images: any[], baseUrl: string, _meta: LoadedMeta): void {
-        (this as any)._images = {};
-        for (const img of images) {
-            if (img.url) {
-                QuarksLoader.warnIfNotAnImageUrl(img.url);
+    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: EffectImageJSON[], baseUrl: string, meta: LoadedMeta): void {
+        for (const [index, img] of images.entries()) {
+            const url = img.url;
+            if (url) {
+                readFormatPart(`[${index}]`, () => QuarksLoader.warnIfNotAnImageUrl(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] = url ? QuarksLoader.joinUrl(baseUrl, 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 = sourceImageUrls.get(img) ?? url;
+            if (source && !/^(data|blob):/i.test(source)) {
+                meta.imageSources[img.uuid] = source;
+            }
         }
     }
 
@@ -725,16 +1136,15 @@ export class QuarksLoader {
         if (/^(data|blob):/i.test(url) || /\.(png|jpe?g|webp|gif|bmp|ktx2?|dds|env|basis)(\?|#|$)/i.test(url)) {
             return;
         }
-        console.warn(
-            `[QuarksLoader] Image "${url}" does not look like an image; its texture will fail to load. ` +
+        warnFormat(
+            `Image "${url}" does not look like an image; its texture will fail to load. ` +
                 'This usually means the effect was exported without embedding that texture.'
         );
     }
 
-    private parseTextures(textures: any[], meta: LoadedMeta): void {
-        const images = (this as any)._images || {};
+    private parseTextures(textures: QuarksTextureJSON[], meta: LoadedMeta): void {
         for (const texDef of textures) {
-            const imageUrl = images[texDef.image];
+            const imageUrl = texDef.image !== undefined ? meta.images[texDef.image] : undefined;
             if (imageUrl) {
                 const invertY = texDef.invertY !== undefined ? !!texDef.invertY : true;
                 const noMipmap = !!texDef.noMipmap;
@@ -760,11 +1170,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 = texDef.image !== undefined ? meta.imageSources[texDef.image] : undefined;
+                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]);
@@ -780,7 +1220,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(() => {
@@ -808,9 +1248,12 @@ export class QuarksLoader {
         }
     }
 
-    private parseMaterials(materials: any[], meta: LoadedMeta): void {
+    private parseMaterials(materials: QuarksMaterialJSON[], meta: LoadedMeta): void {
+        // A file names a texture by uuid; anything else in a slot is no texture.
+        const texture = (ref: MaterialTextureRef | undefined): Texture | null =>
+            typeof ref === 'string' ? meta.textures[ref] || null : null;
         for (const matDef of materials) {
-            const matInfo: any = {
+            const matInfo: QuarksMaterialJSON = {
                 uuid: matDef.uuid,
                 transparent: matDef.transparent ?? true,
                 blending: matDef.blending ?? 1,
@@ -825,12 +1268,12 @@ export class QuarksLoader {
             // emits) uses `texture`. Accept both so library-exported effects round-trip.
             const textureRef = matDef.map ?? matDef.texture;
             if (textureRef) {
-                matInfo.texture = meta.textures[textureRef] || null;
+                matInfo.texture = texture(textureRef);
             }
 
             const reflectionAtlasRef = matDef.reflectionAtlas;
             if (reflectionAtlasRef) {
-                matInfo.reflectionAtlas = meta.textures[reflectionAtlasRef] || null;
+                matInfo.reflectionAtlas = texture(reflectionAtlasRef);
             }
             if (typeof matDef.reflectionLevel === 'number') {
                 matInfo.reflectionLevel = matDef.reflectionLevel;
@@ -853,24 +1296,24 @@ export class QuarksLoader {
             if (matDef.gradientMap && typeof matDef.gradientMap === 'object') {
                 matInfo.gradientMap = {
                     ...matDef.gradientMap,
-                    ramp: matDef.gradientMap.ramp ? meta.textures[matDef.gradientMap.ramp] || null : null,
+                    ramp: texture(matDef.gradientMap.ramp),
                 };
             }
             if (matDef.erosion && typeof matDef.erosion === 'object') {
                 matInfo.erosion = {
                     ...matDef.erosion,
-                    mask: matDef.erosion.mask ? meta.textures[matDef.erosion.mask] || null : null,
+                    mask: texture(matDef.erosion.mask),
                 };
             }
             // 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,
+                    map: texture(matDef.uvDistortion.map),
                 };
             }
 
-            // 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)
@@ -884,19 +1327,19 @@ export class QuarksLoader {
                     3: Constants.ALPHA_SUBTRACT,
                     4: Constants.ALPHA_MULTIPLY,
                 };
-                matInfo.alphaMode = blendingToAlphaMode[matDef.blending] || Constants.ALPHA_COMBINE;
+                matInfo.alphaMode = blendingToAlphaMode[matDef.blending ?? 1] || Constants.ALPHA_COMBINE;
             }
 
             meta.materials[matDef.uuid] = matInfo;
         }
     }
 
-    private getGeometry(meta: LoadedMeta, geometryId: string | undefined): ParsedGeometry | undefined {
+    private getGeometry(meta: LoadedMeta, geometryId: string | undefined): GeometryArrays | undefined {
         if (!geometryId) return undefined;
         return meta.geometries[geometryId];
     }
 
-    private getMaterial(meta: LoadedMeta, materialId: string | string[] | undefined): any | undefined {
+    private getMaterial(meta: LoadedMeta, materialId: string | string[] | undefined): QuarksMaterialJSON | undefined {
         if (!materialId) return undefined;
         const selectedId = Array.isArray(materialId) ? materialId[0] : materialId;
         return meta.materials[selectedId];
@@ -904,11 +1347,12 @@ export class QuarksLoader {
 
     private createPlaceholderNode(type: string, name?: string): TransformNode {
         const node = new TransformNode(name || type || 'node', this.scene);
-        (node as any).quarksOriginalType = type;
+        // The three.js type the node stood for, which babylon.quarks has no node for.
+        Object.assign(node, {quarksOriginalType: type});
         return node;
     }
 
-    private createMeshNode(data: any, meta: LoadedMeta): Mesh {
+    private createMeshNode(data: QuarksNodeJSON, meta: LoadedMeta): Mesh {
         const mesh = new Mesh(data.name || data.type || 'mesh', this.scene);
         const geometry = this.getGeometry(meta, data.geometry);
         if (geometry && geometry.positions.length > 0 && geometry.indices.length > 0) {
@@ -930,20 +1374,22 @@ 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;
             material.disableDepthWrite = !(materialInfo.depthWrite ?? false);
-            if (materialInfo.texture) {
-                material.diffuseTexture = materialInfo.texture;
-                material.opacityTexture = materialInfo.texture;
+            const texture = materialInfo.texture;
+            if (texture && typeof texture !== 'string') {
+                material.diffuseTexture = texture;
+                material.opacityTexture = texture;
             }
             mesh.material = material;
         }
         return mesh;
     }
 
-    private parseObject(data: any, meta: LoadedMeta): TransformNode {
+    private parseObject(data: QuarksNodeJSON, meta: LoadedMeta): TransformNode {
         let node: TransformNode;
         switch (data.type) {
             case 'QuarksPrefab':
@@ -951,7 +1397,8 @@ export class QuarksLoader {
                 break;
             case 'ParticleEmitter':
                 if (data.ps) {
-                    const ps = this.parseParticleSystem(data.ps, meta);
+                    const psJSON = data.ps;
+                    const ps = readFormatPart('ps', () => this.parseParticleSystem(psJSON, meta));
                     node = ps.emitter;
                     break;
                 }
@@ -989,7 +1436,7 @@ export class QuarksLoader {
                 node = new TransformNode(data.name || data.type || 'node', this.scene);
         }
 
-        if (data.uuid) (node as any)._quarksUUID = data.uuid;
+        if (data.uuid) setQuarksNodeId(node, data.uuid);
         if (data.name) node.name = data.name;
 
         if (data.matrix) {
@@ -1017,21 +1464,34 @@ 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) {
-                const child = this.parseObject(childData, meta);
-                child.parent = node;
+            const children: unknown = data.children;
+            if (!Array.isArray(children)) {
+                readFormatPart('children', () => warnFormat('"children" is not a list; the node loads without them.'));
+            } else {
+                children.forEach((childData: unknown, index) => {
+                    const child = readFormatPart(`children[${index}]`, () =>
+                        isNodeJSON(childData)
+                            ? this.parseObject(childData, meta)
+                            : warnFormat('A child is not an object; it is skipped.')
+                    );
+                    if (child) child.parent = node;
+                });
             }
         }
 
         return node;
     }
 
-    private parseParticleSystem(json: any, meta: LoadedMeta): ParticleSystem {
+    private parseParticleSystem(json: ParticleSystemJSONParameters, meta: LoadedMeta): ParticleSystem {
         const dependencies: {[uuid: string]: Behavior} = {};
-        const ps = ParticleSystem.fromJSON(json, meta as any, dependencies, this.scene);
-        (ps as any)._meshSurfaceReferenceUUID = json?.shape?.type === 'mesh_surface' ? json?.shape?.mesh : undefined;
+        const ps = ParticleSystem.fromJSON(json, meta, dependencies, this.scene);
+        if (json?.shape?.type === 'mesh_surface' && typeof json.shape.mesh === 'string') {
+            meshSurfaceLinks.set(ps, json.shape.mesh);
+        }
+        systemPaths.set(ps, currentFormatPath());
         return ps;
     }
 
@@ -1039,8 +1499,9 @@ export class QuarksLoader {
         const nodesMap: {[uuid: string]: TransformNode} = {};
 
         const traverse = (node: TransformNode) => {
-            if ((node as any)._quarksUUID) {
-                nodesMap[(node as any)._quarksUUID] = node;
+            const fileId = fileNodeId(node);
+            if (fileId) {
+                nodesMap[fileId] = node;
             }
             for (const child of node.getChildren()) {
                 if (child instanceof TransformNode) {
@@ -1056,23 +1517,34 @@ export class QuarksLoader {
             }
             if (node instanceof ParticleEmitter) {
                 const system = node.system as ParticleSystem;
-                const meshSurfaceUUID = (system as any)._meshSurfaceReferenceUUID;
-                if (meshSurfaceUUID && (system.emitterShape as any).type === 'mesh_surface') {
+                // Links are made once the whole effect is read; a warning names the system's path.
+                const path = systemPaths.get(system);
+                const warnAtSystem = (message: string) =>
+                    path ? readFormatPart(path, () => warnFormat(message)) : warnFormat(message);
+                const meshSurfaceUUID = meshSurfaceLinks.get(system);
+                const shape = system.emitterShape;
+                if (meshSurfaceUUID && shape instanceof MeshSurfaceEmitter) {
                     const targetNode = nodesMap[meshSurfaceUUID];
                     if (targetNode instanceof Mesh) {
-                        (system.emitterShape as any).mesh = targetNode;
+                        shape.mesh = targetNode;
+                    } else {
+                        warnAtSystem(
+                            `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++) {
                     if (system.behaviors[i] instanceof EmitSubParticleSystem) {
                         const subEmitter = system.behaviors[i] as EmitSubParticleSystem;
-                        const targetUUID = subEmitter.subParticleSystem as any;
+                        const targetUUID = subEmitter.subParticleSystem;
                         if (typeof targetUUID !== 'string') {
                             continue;
                         }
                         const resolved = nodesMap[targetUUID];
                         if (resolved instanceof ParticleEmitter) {
-                            (subEmitter as any).subParticleSystem = resolved;
+                            subEmitter.subParticleSystem = resolved;
                             (resolved.system as ParticleSystem).onlyUsedByOther = true;
                         } else {
                             // An export that dropped the target emitter, or kept only
@@ -1080,8 +1552,8 @@ export class QuarksLoader {
                             // a string the behavior would treat as an emitter.
                             subEmitter.subParticleSystem = undefined;
                             if (targetUUID !== '') {
-                                console.warn(
-                                    `[QuarksLoader] Emitter "${node.name}" has a sub emitter targeting "${targetUUID}", ` +
+                                warnAtSystem(
+                                    `Emitter "${node.name}" has a sub emitter targeting "${targetUUID}", ` +
                                         (resolved ? 'which is not a particle emitter' : 'which is not in the effect') +
                                         '; that sub emitter is skipped.'
                                 );