@needle-tools/engine 4.8.7-next.c2b0897 → 4.8.7-next.c5a1d5a

package/plugins/vite/alias.js

@@ -62,7 +62,6 @@ const packages_to_resolve = {
 
     '@needle-tools/gltf-progressive': "auto-resolve",
     '@needle-tools/materialx': "auto-resolve",
-    '@needle-tools/materialx/needle': "auto-resolve"
 }
 
 /**
@@ -84,7 +83,7 @@ export const needleViteAlias = (command, config, userSettings) => {
         outputDebugFile?.write(msg.join(" ") + "\n");
     }
     if (debug) {
-        const outputFilePath = path.resolve(projectDir, 'node_modules/.vite/needle.alias.log');
+        const outputFilePath = path.resolve(projectDir, 'node_modules/.needle/needle.alias.log');
         const outputDirectory = path.dirname(outputFilePath);
         if (!existsSync(outputDirectory)) mkdirSync(outputDirectory, { recursive: true });
         outputDebugFile = createWriteStream(outputFilePath, { flags: "a" });
@@ -110,6 +109,18 @@ export const needleViteAlias = (command, config, userSettings) => {
                 }
             }
 
+
+            // is needle engine a local package?
+            // This will cause local changes to not be reflected anymore...
+            const localEnginePath = path.resolve(projectDir, 'node_modules/', '@needle-tools/engine', 'node_modules');
+            if (existsSync(localEnginePath)) {
+                config.optimizeDeps ??= {};
+                config.optimizeDeps.exclude ??= [];
+                config.optimizeDeps.exclude.push('@needle-tools/engine');
+                log("[needle-alias] Detected local @needle-tools/engine package: will exclude it from optimization");
+            }
+
+
             if (debug) {
                 const testResults = [];
                 for (const name in aliasDict) {
@@ -179,22 +190,20 @@ export const needleViteAlias = (command, config, userSettings) => {
         }
 
         const workingDirectory = `${process.cwd()}/`;
+        const pathExists = existsSync(fullpath);
+
+        aliasDict[name] = (packageName, index, path) => {
+            if (callback !== null) {
+                const overrideResult = callback(fullpath, packageName, index, path);
+                if (typeof overrideResult === "string")
+                    if (existsSync(overrideResult)) {
+                        if (debug && overrideResult !== packageName) log(`[needle-alias] Resolved \"${path}\"   →   \"${overrideResult.substring(workingDirectory.length).replaceAll("\\", "/")}\"`);
+                        return overrideResult;
+                    }
+            }
 
-        if (existsSync(fullpath)) {
-            aliasDict[name] = (packageName, index, path) => {
-                if (callback !== null) {
-                    const overrideResult = callback(fullpath, packageName, index, path);
-                    if (typeof overrideResult === "string")
-                        if (existsSync(overrideResult)) {
-                            if (debug && overrideResult !== packageName) console.warn(`[needle-alias] Resolved \"${path}\"   →   \"${overrideResult.substring(workingDirectory.length).replaceAll("\\", "/")}\"`);
-                            return overrideResult;
-                        }
-                }
-
-                if (debug && path !== packageName) {
-                    console.warn(`[needle-alias] Resolved \"${path}\"   →   \"${fullpath.substring(workingDirectory.length).replaceAll("\\", "/")}\"`);
-                }
-
+            if (pathExists) {
+                if (debug && path !== packageName) log(`[needle-alias] Resolved \"${path}\"   →   \"${fullpath.substring(workingDirectory.length).replaceAll("\\", "/")}\"`);
                 return fullpath;
             }
         }

package/src/engine/engine_addressables.ts

@@ -8,7 +8,7 @@ import { BlobStorage } from "./engine_networking_blob.js";
 import { registerPrefabProvider, syncInstantiate, SyncInstantiateOptions } from "./engine_networking_instantiate.js";
 import { SerializationContext, TypeSerializer } from "./engine_serialization_core.js";
 import { Context } from "./engine_setup.js";
-import type { GLTF, IComponent, IGameObject, SourceIdentifier } from "./engine_types.js";
+import type { GLTF, IComponent, IGameObject, Model, SourceIdentifier } from "./engine_types.js";
 
 const debug = getParam("debugaddressables");
 
@@ -138,21 +138,35 @@ export class AssetReference {
         return ref;
     }
 
-    private static currentlyInstantiating: Map<string, number> = new Map<string, number>();
 
-    /** @returns true if this is an AssetReference instance */
-    get isAssetReference() { return true; }
 
-    /** The loaded asset */
+
+
+
+    readonly isAssetReference = true;
+
+    /**  
+     * This is the loaded asset root object. If the asset is a glb/gltf file this will be the {@link three#Scene} object.
+     */
+    get rawAsset(): any { return this._rawAsset; }
+
+    /** The loaded asset root
+     */
     get asset(): Object3D | null {
-        return this._glbRoot ?? this._asset;
+        return this._glbRoot ?? (this._rawAsset?.scene || null);
     }
 
-    protected set asset(val: any) {
-        this._asset = val;
+    protected set asset(val: Object3D | null) {
+        if (val) {
+            this._rawAsset = {
+                animations: val.animations,
+                scene: val,
+                scenes: [val],
+            }
+        }
+        else this._rawAsset = null;
     }
 
-    private _loading?: PromiseLike<any>;
 
     /** The url of the loaded asset (or the asset to be loaded) 
      * @deprecated use url */
@@ -177,12 +191,7 @@ export class AssetReference {
             (this._url.startsWith("http") || this._url.startsWith("blob:") || this._url.startsWith("www.") || this._url.includes("/"));
     }
 
-    /**  
-     * This is the loaded asset root object. If the asset is a glb/gltf file this will be the {@link three#Scene} object.
-     */
-    get rawAsset(): any { return this._asset; }
-
-    private _asset: any;
+    private _rawAsset: Model | null = null;
     private _glbRoot?: Object3D | null;
     private _url: string;
     private _urlName: string;
@@ -207,7 +216,7 @@ export class AssetReference {
         else {
             this._urlName = uri;
         }
-        
+
         if (asset !== null) this.asset = asset;
         registerPrefabProvider(this._url, this.onResolvePrefab.bind(this));
     }
@@ -226,6 +235,8 @@ export class AssetReference {
         return !this.asset || (this.asset as any).__destroyed === true || isDestroyed(this.asset) === true;
     }
 
+    private _loadingPromise: Promise<Model | null | undefined> | null = null;
+
     /**
      * @returns `true` if the asset has been loaded (via preload) or if it exists already (assigned to `asset`) */
     isLoaded() { return this._rawBinary || this.asset !== undefined }
@@ -242,7 +253,7 @@ export class AssetReference {
         this.asset = null;
         this._rawBinary = undefined;
         this._glbRoot = null;
-        this._loading = undefined;
+        this._loadingPromise = null;
         if (Context.Current) {
             Context.Current.addressables.unregisterAssetReference(this);
         }
@@ -267,16 +278,14 @@ export class AssetReference {
     /** Loads the asset and creates one instance (assigned to `asset`)
      * @returns the loaded asset
      */
-    async loadAssetAsync(prog?: ProgressCallback | null) {
-        if (debug)
-            console.log("loadAssetAsync", this.url);
+    async loadAssetAsync(prog?: ProgressCallback | null): Promise<Object3D | null> {
+        if (debug) console.log("[AssetReference] loadAssetAsync", this.url);
         if (!this.mustLoad) return this.asset;
 
         if (prog) this._progressListeners.push(prog);
-        
-        if (this._loading !== undefined) {
-            // console.warn("Wait for other loading thiny");
-            return this._loading.then(_ => this.asset);
+
+        if (this._loadingPromise !== null) {
+            return this._loadingPromise.then(_ => this.asset);
         }
         const context = Context.Current;
         // TODO: technically we shouldnt call awake only when the object is added to a scene
@@ -285,31 +294,30 @@ export class AssetReference {
         // console.log("START LOADING");
         if (this._rawBinary) {
             if (!(this._rawBinary instanceof ArrayBuffer)) {
-                console.error("Failed loading: Invalid raw binary data. Must be of type ArrayBuffer. " + (typeof this._rawBinary));
+                console.error("[AssetReference] Failed loading – Invalid data. Must be of type ArrayBuffer. " + (typeof this._rawBinary));
                 return null;
             }
-            this._loading = getLoader().parseSync(context, this._rawBinary, this.url, null);
+            this._loadingPromise = getLoader().parseSync(context, this._rawBinary, this.url, null);
             this.raiseProgressEvent(new ProgressEvent("progress", { loaded: this._rawBinary.byteLength, total: this._rawBinary.byteLength }));
         }
         else {
             if (debug) console.log("Load async", this.url);
-            this._loading = getLoader().loadSync(context, this.url, this.url, null, prog => {
+            this._loadingPromise = getLoader().loadSync(context, this.url, this.url, null, prog => {
                 this.raiseProgressEvent(prog);
             });
         }
-        const res = await this._loading;
+        this._loadingPromise.finally(() => this._loadingPromise = null);
+        const res = await this._loadingPromise;
         // clear all progress listeners after download has finished
         this._progressListeners.length = 0;
         this._glbRoot = this.tryGetActualGameObjectRoot(res);
-        this._loading = undefined;
         if (res) {
             // Make sure the loaded roots all have a reference to this AssetReference
             // that was originally loading it.
             // We need this when the loaded asset is being disposed
             // TODO: we have to prevent disposing resources that are still in use
             res[$assetReference] = this;
-            if (this._glbRoot)
-                this._glbRoot[$assetReference] = this;
+            if (this._glbRoot) this._glbRoot[$assetReference] = this;
             if (this.asset) this.asset[$assetReference] = this;
 
             // we need to handle the pre_setup callsbacks before instantiating
@@ -317,7 +325,7 @@ export class AssetReference {
             processNewScripts(context);
 
             if (res.scene !== undefined) {
-                this.asset = res;
+                this._rawAsset = res;
             }
             return this.asset;
         }
@@ -352,6 +360,9 @@ export class AssetReference {
         }
     }
 
+
+    private static readonly currentlyInstantiating: Map<string, number> = new Map<string, number>();
+
     private async onInstantiate(opts?: Object3D | IInstantiateOptions | SyncInstantiateOptions | null, networked: boolean = false, saveOnServer?: boolean): Promise<Object3D | null> {
         const context = Context.Current;
 
@@ -544,7 +555,7 @@ export class ImageReference {
             console.error("Can not load texture without url");
             return failedTexturePromise;
         }
-        
+
         if (!this.loader) this.loader = new TextureLoader();
         this.loader.setCrossOrigin("anonymous");
         return this.loader.loadAsync(this.url).then(res => {

package/src/engine/engine_animation.ts

@@ -2,6 +2,7 @@ import { AnimationAction, AnimationClip, AnimationMixer, Object3D, PropertyBindi
 
 import type { Context } from "./engine_context.js";
 import { GLTF, IAnimationComponent, Model } from "./engine_types.js";
+import { TypeStore } from "./engine_typestore.js";
 
 /**
  * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.  
@@ -88,12 +89,15 @@ export class AnimationUtils {
      * This method will look for objects in the scene that have animations and assign them to the correct objects.  
      * @param file The GLTF file to assign the animations from
      */
-    static assignAnimationsFromFile(file: Pick<Model, "animations" | "scene">, opts?: { createAnimationComponent(obj: Object3D, animation: AnimationClip): IAnimationComponent }) {
+    static autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null {
         if (!file || !file.animations) {
             console.debug("No animations found in file");
-            return;
+            return null;
         }
 
+        const scene = "scene" in file ? file.scene : file as Object3D;
+        const animationComponents = new Array<IAnimationComponent>();
+
         for (let i = 0; i < file.animations.length; i++) {
             const animation = file.animations[i];
             if (!animation.tracks || animation.tracks.length <= 0) {
@@ -103,12 +107,12 @@ export class AnimationUtils {
             for (const t in animation.tracks) {
                 const track = animation.tracks[t];
                 const parsedPath = PropertyBinding.parseTrackName(track.name);
-                let obj = PropertyBinding.findNode(file.scene, parsedPath.nodeName);
+                let obj = PropertyBinding.findNode(scene, parsedPath.nodeName);
                 if (!obj) {
                     const objectName = track["__objectName"] ?? track.name.substring(0, track.name.indexOf("."));
                     // let obj = gltf.scene.getObjectByName(objectName);
                     // this finds unnamed objects that still have tracks targeting them
-                    obj = file.scene.getObjectByProperty('uuid', objectName);
+                    obj = scene.getObjectByProperty('uuid', objectName);
 
                     if (!obj) {
                         // console.warn("could not find " + objectName, animation, gltf.scene);
@@ -116,19 +120,23 @@ export class AnimationUtils {
                     }
                 }
 
-                let animationComponent = findAnimationGameObjectInParent(obj) || findAnimationGameObjectInParent(file.scene);
+                let animationComponent = findAnimationGameObjectInParent(obj) || findAnimationGameObjectInParent(scene);
                 if (!animationComponent) {
-                    if (!opts?.createAnimationComponent) {
-                        console.warn("No AnimationComponent found in parent hierarchy of object and no 'createAnimationComponent' callback was provided in options.")
-                        continue;
+                    const anim = TypeStore.get("Animation");
+                    animationComponent = scene.addComponent(anim);
+                    if (!animationComponent) {
+                        console.error("Failed creating Animation component: No 'Animation' component found in TypeStore");
+                        break;
                     }
-                    animationComponent = opts.createAnimationComponent(file.scene, animation);
                 }
+                animationComponents.push(animationComponent);
                 if (animationComponent.addClip) {
                     animationComponent.addClip(animation);
                 }
             }
         }
+        return animationComponents;
+
         function findAnimationGameObjectInParent(obj): IAnimationComponent | null {
             if (!obj) return null;
             const components = obj.userData?.components;

package/src/engine/engine_loaders.ts

@@ -61,7 +61,7 @@ export async function onCreateLoader(url: string, context: Context): Promise<Cus
     switch (type) {
         case "unsupported":
             return null;
-            
+
         default:
         case "unknown":
             {
@@ -287,15 +287,6 @@ async function onAfterLoaded(loader: Loader | CustomLoader, context: Context, gl
         gltfId = gltfId.split("?")[0];
     }
 
-    // assign animations of loaded glTF to all scenes
-    if ("scenes" in model) {
-        for (const scene of model.scenes) {
-            if (scene && !scene.animations?.length) {
-                scene.animations = [...model.animations];
-            }
-        }
-    }
-
     // E.g. fbx material cleanup
     postprocessLoadedFile(loader, model);
 
@@ -357,13 +348,27 @@ function checkIfUserAttemptedToLoadALocalFile(url: string) {
 /**
  * Postprocess the loaded file. This is used to apply any custom postprocessing to the loaded file.
  */
-function postprocessLoadedFile(loader: object, result: Model) {
+function postprocessLoadedFile(loader: object, model: Model) {
+
+
+    // assign animations of loaded glTF to all scenes
+    if ("scenes" in model) {
+        for (const scene of model.scenes) {
+            if (scene && !scene.animations?.length) {
+                for (const anim of model.animations) {
+                    if (!scene.animations.includes(anim)) {
+                        scene.animations.push(anim);
+                    }
+                }
+            }
+        }
+    }
 
     if (loader instanceof FBXLoader || loader instanceof OBJLoader) {
 
-        let obj: Object3D | Model = result;
+        let obj: Object3D | Model = model;
         if (!(obj instanceof Object3D)) {
-            obj = (result as GLTF).scene;
+            obj = (model as GLTF).scene || model.scenes.find(s => s);
         }
 
         obj.traverse((child) => {

package/src/engine-components/Animation.ts

@@ -67,7 +67,7 @@ export class Animation extends Behaviour implements IAnimationComponent {
     get isAnimationComponent(): boolean { return true; }
     addClip(clip: AnimationClip) {
         if (!this.animations) this.animations = [];
-        this.animations.push(clip);
+        if (!this.animations.includes(clip)) this.animations.push(clip);
     }
 
     /**

package/src/engine-components/AnimationUtilsAutoplay.ts

@@ -1,7 +1,6 @@
 import type { GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 
 import { AnimationUtils } from "../engine/engine_animation.js";
-import { addComponent } from "../engine/engine_components.js";
 import { ContextEvent, ContextRegistry } from "../engine/engine_context_registry.js";
 import { Animation } from "./Animation.js";
 import { Animator } from "./Animator.js";
@@ -29,11 +28,7 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreated, args => {
                     return undefined;
                 }, true);
                 if (hasAnimation !== true) {
-                    AnimationUtils.assignAnimationsFromFile(file.file as GLTF, {
-                        createAnimationComponent: (obj, _clip) => {
-                            return addComponent(obj, Animation);
-                        },
-                    });
+                    AnimationUtils.autoplayAnimations(file.file as GLTF);
                 }
             }
         }

package/src/engine-components/DropListener.ts

@@ -143,13 +143,6 @@ const blobKeyName = "blob";
  */
 export class DropListener extends Behaviour {
 
-    /**
-     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
-     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
-     */
-    @serializable()
-    useNetworking: boolean = true;
-
     /**
      * When assigned, the DropListener will only accept files that are dropped on this specific object.
      * This allows creating designated drop zones in your scene.
@@ -159,7 +152,10 @@ export class DropListener extends Behaviour {
 
     /**
      * When enabled, dropped objects will be automatically scaled to fit within the volume defined by fitVolumeSize.
-     * Useful for ensuring dropped models appear at an appropriate scale.
+     * Useful for ensuring dropped models appear at an appropriate scale.   
+     * 
+     * **Tip**: Use the handy `fitObjectIntoVolume` function (`import { fitObjectIntoVolume } from "@needle-tools/engine"`) for custom fitting needs.  
+     * 
      * @default false
      */
     @serializable()
@@ -180,6 +176,14 @@ export class DropListener extends Behaviour {
     @serializable()
     placeAtHitPosition: boolean = true;
 
+    /**
+     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
+     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
+     * @default false
+     */
+    @serializable()
+    useNetworking: boolean = false;
+
     /**
      * Event list that gets invoked after a file has been successfully added to the scene.
      * Receives {@link DropListenerOnDropArguments} containing the added object and related information.
@@ -193,6 +197,27 @@ export class DropListener extends Behaviour {
     @serializable(EventList)
     onDropped: EventList<DropListenerOnDropArguments> = new EventList();
 
+    /**
+     * Loads a file from the given URL and adds it to the scene.
+     * @returns A promise that resolves to the loaded object or null if loading failed.
+     */
+    loadFromURL(url: string, data?: { point?: Vec3, size?: Vec3 }): Promise<Object3D | null> {
+        return this.addFromUrl(url, { screenposition: new Vector2(), point: data?.point, size: data?.size, }, false);
+    }
+
+    /**
+     * Forgets all previously added objects.     
+     * The droplistener will then not be able to remove previously added objects.
+     */
+    forgetObjects() {
+        this.removePreviouslyAddedObjects(false);
+    }
+
+
+
+
+    // #region internals
+
     /** @internal */
     onEnable(): void {
         this.context.renderer.domElement.addEventListener("dragover", this.onDrag);
@@ -208,21 +233,6 @@ export class DropListener extends Behaviour {
         this.context.connection.stopListen("droplistener", this.onNetworkEvent);
     }
 
-    /**
-     * Loads a file from the given URL and adds it to the scene.
-     */
-    loadFromURL(url: string, data?: { point?: Vec3, size?: Vec3 }) {
-        this.addFromUrl(url, { screenposition: new Vector2(), point: data?.point, size: data?.size, }, true);
-    }
-
-    /**
-     * Forgets all previously added objects.     
-     * The droplistener will then not be able to remove previously added objects.
-     */
-    forgetObjects() {
-        this.removePreviouslyAddedObjects(false);
-    }
-
     /**
      * Handles network events received from other clients containing information about dropped objects
      * @param evt Network event data containing object information, position, and content URL
@@ -326,7 +336,7 @@ export class DropListener extends Behaviour {
             }
         }
         if (files.length > 0) {
-            await this.addDroppedFiles(files, ctx);
+            await this.addFromFiles(files, ctx);
         }
     }
 
@@ -359,6 +369,7 @@ export class DropListener extends Behaviour {
             // Ignore dropped images
             const lowercaseUrl = url.toLowerCase();
             if (lowercaseUrl.endsWith(".hdr") || lowercaseUrl.endsWith(".hdri") || lowercaseUrl.endsWith(".exr") || lowercaseUrl.endsWith(".png") || lowercaseUrl.endsWith(".jpg") || lowercaseUrl.endsWith(".jpeg")) {
+                console.warn(`Fileformat is not supported: ${lowercaseUrl}`);
                 return null;
             }
 
@@ -374,7 +385,7 @@ export class DropListener extends Behaviour {
             });
             if (res && this._addedObjects.length <= 0) {
                 ctx.url = url;
-                const obj = this.addObject(res, ctx, isRemote);
+                const obj = this.onObjectLoaded(res, ctx, isRemote);
                 return obj;
             }
         }
@@ -393,7 +404,7 @@ export class DropListener extends Behaviour {
      * @param fileList Array of dropped files
      * @param ctx Context information about where the drop occurred
      */
-    private async addDroppedFiles(fileList: Array<File>, ctx: DropContext) {
+    private async addFromFiles(fileList: Array<File>, ctx: DropContext) {
         if (debug) console.log("Add files", fileList)
         if (!Array.isArray(fileList)) return;
         if (!fileList.length) return;
@@ -427,7 +438,7 @@ export class DropListener extends Behaviour {
             if (res) {
                 this.dispatchEvent(new CustomEvent(DropListenerEvents.FileDropped, { detail: file }));
                 ctx.file = file;
-                const obj = this.addObject(res, ctx, false);
+                const obj = this.onObjectLoaded(res, ctx, false);
 
                 // handle uploading the dropped object and networking the event
                 if (obj && this.context.connection.isConnected && this.useNetworking) {
@@ -478,7 +489,7 @@ export class DropListener extends Behaviour {
      * @param isRemote Whether this object was shared from a remote client
      * @returns The added object or null if adding failed
      */
-    private addObject(data: { model: Model, contentMD5: string }, ctx: DropContext, isRemote: boolean): Object3D | null {
+    private onObjectLoaded(data: { model: Model, contentMD5: string }, ctx: DropContext, isRemote: boolean): Object3D | null {
 
         const { model, contentMD5 } = data;
 
@@ -522,9 +533,7 @@ export class DropListener extends Behaviour {
             }
         }
 
-        AnimationUtils.assignAnimationsFromFile(model, {
-            createAnimationComponent: obj => addComponent(obj, Animation)
-        });
+        AnimationUtils.autoplayAnimations(model);
 
         const evt = new DropListenerAddedEvent({
             sender: this,