babylon.quarks 0.20.0 → 0.21.0

package/dist/types/index.d.ts

@@ -3535,6 +3535,18 @@ declare class ParticleSystem implements IParticleSystem {
     clone(): ParticleSystem;
 }
 
+/** Kind of linked asset the loader asks a {@link QuarksResourceResolver} to handle. */
+type QuarksResourceKind = 'effect' | 'geometry' | 'image';
+/**
+ * Hooks for resolving relative source links (textures, geometry files) and loading their JSON.
+ * Omit either method to keep the default (`baseUrl` join / `fetch`).
+ */
+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>;
+}
 interface QuarksLoaderOptions {
     baseUrl?: string;
     /**
@@ -3546,19 +3558,96 @@ interface QuarksLoaderOptions {
      * change one effect's texture settings without touching the others.
      */
     shareResources?: boolean;
+    /** Custom url / fetch backend (File picker, CDN, IndexedDB). */
+    resolver?: QuarksResourceResolver;
+}
+/** One in-memory effect for {@link QuarksLoader.loadFromJSONAll}. */
+interface QuarksJSONLoadEntry {
+    json: unknown;
+    /** Overrides loader `baseUrl` for relative texture / geometry links in this effect. */
+    baseUrl?: string;
+}
+/**
+ * Options for {@link QuarksLoader.loadAll} / {@link QuarksLoader.loadFromJSONAll}.
+ * 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.
+ */
+interface QuarksBatchLoadOptions {
+    /**
+     * 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.
+     */
+    concurrency?: number;
+    /**
+     * Called once per effect when it has fully settled (parsed successfully, or failed under
+     * `continueOnError`). `done` is how many of `total` have settled so far.
+     */
+    onProgress?: (done: number, total: number) => void;
+    /**
+     * When true, a failed effect becomes `null` in the result array and the rest keep loading.
+     * When false (default), the first failure rejects the whole batch.
+     */
+    continueOnError?: boolean;
 }
 declare class QuarksLoader {
     private scene;
     private options;
     constructor(scene: Scene, options?: QuarksLoaderOptions);
+    /** Fetches an effect JSON from `url`, resolves linked sources, and parses it. */
     load(url: string): Promise<TransformNode>;
+    /**
+     * 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).
+     */
+    loadFromJSON(json: any, baseUrl?: string): Promise<TransformNode>;
+    /**
+     * Loads many effects in parallel for battle / level preload. Phase 1 fetches every effect
+     * JSON (optionally concurrency-limited); phase 2 resolves all linked geometries/images across
+     * the pack together so shared asset urls hit the fetch cache once; phase 3 parses.
+     *
+     * @example
+     * ```ts
+     * const roots = await loader.loadAll([
+     *   'fx/hit.json', 'fx/explosion.json', 'fx/heal.json',
+     * ], { concurrency: 6, continueOnError: true });
+     * ```
+     */
+    loadAll(urls: string[], options?: QuarksBatchLoadOptions & {
+        continueOnError?: false;
+    }): Promise<TransformNode[]>;
+    loadAll(urls: string[], options: QuarksBatchLoadOptions & {
+        continueOnError: true;
+    }): Promise<(TransformNode | null)[]>;
+    /**
+     * Same two-phase batch as {@link loadAll}, but effect JSON is already in memory (asset pack,
+     * IndexedDB, editor). Entries may be bare JSON or `{ json, baseUrl }`.
+     */
+    loadFromJSONAll(entries: Array<QuarksJSONLoadEntry | unknown>, options?: QuarksBatchLoadOptions & {
+        continueOnError?: false;
+    }): Promise<TransformNode[]>;
+    loadFromJSONAll(entries: Array<QuarksJSONLoadEntry | unknown>, options: QuarksBatchLoadOptions & {
+        continueOnError: true;
+    }): Promise<(TransformNode | null)[]>;
+    /**
+     * 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.
+     */
+    resolveResources(json: any, baseUrl?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    static resolveLinkedResources(json: any, options?: {
+        baseUrl?: string;
+        resolver?: QuarksResourceResolver;
+        scene?: Scene;
+    }): Promise<void>;
     /**
      * Inlines geometries that an export wrote to their own file (`{uuid, type: 'QuarksGeometry',
-     * url}` — e.g. the Unity exporter's "geometries as files"): each `url` is passed to
-     * `loadGeometry`, and the `positions / indices / uvs / normals` it returns replace the url in
-     * place, so `parse()` (which is synchronous) sees an ordinary inline geometry. `load()` does
-     * this with `fetch`; call it yourself before `parse()` when the files come from elsewhere.
-     * A geometry that fails to load is left as is and warned about.
+     * url}`). Prefer {@link load}, {@link loadFromJSON}, or {@link resolveResources} — those use
+     * the loader's resolver and fetch cache. Kept for callers that already have a custom
+     * `loadGeometry` and no `QuarksLoader` instance.
      */
     static resolveExternalGeometries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void>;
     parse(json: any, baseUrl?: string): TransformNode;
@@ -3566,15 +3655,31 @@ declare class QuarksLoader {
     /** The scene's copy of an identical geometry when resources are shared, else `geometry` itself. */
     private share;
     /**
-     * Forgets the textures and geometries shared between loads into `scene` (see
-     * {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep theirs; the next
-     * load creates new ones. Textures are not disposed — they may still be in use.
+     * Forgets the textures, geometries, and in-flight JSON fetches shared between loads into
+     * `scene` (see {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep
+     * theirs; the next load creates new ones. Textures are not disposed — they may still be in use.
      */
     static clearSharedResources(scene: Scene): void;
+    /** Joins `baseUrl` with a relative `url`; leaves data/blob/absolute/root-absolute urls alone. */
+    static joinUrl(baseUrl: string, url: string): string;
     private parseSphereGeometry;
     private parseBufferGeometry;
     private extractInterleavedAttribute;
     private int32ArrayToFloat32;
+    private resolveResourceUrl;
+    /** Fetches one effect JSON; documents are not fetch-cached because resolve mutates them. */
+    private fetchEffectDocument;
+    /**
+     * Resolve every document's linked resources in parallel (shared urls coalesce via the
+     * scene fetch cache), then parse. Each index settles exactly once for `onProgress`.
+     */
+    private loadDocuments;
+    /** Runs `fn` over `items` with at most `concurrency` in flight (or all if unset/≤0). */
+    private static mapPool;
+    private static resolveWith;
+    /** One in-flight fetch per scene + resolved url when `scene` is set; otherwise uncached. */
+    private static fetchJsonWith;
+    private static inlineGeometryEntries;
     private parseImages;
     /**
      * Flags an image entry that is plainly not an image, which otherwise only
@@ -3586,13 +3691,6 @@ declare class QuarksLoader {
      * file backs.
      */
     private static warnIfNotAnImageUrl;
-    /**
-     * `img.url` is already absolute for data/blob URIs and full http(s) URLs — common for
-     * "portable" exports that embed textures as base64 (see ensurePortableTextureUrl in
-     * babylon.quarks-editor). Prepending baseUrl to those turns e.g.
-     * "data:image/png;base64,AAAA" into an invalid path like "/some/dir/data:image/png;base64,AAAA".
-     */
-    private static resolveUrl;
     private parseTextures;
     private mapWrapMode;
     private parseMaterials;
@@ -3828,4 +3926,4 @@ declare class TrailBatch extends VFXBatch {
 }
 
 export { ApplyCollision, ApplyForce, ApplySequences, AxisAngleGenerator, BatchedParticleRenderer, BatchedRenderer, BehaviorFromJSON, BehaviorTypes, Bezier, BoxEmitFrom, BoxEmitter, ChangeEmitDirection, CircleEmitter, ColorBySpeed, ColorGeneratorFromJSON, ColorOverLife, ColorRange, ConeEmitter, ConstantColor, ConstantValue, DEG2RAD, DonutEmitter, EdgeEmitter, EmitSubParticleSystem, EmitterFromJSON, EmitterMode, EmitterShapes, Euler, EulerGenerator, ForceOverLife, FrameOverLife, GeneratorFromJSON, Gradient, GravityForce, GridEmitter, HemisphereEmitter, InheritVelocity, IntervalValue, LimitSpeedOverLife, MathUtils, Matrix3, Matrix4, MeshSurfaceEmitter, MeshSurfaceEmitterPlugin, NodeParticle, Noise, OrbitOverLife, ParticleEmitter, ParticleMeshPhysicsMaterial, ParticleMeshStandardMaterial, ParticleStore, ParticleSystem, PiecewiseBezier, PiecewiseFunction, Plugins, PointEmitter, QuarksLoader, QuarksPrefab, QuarksUtil, Quaternion, RAD2DEG, RandomColor, RandomColorBetweenGradient, RandomQuatGenerator, RecordState, RectangleEmitter, RenderMode, Rotation3DOverLife, RotationBySpeed, RotationGeneratorFromJSON, RotationOverLife, SequencerFromJSON, ShapeTransform, SizeBySpeed, SizeOverLife, SpeedOverLife, SphereEmitter, SpriteBatch, SpriteParticle, SubParticleEmitMode, TextureSequencer, TrailBatch, TrailParticle, TurbulenceField, VFXBatch, ValueGeneratorFromJSON, Vector2, Vector3, Vector3Function, Vector3GeneratorFromJSON, Vector3View, Vector4, Vector4View, VelocityOverLife, WebGLCoordinateSystem, WebGPUCoordinateSystem, WidthOverLength, cacheEnvAtlas, ceilPowerOfTwo, clamp, createEnvAtlasFromFaceUrls, cubeFaceUrls, damp, degToRad, denormalize, ensureEnvAtlasFromCube, euclideanModulo, floorPowerOfTwo, generateUUID, getCachedEnvAtlas, getPhysicsResolver, getRegisteredShaderChunks, getShaderChunk, getValueFromEmitterMode, inverseLerp, isPowerOfTwo, lerp, loadPlugin, _default$7 as localParticlePhysicsVertShader, _default$6 as localParticleVertShader, mapLinear, normalize, _default$5 as particleFragShader, _default$4 as particlePhysicsFragShader, _default$3 as particleVertShader, pingpong, planBehaviorFusion, radToDeg, randFloat, randFloatSpread, randInt, registerShaderChunks, seededRandom, setPhysicsResolver, setQuaternionFromProperEuler, smootherstep, smoothstep, _default$2 as stretchedBillboardVertShader, _default$1 as trailFragShader, _default as trailVertShader, unloadPlugin };
-export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, DonutEmitterParameters, EdgeEmitterParameters, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshSettings, ParameterPair, ParameterType, Particle, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksLoaderOptions, QuarksTimelineClip, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, TrailSettings, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };
+export type { AdaptivePerformanceOptions, AdaptivePerformanceState, AnimationData, BabylonMetaData, BabylonParticleMaterialParameters, Behavior, BehaviorPlugin, BillBoardSettings, BoxEmitterParameters, BurstParameters, BurstParametersJSON, CircleEmitterParameters, ColorGenerator, ConeEmitterParameters, Constructable, DonutEmitterParameters, EdgeEmitterParameters, EmissionState, EmitterShape, EmitterShapePlugin, EulerOrder, FieldType, FunctionColorGenerator, FunctionJSON, FunctionValueGenerator, FusedPass, FusionStep, GeneratorMemory, GridEmitterParameters, HemisphereEmitterParameters, IAnimationData, IEmitter, IParticle, IParticleSystem, IPrefab, InheritVelocityMode, JsonMetaData, MeshSettings, ParameterPair, ParameterType, Particle, ParticleSystemEvent, ParticleSystemEventType, ParticleSystemJSONParameters, ParticleSystemParameters, Plugin, QuarksBatchLoadOptions, QuarksJSONLoadEntry, QuarksLoaderOptions, QuarksResourceKind, QuarksResourceResolver, QuarksTimelineClip, RectangleEmitterParameters, RendererEmitterSettings, Resource, RotationGenerator, Sequencer, SerializationOptions, ShapeJSON, ShapeTransformJSON, SphereEmitterParameters, StoredBatchSettings, StretchedBillBoardSettings, TrailSettings, VFXBatchSettings, ValueGenerator, Vector3Generator, VelocityOverLifeSpace };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.20.0",
+    "version": "0.21.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",

package/src/QuarksLoader.ts

@@ -12,6 +12,20 @@ import {ParticleSystem} from './ParticleSystem';
 import {QuarksPrefab} from './QuarksPrefab';
 import {ensureTriangleIndices} from './geometryUtil';
 
+/** Kind of linked asset the loader asks a {@link QuarksResourceResolver} to handle. */
+export type QuarksResourceKind = 'effect' | 'geometry' | 'image';
+
+/**
+ * Hooks for resolving relative source links (textures, geometry files) and loading their JSON.
+ * Omit either method to keep the default (`baseUrl` join / `fetch`).
+ */
+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>;
+}
+
 export interface QuarksLoaderOptions {
     baseUrl?: string;
     /**
@@ -23,6 +37,38 @@ export interface QuarksLoaderOptions {
      * change one effect's texture settings without touching the others.
      */
     shareResources?: boolean;
+    /** Custom url / fetch backend (File picker, CDN, IndexedDB). */
+    resolver?: QuarksResourceResolver;
+}
+
+/** One in-memory effect for {@link QuarksLoader.loadFromJSONAll}. */
+export interface QuarksJSONLoadEntry {
+    json: unknown;
+    /** Overrides loader `baseUrl` for relative texture / geometry links in this effect. */
+    baseUrl?: string;
+}
+
+/**
+ * Options for {@link QuarksLoader.loadAll} / {@link QuarksLoader.loadFromJSONAll}.
+ * 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 {
+    /**
+     * 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.
+     */
+    concurrency?: number;
+    /**
+     * Called once per effect when it has fully settled (parsed successfully, or failed under
+     * `continueOnError`). `done` is how many of `total` have settled so far.
+     */
+    onProgress?: (done: number, total: number) => void;
+    /**
+     * When true, a failed effect becomes `null` in the result array and the rest keep loading.
+     * When false (default), the first failure rejects the whole batch.
+     */
+    continueOnError?: boolean;
 }
 
 interface ParsedGeometry {
@@ -35,6 +81,8 @@ interface ParsedGeometry {
 /** 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>>();
+/** In-flight / completed JSON fetches keyed by `json|resolvedUrl`, per scene. */
+const sharedFetches = new WeakMap<Scene, Map<string, Promise<unknown>>>();
 
 function sceneMap<T>(maps: WeakMap<Scene, Map<string, T>>, scene: Scene): Map<string, T> {
     let map = maps.get(scene);
@@ -86,49 +134,131 @@ 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 baseUrl = this.options.baseUrl || url.substring(0, url.lastIndexOf('/') + 1);
-        const response = await fetch(url);
-        const json = await response.json();
-        await QuarksLoader.resolveExternalGeometries(json, async (geometryUrl) => {
-            const geometryResponse = await fetch(QuarksLoader.resolveUrl(baseUrl, geometryUrl));
-            if (!geometryResponse.ok) {
-                throw new Error(`HTTP ${geometryResponse.status}`);
-            }
-            return geometryResponse.json();
+        const {json, baseUrl} = await this.fetchEffectDocument(url);
+        return this.loadFromJSON(json, baseUrl);
+    }
+
+    /**
+     * 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).
+     */
+    async loadFromJSON(json: any, baseUrl?: string): Promise<TransformNode> {
+        const resolvedBase = baseUrl ?? this.options.baseUrl ?? '';
+        await this.resolveResources(json, resolvedBase);
+        return this.parse(json, resolvedBase);
+    }
+
+    /**
+     * Loads many effects in parallel for battle / level preload. Phase 1 fetches every effect
+     * JSON (optionally concurrency-limited); phase 2 resolves all linked geometries/images across
+     * the pack together so shared asset urls hit the fetch cache once; phase 3 parses.
+     *
+     * @example
+     * ```ts
+     * const roots = await loader.loadAll([
+     *   'fx/hit.json', 'fx/explosion.json', 'fx/heal.json',
+     * ], { concurrency: 6, continueOnError: true });
+     * ```
+     */
+    loadAll(urls: string[], options?: QuarksBatchLoadOptions & {continueOnError?: false}): Promise<TransformNode[]>;
+    loadAll(
+        urls: string[],
+        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) => {
+            try {
+                return await this.fetchEffectDocument(url);
+            } catch (err) {
+                if (!options.continueOnError) {
+                    throw err;
+                }
+                console.warn(`[QuarksLoader] Failed to fetch effect "${url}" (${index + 1}/${urls.length}):`, err);
+                return null;
+            }
         });
-        return this.parse(json, baseUrl);
+        return this.loadDocuments(docs, options);
     }
 
     /**
-     * Inlines geometries that an export wrote to their own file (`{uuid, type: 'QuarksGeometry',
-     * url}` — e.g. the Unity exporter's "geometries as files"): each `url` is passed to
-     * `loadGeometry`, and the `positions / indices / uvs / normals` it returns replace the url in
-     * place, so `parse()` (which is synchronous) sees an ordinary inline geometry. `load()` does
-     * this with `fetch`; call it yourself before `parse()` when the files come from elsewhere.
-     * A geometry that fails to load is left as is and warned about.
+     * Same two-phase batch as {@link loadAll}, but effect JSON is already in memory (asset pack,
+     * IndexedDB, editor). Entries may be bare JSON or `{ json, baseUrl }`.
      */
-    static async resolveExternalGeometries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void> {
-        const geometries: any[] = Array.isArray(json?.geometries) ? json.geometries : [];
+    loadFromJSONAll(
+        entries: Array<QuarksJSONLoadEntry | unknown>,
+        options?: QuarksBatchLoadOptions & {continueOnError?: false}
+    ): Promise<TransformNode[]>;
+    loadFromJSONAll(
+        entries: Array<QuarksJSONLoadEntry | unknown>,
+        options: QuarksBatchLoadOptions & {continueOnError: true}
+    ): Promise<(TransformNode | null)[]>;
+    async loadFromJSONAll(
+        entries: Array<QuarksJSONLoadEntry | unknown>,
+        options: QuarksBatchLoadOptions = {}
+    ): Promise<(TransformNode | null)[]> {
+        const docs: Array<{json: any; baseUrl: string} | null> = entries.map((entry) => {
+            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: entry as any, 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.
+     */
+    async resolveResources(json: any, baseUrl: string = ''): Promise<void> {
+        await QuarksLoader.resolveLinkedResources(json, {
+            baseUrl,
+            resolver: this.options.resolver,
+            scene: this.scene,
+        });
+    }
+
+    /**
+     * 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.
+     */
+    static async resolveLinkedResources(
+        json: any,
+        options: {baseUrl?: string; resolver?: QuarksResourceResolver; scene?: Scene} = {}
+    ): 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);
+        });
+
+        const images: any[] = Array.isArray(json?.images) ? json.images : [];
         await Promise.all(
-            geometries
-                .filter((geom) => typeof geom?.url === 'string' && !geom.positions)
-                .map(async (geom) => {
-                    try {
-                        const data = await loadGeometry(geom.url);
-                        for (const key of ['positions', 'indices', 'uvs', 'normals']) {
-                            if (data?.[key] !== undefined) {
-                                geom[key] = data[key];
-                            }
-                        }
-                        delete geom.url;
-                    } catch (err) {
-                        console.warn(`[QuarksLoader] Could not load geometry "${geom.url}":`, err);
-                    }
-                })
+            images.map(async (img) => {
+                if (typeof img?.url !== 'string' || !img.url) {
+                    return;
+                }
+                img.url = await QuarksLoader.resolveWith(resolver, img.url, 'image', baseUrl);
+            })
         );
     }
 
+    /**
+     * Inlines geometries that an export wrote to their own file (`{uuid, type: 'QuarksGeometry',
+     * url}`). Prefer {@link load}, {@link loadFromJSON}, or {@link resolveResources} — those use
+     * 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> {
+        await QuarksLoader.inlineGeometryEntries(json, loadGeometry);
+    }
+
     parse(json: any, baseUrl: string = ''): TransformNode {
         const meta: LoadedMeta = {
             textures: {},
@@ -175,8 +305,8 @@ export class QuarksLoader {
             } else if (geom.type === 'QuarksGeometry') {
                 if (typeof geom.url === 'string' && !geom.positions) {
                     console.warn(
-                        `[QuarksLoader] Geometry "${geom.url}" is an external file; use load() or ` +
-                            'QuarksLoader.resolveExternalGeometries() before parse().'
+                        `[QuarksLoader] Geometry "${geom.url}" is an external file; use load(), ` +
+                            'loadFromJSON(), or resolveResources() before parse().'
                     );
                 }
                 meta.geometries[geom.uuid] = this.share({
@@ -205,13 +335,22 @@ export class QuarksLoader {
     }
 
     /**
-     * Forgets the textures and geometries shared between loads into `scene` (see
-     * {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep theirs; the next
-     * load creates new ones. Textures are not disposed — they may still be in use.
+     * Forgets the textures, geometries, and in-flight JSON fetches shared between loads into
+     * `scene` (see {@link QuarksLoaderOptions.shareResources}). Effects already loaded keep
+     * theirs; the next load creates new ones. Textures are not disposed — they may still be in use.
      */
     static clearSharedResources(scene: Scene): void {
         sharedTextures.delete(scene);
         sharedGeometries.delete(scene);
+        sharedFetches.delete(scene);
+    }
+
+    /** Joins `baseUrl` with a relative `url`; leaves data/blob/absolute/root-absolute urls alone. */
+    static joinUrl(baseUrl: string, url: string): string {
+        if (/^(data|blob):/i.test(url) || /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('/')) {
+            return url;
+        }
+        return baseUrl + url;
     }
 
     private parseSphereGeometry(geom: any): ParsedGeometry {
@@ -366,13 +505,191 @@ export class QuarksLoader {
         return new Float32Array(buffer) as any;
     }
 
+    private async resolveResourceUrl(url: string, kind: QuarksResourceKind, baseUrl: string): Promise<string> {
+        return QuarksLoader.resolveWith(this.options.resolver, url, kind, baseUrl);
+    }
+
+    /** Fetches one effect JSON; documents are not fetch-cached because resolve mutates them. */
+    private async fetchEffectDocument(url: string): Promise<{json: any; baseUrl: string}> {
+        const baseUrl = this.options.baseUrl || url.substring(0, url.lastIndexOf('/') + 1);
+        const resolvedEffect = await this.resolveResourceUrl(url, 'effect', baseUrl);
+        const json = await QuarksLoader.fetchJsonWith(this.options.resolver, resolvedEffect, undefined);
+        return {json, baseUrl};
+    }
+
+    /**
+     * Resolve every document's linked resources in parallel (shared urls coalesce via the
+     * scene fetch cache), then parse. Each index settles exactly once for `onProgress`.
+     */
+    private async loadDocuments(
+        docs: Array<{json: any; baseUrl: string} | null>,
+        options: QuarksBatchLoadOptions
+    ): Promise<(TransformNode | null)[]> {
+        const total = docs.length;
+        if (total === 0) {
+            return [];
+        }
+
+        const results: (TransformNode | null)[] = new Array(total);
+        const settled = new Array<boolean>(total).fill(false);
+        let done = 0;
+        const settle = (index: number, value: TransformNode | null) => {
+            if (settled[index]) {
+                return;
+            }
+            settled[index] = true;
+            results[index] = value;
+            done++;
+            options.onProgress?.(done, total);
+        };
+
+        await 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);
+                }
+            })
+        );
+
+        for (let i = 0; i < total; i++) {
+            if (settled[i]) {
+                continue;
+            }
+            const doc = docs[i];
+            if (!doc) {
+                settle(i, null);
+                continue;
+            }
+            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);
+            }
+        }
+        return results;
+    }
+
+    /** Runs `fn` over `items` with at most `concurrency` in flight (or all if unset/≤0). */
+    private static async mapPool<T, R>(
+        items: T[],
+        concurrency: number | undefined,
+        fn: (item: T, index: number) => Promise<R>
+    ): Promise<R[]> {
+        if (items.length === 0) {
+            return [];
+        }
+        const limit = concurrency !== undefined && concurrency > 0 ? concurrency : items.length;
+        const results = new Array<R>(items.length);
+        let next = 0;
+
+        const worker = async () => {
+            while (next < items.length) {
+                const index = next++;
+                results[index] = await fn(items[index], index);
+            }
+        };
+
+        const workers = Math.min(limit, items.length);
+        await Promise.all(Array.from({length: workers}, () => worker()));
+        return results;
+    }
+
+    private static async resolveWith(
+        resolver: QuarksResourceResolver | undefined,
+        url: string,
+        kind: QuarksResourceKind,
+        baseUrl: string
+    ): Promise<string> {
+        if (resolver?.resolve) {
+            return resolver.resolve(url, kind, baseUrl);
+        }
+        return QuarksLoader.joinUrl(baseUrl, url);
+    }
+
+    /** One in-flight fetch per scene + resolved url when `scene` is set; otherwise uncached. */
+    private static fetchJsonWith(
+        resolver: QuarksResourceResolver | undefined,
+        resolvedUrl: string,
+        scene: Scene | undefined
+    ): Promise<unknown> {
+        const load = async () => {
+            if (resolver?.fetchJson) {
+                return resolver.fetchJson(resolvedUrl);
+            }
+            const response = await fetch(resolvedUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            return response.json();
+        };
+
+        if (!scene) {
+            return load();
+        }
+
+        const cache = sceneMap(sharedFetches, scene);
+        const key = `json|${resolvedUrl}`;
+        let pending = cache.get(key);
+        if (pending === undefined) {
+            pending = load().catch((err) => {
+                if (cache.get(key) === pending) {
+                    cache.delete(key);
+                }
+                throw err;
+            });
+            cache.set(key, pending);
+        }
+        return pending;
+    }
+
+    private static async inlineGeometryEntries(json: any, loadGeometry: (url: string) => Promise<any>): Promise<void> {
+        const geometries: any[] = Array.isArray(json?.geometries) ? json.geometries : [];
+        await Promise.all(
+            geometries
+                .filter((geom) => typeof geom?.url === 'string' && !geom.positions)
+                .map(async (geom) => {
+                    try {
+                        const data = await loadGeometry(geom.url);
+                        // Copy arrays so a shared fetch-cache document is not aliased across
+                        // effects — mutating one effect's inlined geometry must not corrupt others.
+                        for (const key of ['positions', 'indices', 'uvs', 'normals']) {
+                            const value = data?.[key];
+                            if (value === undefined) {
+                                continue;
+                            }
+                            geom[key] = Array.isArray(value) ? value.slice() : value;
+                        }
+                        delete geom.url;
+                    } catch (err) {
+                        console.warn(`[QuarksLoader] Could not load geometry "${geom.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);
             }
-            (this as any)._images[img.uuid] = img.url ? QuarksLoader.resolveUrl(baseUrl, img.url) : null;
+            // 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;
         }
     }
 
@@ -395,19 +712,6 @@ export class QuarksLoader {
         );
     }
 
-    /**
-     * `img.url` is already absolute for data/blob URIs and full http(s) URLs — common for
-     * "portable" exports that embed textures as base64 (see ensurePortableTextureUrl in
-     * babylon.quarks-editor). Prepending baseUrl to those turns e.g.
-     * "data:image/png;base64,AAAA" into an invalid path like "/some/dir/data:image/png;base64,AAAA".
-     */
-    private static resolveUrl(baseUrl: string, url: string): string {
-        if (/^(data|blob):/i.test(url) || /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('/')) {
-            return url;
-        }
-        return baseUrl + url;
-    }
-
     private parseTextures(textures: any[], meta: LoadedMeta): void {
         const images = (this as any)._images || {};
         for (const texDef of textures) {