@needle-tools/engine 2.52.0-pre → 2.54.2-pre

package/src/engine/engine_element.ts

@@ -167,7 +167,8 @@ export class EngineElement extends HTMLElement implements INeedleEngineComponent
             }
             if (fn) {
                 this.classList.add("loading");
-                console.log("Needle Engine: Begin loading", alias ?? "");
+                if (debug)
+                    console.log("Needle Engine: Begin loading", alias ?? "");
                 const allowOverridingDefaultLoading = true;
                 // default loading can be overriden by calling preventDefault in the onload start event
                 const useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {
@@ -210,7 +211,8 @@ export class EngineElement extends HTMLElement implements INeedleEngineComponent
                     this._loadingView?.onLoadingFinished("create scene");
                 this.classList.remove("loading");
                 this.classList.add("loading-finished");
-                console.log("Needle Engine: finished loading", alias ?? "");
+                if (debug)
+                    console.log("Needle Engine: finished loading", alias ?? "");
                 this.dispatchEvent(new CustomEvent("loadfinished", {
                     detail: {
                         context: this._context,

package/src/engine/engine_element_loading.ts

@@ -4,6 +4,7 @@ import { LoadingProgressArgs } from "./engine_setup";
 import { getParam } from "./engine_utils";
 
 const debug = getParam("debugloadingbar");
+const debugRendering = getParam("debugloadingbarrendering");
 
 export class LoadingElementOptions {
     className?: string;
@@ -43,12 +44,14 @@ export function calculateProgress01(progress: LoadingProgressArgs) {
 
 export class EngineLoadingView implements ILoadingViewHandler {
 
+    static LoadingContainerClassName = "loading";
+
     // the raw progress
     loadingProgress: number = 0;
 
     private container: HTMLElement;
     private _progress: number = 0;
-    private _allowCustomLoadingElement: boolean = false;
+    private _allowCustomLoadingElement: boolean = true;
     private _loadingElement?: HTMLElement;
     private _loadingTextContainer: HTMLElement | null = null;
     private _loadingBar: HTMLElement | null = null;
@@ -61,20 +64,21 @@ export class EngineLoadingView implements ILoadingViewHandler {
     }
 
     onLoadingBegin(message?: string) {
+        if(debug) console.log("Begin Loading")
         if (!this._loadingElement) {
             for (let i = 0; i < this.container.children.length; i++) {
                 const el = this.container.children[i] as HTMLElement;
-                if (el.classList.contains("loading")) {
+                if (el.classList.contains(EngineLoadingView.LoadingContainerClassName)) {
                     if (!this._allowCustomLoadingElement) {
-                        console.warn("Custom loading container is not allowed")
+                        if(debug) console.warn("Remove custom loading container")
                         this.container.removeChild(el);
                         continue;
                     }
                     this._loadingElement = this.createLoadingElement(el);
-                    return;
                 }
             }
-            this._loadingElement = this.createLoadingElement();
+            if (!this._loadingElement)
+                this._loadingElement = this.createLoadingElement();
         }
         this._progress = 0;
         this.loadingProgress = 0;
@@ -121,9 +125,11 @@ export class EngineLoadingView implements ILoadingViewHandler {
         if (this._progressLoop) return;
         let dt = 1 / 12;
         const max = 1 - .05;
+        if(debugRendering) dt = 1 / 500;
         this._progressLoop = setInterval(() => {
             if (this.loadingProgress >= 1 && this._progress >= max) {
                 if (this._loadingElement) {
+                    if(debug) console.log("Hiding loading element");
                     this._loadingElement.style.display = "none";
                     this._loadingElement.remove();
                 }
@@ -148,6 +154,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
     }
 
     private createLoadingElement(existing?: HTMLElement): HTMLElement {
+    if(debug && !existing) console.log("Creating loading element");
         this._loadingElement = existing || document.createElement("div");
         if (!existing) {
             this._loadingElement.style.position = "fixed";
@@ -165,7 +172,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
             this._loadingElement.style.color = "white";
         }
 
-        const className = this._loadingElementOptions?.className ?? "loading";
+        const className = this._loadingElementOptions?.className ?? EngineLoadingView.LoadingContainerClassName;
         this._loadingElement.classList.add(className);
         if (this._loadingElementOptions?.additionalClasses) {
             for (const c of this._loadingElementOptions.additionalClasses) {

package/src/engine/engine_element_overlay.ts

@@ -1,6 +1,7 @@
 import { Context } from "./engine_setup";
-import { isMozillaXR } from "./engine_utils";
+import { getParam, isMozillaXR } from "./engine_utils";
 
+const debug = getParam("debugaroverlay");
 export const arContainerClassName = "ar";
 export const quitARClassName = "quit-ar";
 
@@ -110,7 +111,8 @@ export class AROverlayHandler {
         if (arElements && arElements.length > 0)
             return arElements[0] as HTMLElement;
 
-        console.log("No overlay container found in document - generating new ony");
+        if (debug)
+            console.log("No overlay container found in document - generating new ony");
         const el = document.createElement("div");
         el.classList.add(arContainerClassName);
         el.style.position = "absolute";

package/src/engine/engine_input.ts

@@ -384,6 +384,8 @@ export class Input extends EventTarget {
         for (let i = 0; i < evt.changedTouches.length; i++) {
             const touch = evt.changedTouches[i];
             const id = this.getPointerIndex(touch.identifier)
+            if (debug)
+                showBalloonMessage(`touch start #${id}, identifier:${touch.identifier}`);
             const args: PointerEventArgs = { button: id, clientX: touch.clientX, clientY: touch.clientY, pointerType: PointerType.Touch, source: evt };
             this.onDown(args);
         }
@@ -404,6 +406,8 @@ export class Input extends EventTarget {
         for (let i = 0; i < evt.changedTouches.length; i++) {
             const touch = evt.changedTouches[i];
             const id = this.getPointerIndex(touch.identifier)
+            if (debug)
+                showBalloonMessage(`touch up #${id}, identifier:${touch.identifier}`);
             const args: PointerEventArgs = { button: id, clientX: touch.clientX, clientY: touch.clientY, pointerType: PointerType.Touch, source: evt };
             this.onUp(args);
         }

package/src/engine/engine_networking_instantiate.ts

@@ -35,7 +35,10 @@ export class InstantiateIdProvider implements UIDProvider {
     private _originalSeed: number;
     private _seed: number;
 
-    constructor(seed: number) {
+    constructor(seed: string | number) {
+        if (typeof seed === "string") {
+            seed = InstantiateIdProvider.hash(seed);
+        }
         this._originalSeed = seed;
         this._seed = seed;
     }

package/src/engine/engine_networking_websocket.ts

@@ -1 +1,3 @@
-// TODO: move websocket specific networking code here!
+// TODO: move websocket specific networking code here!
+
+export {}

package/src/engine/engine_serialization_builtin_serializer.ts

@@ -4,7 +4,9 @@ import { SerializationContext, TypeSerializer } from "./engine_serialization_cor
 import { Behaviour, Component, GameObject } from "../engine-components/Component";
 import { debugExtension } from "./engine_default_parameters";
 import { CallInfo, EventList } from "../engine-components/EventList";
-import { Color, Object3D } from "three";
+import { Color, Object3D, Texture, WebGLRenderTarget } from "three";
+import { RenderTexture } from "./engine_texture";
+import { isDevEnvironment } from "../engine/debug/debug";
 
 // export class SourcePath {
 //     src?:string
@@ -96,7 +98,11 @@ class ObjectSerializer extends TypeSerializer {
                 if (!res) {
                     res = GameObject.findByGuid(data.guid, context.context.scene);
                 }
-                if (!res) console.warn("could not resolve reference", data, context.target, context.path, context.context.scene);
+                if (!res) {
+                    if (isDevEnvironment() || debugExtension)
+                        console.warn("Could not resolve object reference", context.path, data, context.target, context.context.scene);
+                    data["could_not_resolve"] = true;
+                }
                 else if (debugExtension)
                     console.log("Deserialized object reference?", data, res, context?.nodeToObject);
                 return res;
@@ -129,15 +135,20 @@ class ComponentSerializer extends TypeSerializer {
                 console.log(data.guid, context.root, context.object, context.target);
             // first search within the gltf (e.g. necessary when using AssetReference and loading a gltf without adding it to the scene)
             // if we would search JUST the scene those references would NEVER be resolved
-            const res = this.findObjectForGuid(data.guid, context.root);
+            let res = this.findObjectForGuid(data.guid, context.root);
             if (res) {
                 return res;
             }
-            else if (context.context) {
+            if (context.context) {
                 // if not found within the gltf use the provided context scene
                 // to find references outside
-                return this.findObjectForGuid(data.guid, context.context?.scene);
+                res = this.findObjectForGuid(data.guid, context.context?.scene);
+                if (res) return res;
             }
+            if (isDevEnvironment() || debugExtension)
+                console.warn("Could not resolve component reference", context.path, data, context.target);
+            data["could_not_resolve"] = true;
+            return undefined;
         }
         // if (data?.node !== undefined && context.nodeToObject) {
         //     return context.nodeToObject[data.node];
@@ -191,8 +202,7 @@ class EventListSerializer extends TypeSerializer {
 
     onDeserialize(data: EventListData, context: SerializationContext): EventList | undefined | null {
         // TODO: check that we dont accidentally deserialize methods to EventList objects. This is here to make is easy for react-three-fiber to just add props as { () => { } } 
-        if(typeof data === "function")
-        {
+        if (typeof data === "function") {
             const evtList = new EventList([new CallInfo(data, true)]);
             return evtList;
         }
@@ -220,7 +230,7 @@ class EventListSerializer extends TypeSerializer {
                                 call.method = call.method.substring(4);
                                 if (target[call.method] !== undefined) foundMethod = true;
                             }
-                            if (!foundMethod)
+                            if (!foundMethod && (isDevEnvironment() || debugExtension))
                                 printWarningMethodNotFound();
                         }
                     }
@@ -284,3 +294,24 @@ class EventListSerializer extends TypeSerializer {
 }
 export const eventListSerializer = new EventListSerializer();
 
+
+
+export class RenderTextureSerializer extends TypeSerializer {
+    constructor() {
+        super([RenderTexture, WebGLRenderTarget]);
+    }
+
+    onSerialize(_data: any, _context: SerializationContext) {
+    }
+
+    onDeserialize(data: any, context: SerializationContext) {
+        if (data instanceof Texture && context.type === RenderTexture) {
+            const tex = data as Texture;
+            const rt = new RenderTexture(tex.image.width, tex.image.height);
+            rt.texture = tex;
+            return rt;
+        }
+        return undefined;
+    }
+}
+new RenderTextureSerializer();

package/src/engine/engine_serialization_core.ts

@@ -181,6 +181,7 @@ export class SerializationContext {
     objectToNode?: ObjectToNodeMap;
     context?: Context;
     path?: string;
+    type?: Constructor<any>;
     /** holds information if a field was undefined before serialization. This gives us info if we might want to warn the user about missing attributes */
     implementationInformation?: ImplementationInformation;
 
@@ -286,6 +287,7 @@ export function deserializeObject(obj: ISerializable, serializedData: object, co
                     continue;
                 }
 
+                context.type = undefined;
                 context.path = key;
 
                 if (serializedEntryInfo === null) {
@@ -376,6 +378,9 @@ function checkObjectAssignments(obj: any, serializedData: any, implementationInf
         if (typeof serialized === "object") {
             if (value === undefined || !value.isObject3D) {
                 if (typeof serialized["node"] === "number" || typeof serialized["guid"] === "string") {
+                    if (serialized["could_not_resolve"]) {
+                        continue;
+                    }
                     const hasOtherKeys = value !== undefined && Object.keys(value).length > 1;
                     if (!hasOtherKeys) {
                         showBalloonMessage(`<strong>Missing serialization for object reference!</strong>\n\nPlease change to: \n@serializable(Object3D)\n${key}? : Object3D;\n\nin script ${typeName}.ts\n<a href="https://docs.needle.tools/serializable" target="_blank">documentation</a>`, LogType.Warn);
@@ -453,7 +458,8 @@ function deserializeObjectWithType(data: any, typeOrConstructor: Constructor<any
             console.error("Error in callback", err, data);
         }
     }
-
+    context.type = type;
+    
     // e.g. when @serializable(Texture) and the texture is already resolved via json pointer from gltf
     // then we dont need to do anything else
     if (!typeIsFunction && currentValue instanceof type) return currentValue;

package/src/engine/engine_setup.ts

@@ -134,8 +134,8 @@ export class Context {
 	private calculateBoundingClientRect() {
 		// workaround for mozilla webXR viewer
 		if (this.isInAR) {
-			this._domX = window.innerWidth;
-			this._domY = window.innerHeight;
+			this._domX = 0;
+			this._domY = 0;
 			return;
 		}
 		if (this._boundingClientRectFrame === this.time.frame) return;

package/src/engine/engine_texture.ts

@@ -0,0 +1,6 @@
+import { WebGLRenderTarget } from "three"
+
+export class RenderTexture extends WebGLRenderTarget
+{
+    
+}

package/src/engine/engine_utils.ts

@@ -52,7 +52,7 @@ export function getUrlParams() {
     return new URLSearchParams(window.location.search);
 }
 
-export function getParam(paramName: string): string | boolean {
+export function getParam(paramName: string): string | boolean | number {
 
     if (saveParams && !requestedParams.includes(paramName))
         requestedParams.push(paramName);
@@ -60,6 +60,8 @@ export function getParam(paramName: string): string | boolean {
     if (urlParams.has(paramName)) {
         const val = urlParams.get(paramName);
         if (val) {
+            const num = Number(val);
+            if (!isNaN(num)) return num; 
             return val;
         }
         else return true;

package/src/engine/extensions/NEEDLE_progressive.ts

@@ -0,0 +1,357 @@
+import { Material, Texture, TextureLoader } from "three";
+import { GLTF, GLTFLoader, GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader";
+import { SourceIdentifier } from "../engine_types";
+import { Context } from "../engine_setup";
+import { addDracoAndKTX2Loaders } from "../engine_loaders";
+import { delay, getParam, getPath } from "../engine_utils";
+
+export const EXTENSION_NAME = "NEEDLE_progressive";
+
+const debug = getParam("debugprogressive");
+
+declare type ProgressiveTextureSchema = {
+    uri: string;
+    guid: string;
+}
+
+
+const debug_toggle_maps: Map<Material, { [key: string]: { original: Texture, lod0: Texture } }> = new Map();
+let show_lod0 = false;
+if (debug) {
+    window.addEventListener("keyup", evt => {
+        if (evt.key === "p") {
+            debug_toggle_maps.forEach((map, material) => {
+                Object.entries(map).forEach(([key, value]) => {
+                    if (show_lod0) {
+                        material[key] = value.lod0;
+                    } else {
+                        material[key] = value.original;
+                    }
+                    material.needsUpdate = true;
+                });
+            });
+            show_lod0 = !show_lod0;
+        }
+    });
+}
+
+export class NEEDLE_progressive implements GLTFLoaderPlugin {
+
+    static assignTextureLOD(context: Context, source: SourceIdentifier | undefined, material: Material, level: number = 0) {
+        if (!material) return;
+        for (let slot of Object.keys(material)) {
+            const val = material[slot];
+            if (val?.isTexture === true) {
+
+                if (debug) console.log("-----------\n", "FIND", material.name, slot, val?.name, val?.userData, val, material);
+
+                NEEDLE_progressive.getOrLoadTexture(context, source, material, slot, val, level).then(t => {
+                    if (t?.isTexture === true) {
+
+                        if (debug) console.log("Assign LOD", material.name, slot, t.name, t["guid"], material, "Prev:", val, "Now:", t, "\n--------------");
+
+                        material[slot] = t;
+                        t.needsUpdate = true;
+                        material.needsUpdate = true;
+
+                        if (debug) {
+                            let debug_map = debug_toggle_maps.get(material);
+                            if (!debug_map) {
+                                debug_map = {};
+                                debug_toggle_maps.set(material, debug_map);
+                            }
+                            let entry = debug_map[slot];
+                            if (!entry) {
+                                entry = debug_map[slot] = { original: val, lod0: t };
+                            }
+                            entry.lod0 = t;
+                        }
+                    }
+                });
+            }
+        }
+    }
+
+    get name(): string {
+        return EXTENSION_NAME;
+    }
+
+    private parser: GLTFParser;
+    private sourceId: SourceIdentifier;
+    private context: Context;
+
+    constructor(parser: GLTFParser, sourceId: SourceIdentifier, context: Context) {
+        this.parser = parser;
+        this.sourceId = sourceId;
+        this.context = context;
+    }
+
+    private _loading: number[] = [];
+
+    // beforeRoot(): null {
+    //     console.log("BEFORE ROOT", this.parser);
+    //     return null;
+    // }
+
+    // loadTexture(index: number): Promise<Texture> | null {
+    //     console.log(index, this._loading);
+    //     if (this._loading.includes(index)) return null;
+    //     const textureInfo = this.parser.json.textures[index];
+    //     if (debug)
+    //         console.log(index, textureInfo);
+    //     return null;
+    // }
+
+    afterRoot(gltf: GLTF): null {
+        if (debug)
+            console.log("AFTER", this.sourceId, gltf);
+        this.parser.json.textures?.forEach((textureInfo, index) => {
+            if (textureInfo?.extensions) {
+                const ext: ProgressiveTextureSchema = textureInfo?.extensions[EXTENSION_NAME];
+                if (ext) {
+                    const prom = this.parser.getDependency("texture", index);
+                    this._loading.splice(this._loading.indexOf(index), 1);
+                    prom.then(t => {
+                        if (debug) console.log("register texture", t.name, t.uuid, ext);
+                        t.userData.deferred = ext;
+                        NEEDLE_progressive.cache.set(t.uuid, ext);
+                    });
+                }
+            }
+        });
+
+        return null;
+    }
+
+    private static cache = new Map<string, ProgressiveTextureSchema>();
+    private static resolved: { [key: string]: Texture } = {};
+    private static currentlyLoading: { [key: string]: Promise<Texture | null> } = {};
+
+    private static async getOrLoadTexture(context: Context, source: SourceIdentifier | undefined, material: Material, slot: string, current: Texture, _level: number): Promise<Texture | null> {
+
+        const key = current.uuid;
+        const ext: ProgressiveTextureSchema | undefined = NEEDLE_progressive.cache.get(key);// || current.userData.deferred;
+        if (ext) {
+            if (debug)
+                console.log(key, ext.uri, ext.guid);
+            const uri = getPath(source, ext.uri);
+            if (uri.endsWith(".glb") || uri.endsWith(".gltf")) {
+                if (!ext.guid) {
+                    console.warn("missing pointer for glb/gltf texture", ext);
+                    return null;
+                }
+                const resolveKey = uri + "_" + ext.guid;
+                if (this.resolved[resolveKey]) {
+                    if (debug) console.log("Texture has already been loaded: " + resolveKey, material.name, slot, current.name);
+                    return this.resolved[resolveKey];
+                }
+
+                const info = this.onProgressiveLoadStart(context, source, uri, material, slot);
+                try {
+                    if(this.currentlyLoading[resolveKey] !== undefined) {
+                        if(debug)
+                            console.log("Already loading:", material.name + "." + slot, resolveKey);
+                        const tex = await this.currentlyLoading[resolveKey];
+                        return tex;
+                    }
+                    const request = new Promise<Texture | null>(async (resolve, _) => {
+                        const loader = new GLTFLoader();
+                        addDracoAndKTX2Loaders(loader, context);
+
+                        if (debug) console.log("Load " + uri, material.name, slot, ext.guid);
+                        if (debug) {
+                            await delay(Math.random() * 1000);
+                        }
+
+                        const gltf = await loader.loadAsync(uri);
+                        const parser = gltf.parser;
+                        if (debug) console.log("Loading finished " + uri, material.name, slot, ext.guid);
+                        let index = -1;
+                        let found = false;
+                        for (const tex of gltf.parser.json.textures) {
+                            index++;
+                            if (tex?.extensions) {
+                                const other: ProgressiveTextureSchema = tex?.extensions[EXTENSION_NAME];
+                                if (other?.guid) {
+                                    if (other.guid === ext.guid) {
+                                        found = true;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                        if (!found)
+                            return resolve(null);
+
+                        const tex = await parser.getDependency("texture", index);
+                        tex.encoding = current.encoding;
+                        if (tex) {
+                            tex.guid = ext.guid;
+                        }
+                        this.resolved[resolveKey] = tex as Texture;
+                        if (debug)
+                            console.log(material.name, slot, "change \"" + current.name + "\" → \"" + tex.name + "\"", uri, index, tex, material, resolveKey);
+                        resolve(tex);
+                    });
+                    this.currentlyLoading[resolveKey] = request;
+                    const tex = await request;
+                    return tex;
+                }
+                finally {
+                    delete this.currentlyLoading[resolveKey];
+                    this.onProgressiveLoadEnd(info);
+                }
+            }
+            else {
+                const info = this.onProgressiveLoadStart(context, source, uri, material, slot);
+                try {
+                    if (debug) console.log("Load texture from uri: " + uri);
+                    const loader = new TextureLoader();
+                    const tex = await loader.loadAsync(uri);
+                    if (tex) {
+                        (tex as any).guid = ext.guid;
+                        tex.flipY = false;
+                        tex.needsUpdate = true;
+                        tex.encoding = current.encoding;
+                        if (debug)
+                            console.log(ext, tex);
+                    }
+                    else if (debug) console.warn("failed loading", uri);
+                    return tex;
+                }
+                finally {
+                    this.onProgressiveLoadEnd(info);
+                }
+            }
+            // loader.then((h: Texture) => {
+            //     // console.log(t, h);
+            //     // t.image = h.image;
+            //     // // this.context.renderer.copyTextureToTexture(new Vector2(0, 0), h, t);
+            //     // // console.log(h);
+
+            //     // // t.source = h.source;
+            //     // // t.version++;
+            //     // t.width = h.width;
+            //     // t.height = h.height;
+            //     // t.needsUpdate = true;
+            // });
+        }
+        else {
+            if (debug)
+                console.warn("unknown uuid", current.name, current.uuid, current);
+        }
+        return null;
+    }
+
+
+    /** subscribe to events whenever a loading event starts, invoked for every single loading process that starts */
+    static beginListenStart(context: Context, evt: ProgressiveLoadingEvent) {
+        if (!this._progressiveEventListeners.has(context)) {
+            this._progressiveEventListeners.set(context, new ProgressiveLoadingEventHandler());
+        }
+        this._progressiveEventListeners.get(context)!.start.push(evt);
+    }
+    static stopListenStart(context: Context, evt: ProgressiveLoadingEvent) {
+        if (!this._progressiveEventListeners.has(context)) {
+            return;
+        }
+        const listeners = this._progressiveEventListeners.get(context)!.start;
+        const index = listeners.indexOf(evt);
+        if (index >= 0) {
+            listeners.splice(index, 1);
+        }
+    }
+
+    /** subscribe to loading event ended event */
+    static beginListenEnd(context: Context, evt: ProgressiveLoadingEvent) {
+        if (!this._progressiveEventListeners.has(context)) {
+            this._progressiveEventListeners.set(context, new ProgressiveLoadingEventHandler());
+        }
+        this._progressiveEventListeners.get(context)!.end.push(evt);
+    }
+    static stopListenEnd(context: Context, evt: ProgressiveLoadingEvent) {
+        if (!this._progressiveEventListeners.has(context)) {
+            return;
+        }
+        const listeners = this._progressiveEventListeners.get(context)!.end;
+        const index = listeners.indexOf(evt);
+        if (index >= 0) {
+            listeners.splice(index, 1);
+        }
+    }
+
+    /** event listeners per context */
+    private static _progressiveEventListeners: Map<Context, ProgressiveLoadingEventHandler> = new Map();
+    //** loading info per context, contains an array of urls that are currently being loaded */
+    private static _currentProgressiveLoadingInfo: Map<Context, ProgressiveLoadingInfo[]> = new Map();
+
+    // called whenever a progressive loading event starts
+    private static onProgressiveLoadStart(context: Context, source: SourceIdentifier | undefined, uri: string, material: Material, slot: string): ProgressiveLoadingInfo {
+        if (!this._currentProgressiveLoadingInfo.has(context)) {
+            this._currentProgressiveLoadingInfo.set(context, []);
+        }
+        const info = new ProgressiveLoadingInfo(context, source, uri, material, slot);
+        const current = this._currentProgressiveLoadingInfo.get(context)!;
+        const listener = this._progressiveEventListeners.get(context);
+        if (listener) listener.onStart(info);
+
+        current.push(info);
+        return info;
+    }
+
+    private static onProgressiveLoadEnd(info: ProgressiveLoadingInfo) {
+        if (!info) return;
+        const context = info.context;
+        if (!this._currentProgressiveLoadingInfo.has(context)) {
+            return;
+        }
+        const current = this._currentProgressiveLoadingInfo.get(context)!;
+        const index = current.indexOf(info);
+        if (index < 0) {
+            return;
+        }
+        current.splice(index, 1);
+        const listener = this._progressiveEventListeners.get(context);
+        if (listener) listener.onEnd(info);
+    }
+}
+
+
+/** info object that holds information about a file that is currently being loaded */
+export class ProgressiveLoadingInfo {
+    readonly context: Context;
+    readonly source: SourceIdentifier | undefined;
+    readonly uri: string;
+    readonly material?: Material;
+    readonly slot?: string;
+    // TODO: can contain information if the event is a background process / preloading or if the object is currently visible
+
+    constructor(context: Context, source: SourceIdentifier | undefined, uri: string, material?: Material, slot?: string) {
+        this.context = context;
+        this.source = source;
+        this.uri = uri;
+        this.material = material;
+        this.slot = slot;
+    }
+};
+
+
+export declare type ProgressiveLoadingEvent = (info: ProgressiveLoadingInfo) => void;
+
+/** progressive loading event handler implementation */
+class ProgressiveLoadingEventHandler {
+    start: ProgressiveLoadingEvent[] = [];
+    end: ProgressiveLoadingEvent[] = [];
+
+    onStart(listener: ProgressiveLoadingInfo) {
+        for (const l of this.start) {
+            l(listener);
+        }
+    }
+
+    onEnd(listener: ProgressiveLoadingInfo) {
+        for (const l of this.end) {
+            l(listener);
+        }
+    }
+}