@needle-tools/engine 4.11.0-next.8bfb2f5 → 4.11.0

package/plugins/vite/needle-app.js

@@ -45,8 +45,13 @@ export const needleApp = (command, config, userSettings) => {
                                 //     refs: context.chunk.referencedFiles,
                                 // });
 
-                                const referencedGlbs = tryParseNeedleEngineSrcAttributeFromHtml(html);
-                                const webComponent = generateNeedleEmbedWebComponent(path, referencedGlbs);
+                                // TODO: here we try to find the main asset (entrypoint) for this web app. It's a bit hacky right now but we have to assign this url directly to make it work with `gen.js` where multiple needle-apps are on different (or the same) pages.
+                                const attribute_src = tryParseNeedleEngineSrcAttributeFromHtml(html);
+                                const imported_glbs = Array.from(context.chunk.viteMetadata?.importedAssets?.values() || [])?.filter(f => f.endsWith(".glb") || f.endsWith(".gltf"));
+
+                                const main_asset = attribute_src?.[0] || imported_glbs?.[0];
+
+                                const webComponent = generateNeedleEmbedWebComponent(path, main_asset);
                                 await writeFile(`${outputDir}/needle-app.js`, webComponent, (err) => {
                                     if (err) {
                                         console.error("[needle-app] could not create needle-app.js", err);
@@ -71,78 +76,119 @@ export const needleApp = (command, config, userSettings) => {
 
 /**
  * @param {string} filepath
- * @param {string[]} needleEngineSrcPaths
+ * @param {string | null} src
  * @returns {string}
  */
-function generateNeedleEmbedWebComponent(filepath, needleEngineSrcPaths) {
+function generateNeedleEmbedWebComponent(filepath, src) {
 
 
     // filepath is e.g. `assets/index-XXXXXXXX.js`
     // we want to make sure the path is correct relative to where the component will be used
     // this script will be emitted in the output directory root (e.g. needle-embed.js)
 
-    const src = needleEngineSrcPaths?.length ? `${needleEngineSrcPaths[0]}` : "";
-
-    const componentName = 'needle-app';
-    const className = 'NeedleApp';
+    const componentDefaultName = 'needle-app';
 
     return `
-class ${className} extends HTMLElement {
-    constructor() {
-        super();
-        this.attachShadow({ mode: 'open' });
-        const template = document.createElement('template');
-        template.innerHTML = \`
-            <style>
-                :host {
-                    position: relative;
-                    display: block;
-                    width: 100%;
-                    height: 100%;
-                    margin: 0;
-                    padding: 0;
-                }
-                needle-engine {
-                    position: absolute;
-                    top: 0;
-                    left: 0;
-                    width: 100%;
-                    height: 100%;
-                }
-            </style>
-        \`;
-        this.shadowRoot.appendChild(template.content.cloneNode(true));
-
-        const script = document.createElement('script');
-        script.type = 'module';
-        const url = new URL('.', import.meta.url);
-        let basePath = this.getAttribute('base-path') || \`\${url.protocol}//\${url.host}\${url.pathname}\`;
-        while(basePath.endsWith('/')) {
-            basePath = basePath.slice(0, -1);
+
+// Needle Engine attributes we want to allow to be overriden
+const knownAttributes = [
+    "src",
+    "background-color", 
+    "background-image", 
+    "environment-image", 
+    "focus-rect",
+];
+
+const scriptUrl = new URL(import.meta.url);
+const componentName = scriptUrl.searchParams.get("component-name") || '${componentDefaultName}';
+
+
+if (!customElements.get(componentName)) {
+    console.debug(\`Defining needle-app as <\${componentName}>\`);
+    customElements.define(componentName, class extends HTMLElement {
+
+        static get observedAttributes() {
+            return knownAttributes;
         }
-        script.src = this.getAttribute('script-src') || \`\${basePath}/${filepath}\`;
-        this.shadowRoot.appendChild(script);
 
-        const needleEngine = document.createElement('needle-engine');
-        needleEngine.src = this.getAttribute('src') || ${src?.length ? `\${basePath}/${needleEngineSrcPaths}` : undefined};
-        this.shadowRoot.appendChild(needleEngine);
+        constructor() {
+            super();
+            this.attachShadow({ mode: 'open' });
+            const template = document.createElement('template');
+            template.innerHTML = \`
+                <style>
+                    :host {
+                        position: relative;
+                        display: block;
+                        width: max(360px 100%);
+                        height: max(240px, 100%);
+                        margin: 0;
+                        padding: 0;
+                    }
+                    needle-engine {
+                        position: absolute;
+                        top: 0;
+                        left: 0;
+                        width: 100%;
+                        height: 100%;
+                    }
+                </style>
+            \`;
+            this.shadowRoot.appendChild(template.content.cloneNode(true));
+
+            const script = document.createElement('script');
+            script.type = 'module';
+            const url = new URL('.', import.meta.url);
+            this.basePath = this.getAttribute('base-path') || \`\${url.protocol}//\${url.host}\${url.pathname}\`;
+            while(this.basePath.endsWith('/')) {
+                this.basePath = this.basePath.slice(0, -1);
+            }
+            script.src = this.getAttribute('script-src') || \`\${this.basePath}/${filepath}\`;
+            this.shadowRoot.appendChild(script);
+
+            this.needleEngine = document.createElement('needle-engine');
+            this.updateAttributes();
+            this.shadowRoot.appendChild(this.needleEngine);
+
+            console.debug(this.basePath, script.src, this.needleEngine.getAttribute("src"));
+        }
 
-        console.debug(basePath, script.src, needleEngine.getAttribute("src"));
-    }
+        onConnectedCallback() {
+            console.debug('NeedleEmbed connected to the DOM');
+        }
 
-    onConnectedCallback() {
-        console.debug('NeedleEmbed connected to the DOM');
-    }
+        disconnectedCallback() {
+            console.debug('NeedleEmbed disconnected from the DOM');
+        }
+        
+        attributeChangedCallback(name, oldValue, newValue) {
+            console.debug(\`NeedleApp attribute changed: \${name} from \${oldValue} to \${newValue}\`);
+            this.updateAttributes();
+        }
 
-    disconnectedCallback() {
-        console.debug('NeedleEmbed disconnected from the DOM');
-    }
-}
+        updateAttributes() {
+            console.debug("NeedleApp updating attributes");
+            
+            const src = this.getAttribute('src') || ${src?.length ? `\`\${this.basePath}/${src}\`` : null};
+            if(src) this.needleEngine.setAttribute("src", src);
+            else this.needleEngine.removeAttribute("src");
 
+            for(const attr of knownAttributes) {
+                
+                if(attr === "src") continue; // already handled above
 
-if (!customElements.get('${componentName}')) {
-    console.debug("Defining ${componentName}");
-    customElements.define('${componentName}', ${className});
+                if(this.hasAttribute(attr)) {
+                    this.needleEngine.setAttribute(attr, this.getAttribute(attr));
+                }
+                else {
+                    this.needleEngine.removeAttribute(attr);    
+                }
+            }
+        }
+    });
+}
+else {
+    console.warn(\`needle-app <\${componentName}> already defined.\`);
 }
 `
 }

package/src/engine/js-extensions/Object3D.ts

@@ -157,6 +157,14 @@ declare module 'three' {
          * Added by Needle Engine.
          */
         get worldUp(): Vector3;
+
+
+        /**
+         * Check if the given object is contained in the hierarchy of this object or if it's the same object.
+         * @param object The object to check.
+         * @returns True if the object is contained in the hierarchy, false otherwise.
+         */
+        contains(object: Object3D | null | undefined): boolean;
     }
 }
 
@@ -356,5 +364,21 @@ if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldUp")) {
 
 
 
+if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "contains")) {
+    Object.defineProperty(Object3D.prototype, "contains", {
+        value: function (object: Object3D | null | undefined): boolean {
+            if (!object) return false;
+            if (this === object) return true;
+            for (const child of this.children) {
+                if (child.contains(object)) return true;
+            }
+            return false;
+        }
+    });
+}
+
+
+
+
 // do this after adding the component extensions
 registerPrototypeExtensions(Object3D);

package/src/engine-components/Collider.ts

@@ -16,7 +16,13 @@ import { Rigidbody } from "./RigidBody.js";
 /**
  * Collider is the base class for all colliders. A collider is a physical shape that is used to detect collisions with other objects in the scene.  
  * Colliders are used in combination with a {@link Rigidbody} to create physical interactions between objects.  
- * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.
+ * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.  
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
+ * 
  * @category Physics  
  * @group Components
  */
@@ -112,6 +118,11 @@ export class Collider extends Behaviour implements ICollider {
 /**
  * SphereCollider represents a sphere-shaped collision volume.
  * Useful for objects that are roughly spherical in shape or need a simple collision boundary.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */
@@ -158,6 +169,11 @@ export class SphereCollider extends Collider implements ISphereCollider {
 /**
  * BoxCollider represents a box-shaped collision volume.
  * Ideal for rectangular objects or objects that need a simple cuboid collision boundary.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */
@@ -260,6 +276,11 @@ export class BoxCollider extends Collider implements IBoxCollider {
 /**
  * MeshCollider creates a collision shape from a mesh geometry.
  * Allows for complex collision shapes that match the exact geometry of an object.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */
@@ -343,6 +364,11 @@ export class MeshCollider extends Collider {
 /**
  * CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).
  * Ideal for character controllers and objects that need a rounded collision shape.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */

package/src/engine-components/ContactShadows.ts

@@ -44,10 +44,19 @@ type FitParameters = {
 // - node can simply be scaled in Y to adjust max. ground height
 
 /**
- * ContactShadows is a component that allows to display contact shadows in the scene.
+ * ContactShadows is a component that allows to display contact shadows in the scene. It has options for darkness, opacity and blur of the shadows.  
+ * 
+ * - Example: https://samples.needle.tools/contact-shadows
+ * 
+ * ## Usage
+ * You can use {@link ContactShadows.auto} to automatically create a ContactShadows instance for the scene or you can add the component to an object in the scene. Note that the scale of the object will be used to define the size of the shadow area.  
+ * 
+ * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
+ * 
+ * 
  * @category Rendering
  * @group Components
- */
+*/
 export class ContactShadows extends Behaviour {
 
     private static readonly _instances: Map<Context, ContactShadows> = new Map();
@@ -362,8 +371,7 @@ export class ContactShadows extends Behaviour {
             !this.depthMaterial || !this.shadowCamera ||
             !this.blurPlane || !this.shadowGroup || !this.plane ||
             !this.horizontalBlurMaterial || !this.verticalBlurMaterial) {
-            if (debug)
-                console.error("ContactShadows: not initialized yet");
+            if (debug) console.error("ContactShadows: not initialized yet");
             return;
         }
 

package/src/engine-components/DropListener.ts

@@ -1,23 +1,22 @@
-import { AxesHelper, Box3, Cache, Object3D, Vector2, Vector3 } from "three";
+import { Box3, Object3D, Vector2, Vector3 } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
 import { AnimationUtils } from "../engine/engine_animation.js";
-import { addComponent } from "../engine/engine_components.js";
 import { Context } from "../engine/engine_context.js";
 import { destroy } from "../engine/engine_gameobject.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { getLoader } from "../engine/engine_gltf.js";
 import { BlobStorage } from "../engine/engine_networking_blob.js";
 import { PreviewHelper } from "../engine/engine_networking_files.js";
-import { generateSeed, InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
+import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { fitObjectIntoVolume, getBoundingBox, placeOnSurface } from "../engine/engine_three_utils.js";
-import { IGameObject, Model, Vec3 } from "../engine/engine_types.js";
+import { Model, Vec3 } from "../engine/engine_types.js";
 import { getParam, setParamWithoutReload } from "../engine/engine_utils.js";
 import { determineMimeTypeFromExtension } from "../engine/engine_utils_format.js";
-import { Animation } from "./Animation.js";
 import { Behaviour } from "./Component.js";
 import { EventList } from "./EventList.js";
+import { Renderer } from "./Renderer.js";
 
 /**
  * Debug mode can be enabled with the URL parameter `?debugdroplistener`, which
@@ -116,6 +115,8 @@ const blobKeyName = "blob";
  * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
  * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
  * 
+ * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
+ * 
  * The following events are dispatched by the DropListener:
  * - **object-added** - dispatched when a new object is added to the scene
  * - **file-dropped** - dispatched when a file is dropped into the scene
@@ -214,7 +215,14 @@ export class DropListener extends Behaviour {
     }
 
 
-
+    awake() {
+        for (const ch of this.gameObject.children) {
+            if (this.dropArea && ch.contains(this.dropArea)) {
+                continue;
+            }
+            this._addedObjects.push(ch);
+        }
+    }
 
     // #region internals
 
@@ -223,7 +231,15 @@ export class DropListener extends Behaviour {
         this.context.renderer.domElement.addEventListener("dragover", this.onDrag);
         this.context.renderer.domElement.addEventListener("drop", this.onDrop);
         window.addEventListener("paste", this.handlePaste);
-        this.context.connection.beginListen("droplistener", this.onNetworkEvent)
+        this.context.connection.beginListen("droplistener", this.onNetworkEvent);
+        if (isDevEnvironment()) {
+            if (this.dropArea) {
+                const anyRenderer = this.dropArea.getComponentInChildren(Renderer);
+                if (!anyRenderer) {
+                    console.warn("[DropListener] The assigned DropArea does not seem to have a renderer/mesh. Drag and Drop events will not be detected.");
+                }
+            }
+        }
     }
     /** @internal */
     onDisable(): void {
@@ -287,6 +303,7 @@ export class DropListener extends Behaviour {
      * @param evt The drag event
      */
     private onDrag = (evt: DragEvent) => {
+        if(debug) console.debug("DropListener Drag", evt, this.context.connection.allowEditing);
         if (this.context.connection.allowEditing === false) return;
         // necessary to get drop event
         evt.preventDefault();
@@ -298,9 +315,9 @@ export class DropListener extends Behaviour {
      * @param evt The drop event
      */
     private onDrop = async (evt: DragEvent) => {
+        if (debug) console.debug("DropListener Drop", evt, this.context.connection.allowEditing);
         if (this.context.connection.allowEditing === false) return;
 
-        if (debug) console.log(evt);
         if (!evt?.dataTransfer) return;
         // If the event is marked as handled for droplisteners then ignore it
         if (evt["droplistener:handled"]) return;
@@ -473,7 +490,7 @@ export class DropListener extends Behaviour {
         if (doDestroy) {
             for (const prev of this._addedObjects) {
                 if (prev.parent === this.gameObject) {
-                    destroy(prev, true, true);
+                    prev.destroy();
                 }
             }
         }
@@ -596,24 +613,28 @@ export class DropListener extends Behaviour {
      * @returns True if the drop is valid (either no drop area is set or the drop occurred inside it)
      */
     private testIfIsInDropArea(ctx: DropContext): boolean {
+        const screenPoint = this.context.input.convertScreenspaceToRaycastSpace(ctx.screenposition.clone());
+        const hits = this.context.physics.raycast({
+            screenPoint,
+            recursive: true,
+            testObject: obj => {
+                // Ignore hits on the already added objects, they don't count as part of the dropzone
+                if (this._addedObjects.some(o => o.contains(obj))) return false;
+                return true;
+            }
+        });
+        if (!hits.length) {
+            if (isDevEnvironment()) console.log(`Dropped outside of drop area for DropListener \"${this.name}\".`);
+            return false;
+        }
+
+        const hit = hits[0];
         if (this.dropArea) {
-            const screenPoint = this.context.input.convertScreenspaceToRaycastSpace(ctx.screenposition.clone());
-            const hits = this.context.physics.raycast({
-                targets: [this.dropArea],
-                screenPoint,
-                recursive: true,
-                testObject: obj => {
-                    // Ignore hits on the already added objects, they don't count as part of the dropzone
-                    if (this._addedObjects.includes(obj)) return false;
-                    return true;
-                }
-            });
-            if (!hits.length) {
-                if (isDevEnvironment()) console.log(`Dropped outside of drop area for DropListener \"${this.name}\".`);
-                return false;
+            if (this.dropArea.contains(hit.object)) {
+                return true;
             }
         }
-        return true;
+        return false;
     }
 
 }

package/src/engine-components/Duplicatable.ts

@@ -12,8 +12,8 @@ import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.
 import { ObjectRaycaster } from "./ui/Raycaster.js";
 
 /**
- * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the GameObject.  
- * It implements the {@link IPointerEventHandler} interface and can be used to expose duplication to the user in the editor without writing code.
+ * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.   
+ *  
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/EventList.ts

@@ -97,7 +97,24 @@ export class EventListEvent<TArgs extends any> extends Event { //implements Arra
 
 
 /**
- * The EventList is a class that can be used to create a list of event listeners that can be invoked
+ * The EventList is a class that can be used to create a list of event listeners that can be invoked.  
+ * 
+ * @example
+ * ```ts
+ * // create an event list
+ * const onClick = new EventList<(event: MouseEvent) => void>();
+ * 
+ * // add an event listener
+ * onClick.addEventListener((event) => {
+ *   console.log("Clicked!", event);
+ * });
+ * 
+ * // invoke the event list
+ * onClick.invoke(new MouseEvent("click"));
+ * ```
+ * 
+ * @category Events
+ * @group Utilities
  */
 export class EventList<TArgs extends any = any> implements IEventList {
 

package/src/engine-components/GroundProjection.ts

@@ -10,7 +10,10 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debuggroundprojection");
 
 /**
- * GroundProjectedEnv creates a ground projection of the current environment map.  
+ * GroundProjectedEnv creates a ground projection of the current environment map.    
+ * 
+ * - Example https://engine.needle.tools/samples/ground-projection
+ * 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/Interactable.ts

@@ -10,6 +10,9 @@ export class UsageMarker extends Behaviour
     public usedBy: any = null;
 }
 
-
+/**
+ * An empty component that can be used to mark an object as interactable.
+ * @group Components
+ */
 /** @deprecated */
 export class Interactable extends Behaviour {}

package/src/engine-components/OrbitControls.ts

@@ -255,7 +255,12 @@ export class OrbitControls extends Behaviour implements ICameraController {
      * @default 1
      */
     @serializable()
-    targetLerpDuration = 1;
+    get targetLerpDuration() { return this._lookTargetLerpDuration; }
+    set targetLerpDuration(v) { this._lookTargetLerpDuration = v; }
+    private _lookTargetLerpDuration: number = 1;
+
+    @serializable(Object3D)
+    targetBounds: Object3D | null = null;
 
     /**
      * Rotate the camera left (or right) by the specified angle in radians.   
@@ -326,7 +331,6 @@ export class OrbitControls extends Behaviour implements ICameraController {
     private _lookTargetStartPosition: Vector3 = new Vector3();
     private _lookTargetEndPosition: Vector3 = new Vector3();
     private _lookTargetLerp01: number = 0;
-    private _lookTargetLerpDuration: number = 0;
 
     private _cameraLerpActive: boolean = false;
     private _cameraStartPosition: Vector3 = new Vector3();
@@ -685,6 +689,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
             }
         }
 
+        if (this.targetBounds) {
+            // #region target bounds
+            const targetVector = this._controls.target;
+            const boundsCenter = this.targetBounds.worldPosition;
+            const boundsHalfSize = getTempVector(this.targetBounds.worldScale).multiplyScalar(0.5);
+            const min = getTempVector(boundsCenter).sub(boundsHalfSize);
+            const max = getTempVector(boundsCenter).add(boundsHalfSize);
+            const newTarget = getTempVector(this._controls.target).clamp(min, max);
+            const duration = .1;
+            if (duration <= 0) targetVector.copy(newTarget);
+            else targetVector.lerp(newTarget, this.context.time.deltaTime / duration);
+            if (this._lookTargetLerpActive) {
+                if (duration <= 0) this._lookTargetEndPosition.copy(newTarget);
+                else this._lookTargetEndPosition.lerp(newTarget, this.context.time.deltaTime / (duration * 5));
+            }
+            if (debug) {
+                Gizmos.DrawWireBox(boundsCenter, boundsHalfSize.multiplyScalar(2), 0xffaa00);
+            }
+        }
+
 
         if (this._controls) {
             if (this.debugLog)
@@ -1000,7 +1024,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     */
     fitCamera(options?: OrbitFitCameraOptions);
     /** @deprecated Use fitCamera(options) */
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);    
+    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
     fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | OrbitFitCameraOptions, options?: OrbitFitCameraOptions): void {
 
 

package/src/engine-components/RigidBody.ts

@@ -134,7 +134,12 @@ class TransformWatch {
 }
 
 /**
- * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene. 
+ * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.   
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation
+ * 
  * @category Physics 
  * @group Components
  */