@needle-tools/engine 3.36.3-beta → 3.36.4-beta

package/src/engine/engine_three_utils.ts

@@ -1,5 +1,5 @@
-import { AnimationAction, Euler, Mesh,Object3D, PerspectiveCamera, PlaneGeometry, Quaternion, Scene, Texture, Uniform, Vector3 } from "three";
-import { ShaderMaterial,WebGLRenderer } from "three";
+import { AnimationAction, Euler, Mesh, Object3D, PerspectiveCamera, PlaneGeometry, Quaternion, Scene, Texture, Uniform, Vector3 } from "three";
+import { ShaderMaterial, WebGLRenderer } from "three";
 
 import { Mathf } from "./engine_math.js"
 import { CircularBuffer } from "./engine_utils.js";
@@ -13,6 +13,7 @@ export function slerp(vec: Vector3, end: Vector3, t: number) {
 }
 
 const flipYQuat: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
+
 export function lookAtInverse(obj: Object3D, target: Vector3) {
 
     obj.lookAt(target);
@@ -50,6 +51,14 @@ export function lookAtObject(object: Object3D, target: Object3D, keepUpDirection
 
 
 const _tempVecs = new CircularBuffer(() => new Vector3(), 100);
+
+/** Gets a temporary vector. If a vector is passed in it will be copied to the temporary vector    
+ * Temporary vectors are cached and reused internally. Don't store them!  
+ * @param vecOrX the vector to copy or the x value
+ * @param y the y value
+ * @param z the z value
+ * @returns a temporary vector
+ */
 export function getTempVector(vecOrX?: Vector3 | number | DOMPointReadOnly, y?: number, z?: number) {
     const vec = _tempVecs.get();
     if (vecOrX instanceof Vector3) vec.copy(vecOrX);
@@ -62,6 +71,13 @@ export function getTempVector(vecOrX?: Vector3 | number | DOMPointReadOnly, y?:
     return vec;
 }
 const _tempQuats = new CircularBuffer(() => new Quaternion(), 100);
+
+/**
+ * Gets a temporary quaternion. If a quaternion is passed in it will be copied to the temporary quaternion  
+ * Temporary quaternions are cached and reused internally. Don't store them!
+ * @param value the quaternion to copy
+ * @returns a temporary quaternion
+ */
 export function getTempQuaternion(value?: Quaternion | DOMPointReadOnly) {
     const val = _tempQuats.get();
     if (value instanceof Quaternion) val.copy(value);
@@ -73,6 +89,13 @@ export function getTempQuaternion(value?: Quaternion | DOMPointReadOnly) {
 const _worldPositions = new CircularBuffer(() => new Vector3(), 100);
 const _lastMatrixWorldUpdateKey = Symbol("lastMatrixWorldUpdateKey");
 
+/**
+ * Get the world position of an object
+ * @param obj the object to get the world position from
+ * @param vec a vector to store the result in. If not passed in a temporary vector will be used
+ * @param updateParents if true the parents will be updated before getting the world position
+ * @returns the world position
+ */
 export function getWorldPosition(obj: Object3D, vec: Vector3 | null = null, updateParents: boolean = true): Vector3 {
     const wp = vec ?? _worldPositions.get();
     if (!obj) return wp.set(0, 0, 0);
@@ -87,20 +110,34 @@ export function getWorldPosition(obj: Object3D, vec: Vector3 | null = null, upda
     return wp;
 }
 
-export function setWorldPosition(obj: Object3D, val: Vector3) {
-    if (!obj) return;
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param val the world position to set
+ */
+export function setWorldPosition(obj: Object3D, val: Vector3): Object3D {
+    if (!obj) return obj;
     const wp = _worldPositions.get();
     if (val !== wp)
         wp.copy(val);
     const obj2 = obj?.parent ?? obj;
     obj2.worldToLocal(wp);
     obj.position.set(wp.x, wp.y, wp.z);
+    return obj;
 }
 
-export function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number) {
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param x the x position
+ * @param y the y position
+ * @param z the z position
+ */
+export function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number): Object3D {
     const wp = _worldPositions.get();
     wp.set(x, y, z);
     setWorldPosition(obj, wp);
+    return obj;
 }
 
 
@@ -254,7 +291,7 @@ export function logHierarchy(root: Object3D | null | undefined, collapsible: boo
 
 export function getParentHierarchyPath(obj: Object3D): string {
     let path = obj?.name || "";
-    if(!obj) return path;
+    if (!obj) return path;
     let parent = obj.parent;
     while (parent) {
         path = parent.name + "/" + path;
@@ -278,6 +315,9 @@ export function isAnimationAction(obj: object) {
 
 
 
+/**
+ * Utility class to perform various graphics operations like copying textures to canvas
+ */
 export class Graphics {
     private static planeGeometry = new PlaneGeometry(2, 2, 1, 1);
     private static renderer: WebGLRenderer | undefined = undefined;
@@ -300,6 +340,9 @@ export class Graphics {
     }`;
     private static blipMaterial: ShaderMaterial | undefined = undefined;
 
+    /**
+     * Create a blit material for copying textures
+     */
     static createBlitMaterial(fragment: string): ShaderMaterial {
         return new ShaderMaterial({
             uniforms: { map: new Uniform(null) },
@@ -309,7 +352,13 @@ export class Graphics {
     }
     private static mesh: Mesh | undefined = undefined;
 
-    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial) {
+    /** 
+     * Copy a texture to a new texture
+     * @param texture the texture to copy
+     * @param blitMaterial the material to use for copying (optional)
+     * @returns the newly created, copied texture
+    */
+    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial): Texture {
         const material = blitMaterial ?? this.blipMaterial!;
         material.uniforms.map.value = texture;
         material.needsUpdate = true;

package/src/engine/engine_types.ts

@@ -320,6 +320,9 @@ export type Vec4 = {
 
 const contactsVectorBuffer = new CircularBuffer(() => new Vector3(), 20);
 
+/**
+ * Holds information about physics contacts 
+ */
 export class ContactPoint {
 
     private readonly _point: Vec3;
@@ -350,6 +353,7 @@ export class ContactPoint {
         return target.set(this._tangentVelocity.x, this._tangentVelocity.y, this._tangentVelocity.z);
     }
 
+    /** @internal */
     constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number, tangentVelocity: Vec3) {
         this._point = point;
         this.distance = dist;
@@ -360,12 +364,15 @@ export class ContactPoint {
     }
 }
 
-/// all info in here must be readonly because the object is only created once per started collision
+/**
+ * Holds information about a collision event. Includes a list of contact points and the colliders involved
+ */
 export class Collision {
 
     /** The contact points of this collision. Contains information about positions, normals, distance, friction, impulse... */
     readonly contacts: ContactPoint[];
 
+    /** @internal */
     constructor(obj: IGameObject, otherCollider: ICollider, contacts: ContactPoint[]) {
         this.me = obj;
         this._collider = otherCollider;

package/src/engine/engine_util_decorator.ts

@@ -96,8 +96,9 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
 
 
 
-/** experimental attribute - use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).
- * Return false to prevent the original method from running.
+/** Experimental attribute  
+ * Use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).  
+ * Return false to prevent the original method from running.  
  */
 export const prefix = function <T>(type: Constructor<T>) {
     return function (target: IComponent | any, _propertyKey: string | { name: string }, _PropertyDescriptor: PropertyDescriptor) {

package/src/engine/engine_utils.ts

@@ -319,10 +319,12 @@ export function resolveUrl(source: SourceIdentifier | undefined, uri: string): s
     if (pathIndex >= 0) {
         // Take the source uri as the base path
         const basePath = source.substring(0, pathIndex + 1);
+        // make sure we don't have double slashes
+        while (basePath.endsWith("/") && uri.startsWith("/")) uri = uri.substring(1);
         // Append the relative uri
         const newUri = basePath + uri;
         // newUri = new URL(newUri, globalThis.location.href).href;
-        if (debugGetPath) console.log("source:", source, "- changed uri \nfrom", uri, "\n→ ", newUri, "\n" + basePath);
+        if (debugGetPath) console.log("source:", source, "changed uri \nfrom", uri, "\nto ", newUri, "\nbasePath: " + basePath);
         return newUri;
     }
     return uri;

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -34,7 +34,7 @@ export class NeedleMenu {
     private readonly _spatialMenu: NeedleSpatialMenu;
 
     constructor(context: Context) {
-        this._menu = NeedleMenuElement.getOrCreate(context.domElement);
+        this._menu = NeedleMenuElement.getOrCreate(context.domElement, context);
         this._context = context;
         this._spatialMenu = new NeedleSpatialMenu(context, this._menu);
         window.addEventListener("message", this.onPostMessage);
@@ -160,7 +160,7 @@ export class NeedleMenuElement extends HTMLElement {
         return document.createElement(elementName, { is: elementName });
     }
 
-    static getOrCreate(domElement: HTMLElement) {
+    static getOrCreate(domElement: HTMLElement, context: Context) {
         let element = domElement.querySelector(elementName) as NeedleMenuElement | null;
         if (!element && domElement.shadowRoot) {
             element = domElement.shadowRoot.querySelector(elementName);
@@ -168,6 +168,7 @@ export class NeedleMenuElement extends HTMLElement {
         if (!element) {
             element = NeedleMenuElement.create() as NeedleMenuElement;
             element._domElement = domElement;
+            element._context = context;
             if (domElement.shadowRoot)
                 domElement.shadowRoot.appendChild(element);
             else
@@ -177,6 +178,7 @@ export class NeedleMenuElement extends HTMLElement {
     }
 
     private _domElement: HTMLElement | null = null;
+    private _context: Context | null = null;
 
     constructor() {
         super();
@@ -414,6 +416,11 @@ export class NeedleMenuElement extends HTMLElement {
         });
 
 
+
+        let context = this._context;
+        // we need to assign it in the timeout because the reference is set *after* the constructor did run
+        setTimeout(() => context = this._context);
+
         // watch changes
         let showInterval = -1;
         const rootObserver = new MutationObserver(mutations => {
@@ -425,7 +432,12 @@ export class NeedleMenuElement extends HTMLElement {
                 if (!hasProLicense()) {
                     clearInterval(showInterval);
                     showInterval = setInterval(() => {
-                        if (parent != this._domElement?.shadowRoot)
+                        if (context?.isInAR && context.arOverlayElement) {
+                            if (parent != context.arOverlayElement) {
+                                context.arOverlayElement.appendChild(this);
+                            }
+                        }
+                        else if (parent != this._domElement?.shadowRoot)
                             this._domElement?.shadowRoot?.appendChild(this);
                         this.style.display = "flex";
                         this.style.visibility = "visible";

package/src/engine-components/Component.ts

@@ -447,7 +447,7 @@ export abstract class Component implements IComponent, EventTarget,
         this.__destroyed = true;
     }
     /** called when you decorate fields with the @validate() decorator
-     * @param field the name of the field that was changed
+     * @param prop the name of the field that was changed
      */
     onValidate?(prop?: string): void;
 

package/src/engine-components/ContactShadows.ts

@@ -1,4 +1,4 @@
-import { CustomBlending, DoubleSide, Group, Matrix4, MaxEquation, Mesh, MeshBasicMaterial, MeshDepthMaterial, MinEquation, OrthographicCamera, PlaneGeometry, ShaderMaterial, WebGLRenderTarget } from "three";
+import { CustomBlending, DoubleSide, FrontSide, Group, Matrix4, MaxEquation, Mesh, MeshBasicMaterial, MeshDepthMaterial, MinEquation, Object3D, OrthographicCamera, PlaneGeometry, RenderItem, ShaderMaterial, WebGLRenderTarget } from "three";
 import { HorizontalBlurShader } from 'three/examples/jsm/shaders/HorizontalBlurShader.js';
 import { VerticalBlurShader } from 'three/examples/jsm/shaders/VerticalBlurShader.js';
 
@@ -214,11 +214,19 @@ export class ContactShadows extends Behaviour {
 
         const prevXRState = renderer.xr.enabled;
         renderer.xr.enabled = false;
+        
+        const list = renderer.renderLists.get(scene, 0);
+        const prev = list.transparent;
+        list.transparent = [];
 
         // render to the render target to get the depths
         renderer.setRenderTarget(this.renderTarget);
+        renderer.clear();
+
         renderer.render(scene, this.shadowCamera);
 
+        list.transparent = prev;
+        
         // for the shearing idea
         // this.shadowCamera.projectionMatrix.copy(mat);
 

package/src/engine-components/OrbitControls.ts

@@ -639,10 +639,17 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 expandByObjectRecursive(child);
             }
         }
+        let hasAnyObject = false;
         for (const object of objects) {
+            if (!object) continue;
+            hasAnyObject = true;
             object.updateMatrixWorld();
             expandByObjectRecursive(object);
         }
+        if (!hasAnyObject) {
+            console.warn("No objects to fit camera to...");
+            return;
+        }
 
         camera.updateMatrixWorld();
         camera.updateProjectionMatrix();

package/src/engine-components/SceneSwitcher.ts

@@ -1,6 +1,6 @@
 import { Object3D } from "three";
 
-import { AssetReference } from "../engine/engine_addressables.js";
+import { Addressables, AssetReference } from "../engine/engine_addressables.js";
 import { registerObservableAttribute } from "../engine/engine_element_extras.js";
 import { InputEvents } from "../engine/engine_input.js";
 import { isLocalNetwork } from "../engine/engine_networking_utils.js";
@@ -64,6 +64,7 @@ export interface ISceneEventListener {
  * - `loadscene-start`: Called when a scene starts loading
  * - `loadscene-finished`: Called when a scene finished loading
  * - `progress`: Called when a scene is loading and the progress changes
+ * - `scene-opened`: Called when a scene is loaded and added to the SceneSwitcher's GameObject
  * @example
  * ```ts
  * sceneSwitcher.addEventListener("loadscene-start", (e) => {
@@ -75,6 +76,9 @@ export interface ISceneEventListener {
  * sceneSwitcher.addEventListener("progress", (e) => {
  *  console.log("Loading progress", e.loaded, e.total);
  * });
+ * sceneSwitcher.addEventListener("scene-opened", (e) => {
+ * console.log("Scene opened", e.detail.scene.uri);
+ * });
  * ```
  * 
  */
@@ -159,10 +163,14 @@ export class SceneSwitcher extends Behaviour {
 
     private _preloadScheduler?: PreLoadScheduler;
 
+    /** @internal */
     awake(): void {
+        if (this.scenes === undefined) this.scenes = [];
+        
         if (debug) console.log("SceneSwitcher", this);
     }
 
+    /** @internal */
     async onEnable() {
         globalThis.addEventListener("popstate", this.onPopState);
         this.context.input.addEventListener(InputEvents.KeyDown, this.onInputKeyDown);
@@ -210,6 +218,7 @@ export class SceneSwitcher extends Behaviour {
         }
     }
 
+    /** @internal */
     onDisable(): void {
         globalThis.removeEventListener("popstate", this.onPopState);
         this.context.input.removeEventListener(InputEvents.KeyDown, this.onInputKeyDown);
@@ -288,14 +297,58 @@ export class SceneSwitcher extends Behaviour {
         }
     }
 
+    /**
+     * Add a scene to the SceneSwitcher.     
+     * If the scene is already added it will be added again.
+     * @param urlOrAssetReference The url of the scene or an AssetReference to the scene  
+     * @returns The AssetReference of the scene that was added
+     * @example
+     * ```ts
+     * // adding a scene:
+     * sceneSwitcher.addScene("scene1.glb");
+     * // add another scene and load it:
+     * const scene2 = sceneSwitcher.addScene("scene2.glb");
+     * sceneSwitcher.switchScene(scene2).then(res => { console.log("Scene loaded", res); });
+     * ```
+     */
+    addScene(urlOrAssetReference: string | AssetReference): AssetReference {
+        if (typeof urlOrAssetReference === "string") {
+            let assetReference = this.context.addressables.findAssetReference(urlOrAssetReference);
+            if (!assetReference) {
+                assetReference = new AssetReference(urlOrAssetReference);
+                this.context.addressables.registerAssetReference(assetReference);
+            }
+            this.scenes.push(assetReference);
+            return assetReference;
+        }
+
+        this.scenes.push(urlOrAssetReference);
+        return urlOrAssetReference;
+    }
+
+    /**
+     * Load the next scene in the scenes array ({@link this.currentIndex} + 1)  
+     * If the current scene is the last scene in the array and {@link this.clamp} is disabled then the first scene will be loaded.
+     * @returns a promise that resolves to true if the scene was loaded successfully    
+     */
     selectNext(): Promise<boolean> {
         return this.select(this._currentIndex + 1);
     }
 
+    /**
+     * Load the previous scene in the scenes array ({@link this.currentIndex} - 1)  
+     * If the current scene is the first scene in the array and {@link this.clamp} is disabled then the last scene will be loaded.
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     selectPrev(): Promise<boolean> {
         return this.select(this._currentIndex - 1);
     }
 
+    /**
+     * Load a scene by its index in the scenes array.
+     * @param index The index of the scene or a string that represents the scene uri (if the url is not known to the SceneSwitcher it will try to load the scene by its uri but it won't be added to the current scenes array. Use {@link addScene} to add a scene to the SceneSwitcher)  
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     select(index: number | string): Promise<boolean> {
         if (debug) console.log("select", index);
 
@@ -341,6 +394,19 @@ export class SceneSwitcher extends Behaviour {
     private __lastSwitchScene?: AssetReference;
     private __lastSwitchScenePromise?: Promise<boolean>;
 
+    /**
+     * Switch to a scene by its AssetReference.  
+     * If the scene is already loaded it will be unloaded and the new scene will be loaded.  
+     * If the scene is already loading it will wait for the scene to be loaded.  
+     * If the scene is already loaded and the same scene is requested again it will return the same promise that was returned the first time the scene was requested.  
+     * @param scene The AssetReference of the scene to switch to
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     * @example
+     * ```ts
+     * const myAssetReference = new AssetReference("scene1.glb");
+     * sceneSwitcher.switchScene(myAssetReference).then(res => { console.log("Scene loaded", res); });
+     * ```
+     */
     async switchScene(scene: AssetReference): Promise<boolean> {
         if (!(scene instanceof AssetReference)) {
             const type = typeof scene;
@@ -444,6 +510,9 @@ export class SceneSwitcher extends Behaviour {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
+
+                const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
+                this.dispatchEvent(openedEvt);
                 return true;
             }
         }