babylon.quarks 0.27.0 → 0.28.0

package/src/QuarksLoader.ts

@@ -8,13 +8,36 @@ 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. */
@@ -35,6 +58,18 @@ export interface QuarksResourceResolver {
     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 {
     /**
@@ -65,6 +100,22 @@ export interface QuarksLoaderOptions {
      * 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}. */
@@ -109,17 +160,60 @@ export interface QuarksBatchLoadOptions extends QuarksLoadOptions {
     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>>>();
 
@@ -139,7 +233,7 @@ const resolvedImageUrls = new WeakMap<object, string>();
 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> = [
@@ -165,27 +259,18 @@ 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';
-    }
-}
+// 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: any): any {
-    if (json === null || typeof json !== 'object') {
+function detachDocument(json: unknown): unknown {
+    if (!isRecord(json)) {
         return json;
     }
-    const copy = {...json};
+    const copy: JSONRecord = {...json};
     if (Array.isArray(json.images)) {
         copy.images = json.images.map((image: unknown) => {
             if (!image || typeof image !== 'object') {
@@ -250,8 +335,8 @@ interface LoadedMeta {
     /** 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};
 }
 
 /**
@@ -292,18 +377,20 @@ export class QuarksLoader {
 
     /**
      * 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
+     * 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, options: QuarksLoadOptions = {}): 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 ?? '';
-        json = detachDocument(json);
-        await untilStopped(this.resolveResources(json, resolvedBase), this.scene, signal);
+        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(json, '');
+        const loaded = this.parseDocument(document, '');
         await this.finishLoad(loaded, signal);
         return loaded.root;
     }
@@ -402,7 +489,7 @@ 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;
@@ -420,7 +507,7 @@ export class QuarksLoader {
      * 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,
@@ -435,15 +522,7 @@ export class QuarksLoader {
      * 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;
-            onResourceError?: QuarksLoaderOptions['onResourceError'];
-        } = {}
-    ): Promise<void> {
+    static async resolveLinkedResources(json: unknown, options: QuarksResolveOptions = {}): Promise<void> {
         const baseUrl = options.baseUrl ?? '';
         const resolver = options.resolver;
         const scene = options.scene;
@@ -457,10 +536,9 @@ export class QuarksLoader {
             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
@@ -468,12 +546,13 @@ export class QuarksLoader {
                 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);
+                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(img.url)) {
+                if (!/^(data|blob):/i.test(url)) {
                     sourceImageUrls.set(img, source);
                 }
             })
@@ -486,7 +565,10 @@ 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);
     }
 
@@ -496,19 +578,41 @@ export class QuarksLoader {
      * 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 {
+    parse(json: unknown, 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') {
+    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) {
-            console.warn(
-                `[QuarksLoader] This effect was written in format ${format}, newer than the ${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.'
             );
         }
@@ -521,27 +625,28 @@ export class QuarksLoader {
             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);
         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;
@@ -561,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().'
                     );
                 }
@@ -578,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;
         }
@@ -611,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));
@@ -681,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;
@@ -692,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(
@@ -702,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);
@@ -759,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++) {
@@ -776,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> {
@@ -784,7 +876,7 @@ export class QuarksLoader {
     }
 
     /** Fetches one effect JSON; documents are not fetch-cached because resolve mutates them. */
-    private async fetchEffectDocument(url: string, signal?: AbortSignal): 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, signal);
@@ -796,7 +888,7 @@ 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;
@@ -816,7 +908,7 @@ export class QuarksLoader {
     }
 
     private async loadResolvedDocuments(
-        docs: Array<{json: any; baseUrl: string} | null>,
+        docs: Array<{json: unknown; baseUrl: string} | null>,
         options: QuarksBatchLoadOptions,
         stopAll: AbortController
     ): Promise<(TransformNode | null)[]> {
@@ -976,31 +1068,32 @@ export class QuarksLoader {
     }
 
     private static async inlineGeometryEntries(
-        json: any,
-        loadGeometry: (url: string) => Promise<any>,
+        json: unknown,
+        loadGeometry: (url: string) => Promise<unknown>,
         onResourceError: QuarksLoaderOptions['onResourceError'] = QuarksLoader.warnResourceError
     ): Promise<void> {
-        const geometries: any[] = Array.isArray(json?.geometries) ? json.geometries : [];
         await Promise.all(
-            geometries
-                .filter((geom) => typeof geom?.url === 'string' && !geom.positions)
-                .map(async (geom) => {
-                    try {
-                        const data = await loadGeometry(geom.url);
-                        // 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) {
-                        onResourceError('geometry', geom.url, err);
+                        geom[key] = Array.isArray(value) ? value.slice() : value;
                     }
-                })
+                    delete geom.url;
+                } catch (err) {
+                    onResourceError('geometry', url, err);
+                }
+            })
         );
     }
 
@@ -1012,17 +1105,18 @@ export class QuarksLoader {
         (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);
+    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.
-            meta.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: string | undefined = sourceImageUrls.get(img) ?? img.url;
+            const source = sourceImageUrls.get(img) ?? url;
             if (source && !/^(data|blob):/i.test(source)) {
                 meta.imageSources[img.uuid] = source;
             }
@@ -1042,15 +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 {
+    private parseTextures(textures: QuarksTextureJSON[], meta: LoadedMeta): void {
         for (const texDef of textures) {
-            const imageUrl = meta.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;
@@ -1105,7 +1199,7 @@ export class QuarksLoader {
                     continue;
                 }
                 textureSettled.set(texture, settled);
-                const source = meta.imageSources[texDef.image];
+                const source = texDef.image !== undefined ? meta.imageSources[texDef.image] : undefined;
                 if (source !== undefined) {
                     setTextureSourceUrl(texture, source, imageUrl);
                 }
@@ -1154,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,
@@ -1171,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;
@@ -1199,20 +1296,20 @@ 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),
                 };
             }
 
@@ -1230,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];
@@ -1250,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) {
@@ -1281,16 +1379,17 @@ export class QuarksLoader {
             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':
@@ -1298,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;
                 }
@@ -1336,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) {
@@ -1367,19 +1467,31 @@ export class QuarksLoader {
         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;
     }
 
@@ -1387,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) {
@@ -1404,14 +1517,19 @@ 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 {
-                        console.warn(
-                            `[QuarksLoader] Emitter "${node.name}" has a mesh surface shape on "${meshSurfaceUUID}", ` +
+                        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.'
                         );
@@ -1420,13 +1538,13 @@ export class QuarksLoader {
                 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
@@ -1434,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.'
                                 );