@needle-tools/engine 3.32.6-alpha → 3.32.7-alpha

package/src/engine/xr/NeedleXRSession.ts

@@ -14,6 +14,7 @@ import { registerFrameEventCallback, unregisterFrameEventCallback } from "../eng
 import { isDestroyed } from "../engine_gameobject.js";
 import { TemporaryXRContext } from "./TempXRContext.js";
 import { Mathf } from "../engine_math.js";
+import { SceneTransition } from "./SceneTransition.js";
 
 export type NeedleXREventArgs = { xr: NeedleXRSession }
 export type SessionChangedEvt = (args: NeedleXREventArgs) => void;
@@ -1019,7 +1020,7 @@ export class NeedleXRSession implements INeedleXRSession {
 
     private onAfterRender = () => {
         this.onUpdateFade_PostRender();
-        
+
         // render spectator view if we're in VR using Link
         if (isDesktop()) {
             const renderer = this.context.renderer;
@@ -1200,71 +1201,25 @@ export class NeedleXRSession implements INeedleXRSession {
     }
 
     // TODO: for scene transitions (e.g. SceneSwitcher) where creating the scene might take a few moments we might want more control over when/how this fading occurs and how long the scene stays black
-    
+    private transition?: SceneTransition;
+
     /** Call to fade rendering to black for a short moment (the returned promise will be resolved when fully black)   
      * This can be used to mask scene transitions or teleportation
      * @returns a promise that is resolved when the screen is fully black
      * @example `fadeTransition().then(() => { <fully_black> })`
     */
     fadeTransition() {
-        if (this._transitionPromise) return this._transitionPromise;
-        this._requestedFadeValue = 1;
-        const promise = new Promise<void>(resolve => {
-            this._transitionResolve = resolve;
-        });
-        this._transitionPromise = promise;
-        return promise;
+        if (!this.transition) this.transition = new SceneTransition();
+        return this.transition.fadeTransition();
     }
 
-    private _requestedFadeValue: number = 0;
-    private _transitionPromise: Promise<void> | null = null;
-    private _transitionResolve: (() => void) | null = null;
-    private _fadeToColorQuad: Mesh | null = null;
-    private _fadeToColorMaterial!: MeshBasicMaterial;
-
     /** e.g. FadeToBlack */
     private updateFade(camera: Camera) {
-        if (!(camera instanceof PerspectiveCamera)) return;
-        if (!this._fadeToColorQuad || !this._fadeToColorMaterial) {
-            this._fadeToColorMaterial = new MeshBasicMaterial({
-                color: 0x000000,
-                transparent: true,
-                depthTest: false,
-                fog: false,
-                side: DoubleSide,
-            });
-            this._fadeToColorQuad = new Mesh(new PlaneGeometry(10, 10), this._fadeToColorMaterial);
-        }
-
-        // ensure that the quad is setup with the right properties
-        const quad = this._fadeToColorQuad;
-        const mat = this._fadeToColorMaterial;
-
-        // make sure the quad is in the scene
-        if (quad.parent !== camera && mat.opacity > 0) {
-            camera!.add(quad);
-        }
-        else if (mat.opacity === 0) {
-            quad.removeFromParent();
-        }
-        quad.layers.set(2);
-        quad.material = this._fadeToColorMaterial!;
-        quad.position.z = -1;
-        // perform the fade
-        const fadeValue = this._requestedFadeValue;
-        mat.opacity = Mathf.lerp(mat.opacity, fadeValue, this.context.time.deltaTime / .03);
-        // check if we're close enough to the desired value:
-        if (Math.abs(mat.opacity - fadeValue) <= .01) {
-            if (this._transitionResolve) {
-                this._transitionResolve();
-                this._transitionResolve = null;
-                this._transitionPromise = null;
-                this._requestedFadeValue = 0;
-            }
-        }
+        if (this.transition && camera instanceof PerspectiveCamera)
+            this.transition.update(camera, this.context.time.deltaTime);
     }
 
     private onUpdateFade_PostRender() {
-        this._fadeToColorQuad?.removeFromParent();
+        this.transition?.remove();
     }
 }

package/src/engine/xr/SceneTransition.ts

@@ -0,0 +1,76 @@
+import { Camera, DoubleSide, Mesh, MeshBasicMaterial, PlaneGeometry } from "three";
+import { Mathf } from "../engine_math.js";
+
+export class SceneTransition {
+
+    private readonly _fadeToColorQuad: Mesh;
+    private readonly _fadeToColorMaterial: MeshBasicMaterial;
+
+    constructor() {
+        this._fadeToColorMaterial = new MeshBasicMaterial({
+            color: 0x000000,
+            transparent: true,
+            depthTest: false,
+            fog: false,
+            side: DoubleSide,
+        });
+        this._fadeToColorQuad = new Mesh(new PlaneGeometry(10, 10), this._fadeToColorMaterial);
+    }
+
+    dispose() {
+        this._fadeToColorQuad.geometry.dispose();
+        this._fadeToColorMaterial.dispose();
+    }
+
+    update(camera: Camera, dt: number) {
+        const quad = this._fadeToColorQuad;
+        const mat = this._fadeToColorMaterial;
+
+        // make sure the quad is in the scene
+        if (quad.parent !== camera && mat.opacity > 0) {
+            camera.add(quad);
+        }
+        else if (mat.opacity === 0) {
+            quad.removeFromParent();
+        }
+        quad.layers.set(2);
+        quad.material = this._fadeToColorMaterial!;
+        quad.position.z = -1;
+        // perform the fade
+        const fadeValue = this._requestedFadeValue;
+        mat.opacity = Mathf.lerp(mat.opacity, fadeValue, dt / .03);
+
+        // check if we're close enough to the desired value:
+        if (Math.abs(mat.opacity - fadeValue) <= .01) {
+            if (this._transitionResolve) {
+                this._transitionResolve();
+                this._transitionResolve = null;
+                this._transitionPromise = null;
+                this._requestedFadeValue = 0;
+            }
+        }
+    }
+    remove() {
+        this._fadeToColorQuad.removeFromParent();
+    }
+
+    /** Call to fade rendering to black for a short moment (the returned promise will be resolved when fully black)   
+     * This can be used to mask scene transitions or teleportation
+     * @returns a promise that is resolved when the screen is fully black
+     * @example `fadeTransition().then(() => { <fully_black> })`
+    */
+    fadeTransition() {
+        if (this._transitionPromise) return this._transitionPromise;
+        this._requestedFadeValue = 1;
+        const promise = new Promise<void>(resolve => {
+            this._transitionResolve = resolve;
+        });
+        this._transitionPromise = promise;
+        return promise;
+    }
+
+
+    private _requestedFadeValue: number = 0;
+    private _transitionPromise: Promise<void> | null = null;
+    private _transitionResolve: (() => void) | null = null;
+}

package/src/engine-components/ui/EventSystem.ts

@@ -1,11 +1,10 @@
 import { RaycastOptions, RaycastTestObjectReturnType } from "../../engine/engine_physics.js";
 import { Behaviour, GameObject } from "../Component.js";
-import * as ThreeMeshUI from 'three-mesh-ui'
 import { Context } from "../../engine/engine_setup.js";
-import { type IPointerEventHandler, PointerEventData, hasPointerEventComponent } from "./PointerEvents.js";
+import { type IPointerEventHandler, PointerEventData, hasPointerEventComponent, IPointerUpHandler } from "./PointerEvents.js";
 import { ObjectRaycaster, Raycaster } from "./Raycaster.js";
 import { InputEvents, NEPointerEvent, PointerType } from "../../engine/engine_input.js";
-import { Object3D } from "three";
+import { Intersection, Object3D } from "three";
 import type { ICanvasGroup } from "./Interfaces.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { UIRaycastUtils } from "./RaycastUtils.js";
@@ -13,7 +12,7 @@ import { $shadowDomOwner } from "./BaseUIComponent.js";
 import { isDevEnvironment, showBalloonMessage } from "../../engine/debug/index.js";
 import { Mathf } from "../../engine/engine_math.js";
 import { isUIObject } from "./Utils.js";
-import { Gizmos } from "../../engine/engine_gizmos.js";
+import { IComponent } from "../../engine/engine_types.js";
 
 const debug = getParam("debugeventsystem");
 
@@ -187,12 +186,12 @@ export class EventSystem extends Behaviour {
             hasActiveUI: this.currentActiveMeshUIComponents.length > 0,
         }
 
-        this.dispatchEvent(new CustomEvent(EventSystemEvents.BeforeHandleInput, { detail: evt }))
+        this.dispatchEvent(new CustomEvent(EventSystemEvents.BeforeHandleInput, { detail: evt }));
 
-        // handle hit objects
-        this.handleIntersections(id, hits, data)
+        // then handle the intersections and call the callbacks on the regular objects
+        this.handleIntersections(id, hits, data);
 
-        this.dispatchEvent(new CustomEvent<AfterHandleInputEvent>(EventSystemEvents.AfterHandleInput, { detail: evt }))
+        this.dispatchEvent(new CustomEvent<AfterHandleInputEvent>(EventSystemEvents.AfterHandleInput, { detail: evt }));
     }
 
     private readonly _sortedHits: THREE.Intersection[] = [];
@@ -294,20 +293,38 @@ export class EventSystem extends Behaviour {
         return this._sortedHits;
     }
 
-    private handleIntersections(id: number, hits: THREE.Intersection[] | null | undefined, args: PointerEventData): boolean {
+    private assignHitInformation(args: PointerEventData, hit?: Intersection) {
+        if (!hit) {
+            args.point = undefined;
+            args.normal = undefined;
+            args.face = undefined;
+            args.distance = undefined;
+            args.instanceId = undefined;
+        }
+        else {
+            args.point = hit.point;
+            args.normal = hit.normal;
+            args.face = hit.face;
+            args.distance = hit.distance;
+            args.instanceId = hit.instanceId;
+        }
+    }
+
+    private handleIntersections(id: number, hits: Intersection[] | null | undefined, args: PointerEventData): boolean {
+
+        // first invoke captured pointers
+        this.assignHitInformation(args, hits?.[0]);
+        this.invokePointerCapture(args);
+
+
         if (hits?.length) {
             hits = this.sortCandidates(hits);
             for (const hit of hits) {
                 if (args.event.immediatePropagationStopped) {
                     return false;
                 }
-                const { object } = hit;
-                args.point = hit.point;
-                args.normal = hit.normal;
-                args.face = hit.face;
-                args.distance = hit.distance;
-                args.instanceId = hit.instanceId;
-                if (this.handleEventOnObject(object, args)) {
+                this.assignHitInformation(args, hit);
+                if (this.handleEventOnObject(hit.object, args)) {
                     return true;
                 }
             }
@@ -325,7 +342,7 @@ export class EventSystem extends Behaviour {
         // if it was up, it means it doesn't should notify things that it down on before
         if (args.isUp) {
             const pressedData = this.pressedByID.get(id);
-            pressedData?.handlers.forEach(h => h.onPointerUp?.call(h, args));
+            pressedData?.handlers.forEach(h => this.invokeOnPointerUp(args, h));
             this.pressedByID.delete(id);
         }
 
@@ -374,16 +391,11 @@ export class EventSystem extends Behaviour {
 
         // Event without pointer can't be handled
         if (args.pointerId === undefined) {
-            if (debug) console.warn("Event without pointer can't be handled", args);
+            if (debug) console.error("Event without pointer can't be handled", args);
             return false;
         }
 
-        // We want to call all event methods even if the event was used
-        // Used event can't be handled
-        // if (args.used) return false;
-
         // Correct the handled object to match the relevant object in shadow dom (?)
-        const originalObject = object;
         args.object = object;
 
         const parent = object.parent as any;
@@ -460,13 +472,10 @@ export class EventSystem extends Behaviour {
     /**
      * Propagate up in hiearchy and call the callback for each component that is possibly a handler
      */
-    private propagate(object: Object3D | null, args: PointerEventData, onComponent: (behaviour: Behaviour) => void) {
+    private propagate(object: Object3D | null, onComponent: (behaviour: Behaviour) => void) {
 
         while (true) {
 
-            // Propagate up the hierarchy
-            if (args.used) break;
-
             if (!object) break;
 
             GameObject.foreachComponent(object, comp => {
@@ -505,7 +514,7 @@ export class EventSystem extends Behaviour {
                 break;
         }
 
-        this.propagate(object, args, (behaviour) => {
+        this.propagate(object, (behaviour) => {
             const comp = behaviour as any;
 
             if (comp.interactable === false) return;
@@ -528,17 +537,20 @@ export class EventSystem extends Behaviour {
                     // So we can call the up event on the same handler 
                     // In a scenario where we Down on one object and Up on another
                     pressedEvent?.handlers.add(comp);
+
+                    this.handlePointerCapture(args, comp);
                 }
             }
 
             if (comp.onPointerMove) {
                 if (isMoving)
                     comp.onPointerMove(args);
+                    this.handlePointerCapture(args, comp);
             }
 
             if (args.isUp) {
                 if (comp.onPointerUp) {
-                    comp.onPointerUp(args);
+                    this.invokeOnPointerUp(args, comp);
 
                     // We don't want to call Up twice if we Down and Up on the same object
                     // But if we Down on one and Up on another we want to call Up on the first one as well
@@ -566,9 +578,7 @@ export class EventSystem extends Behaviour {
         // If user drags away from the object, then it doesn't get the UP event
         if (args.isUp) {
             pressedEvent?.handlers.forEach((handler) => {
-                if (handler.onPointerUp) {
-                    handler.onPointerUp(args);
-                }
+                this.invokeOnPointerUp(args, handler);
             });
 
             this.pressedByID.delete(args.pointerId);
@@ -580,7 +590,7 @@ export class EventSystem extends Behaviour {
      */
     private triggerOnExit(object: Object3D, args: PointerEventData, newObject: Object3D | null) {
 
-        this.propagate(object, args, (behaviour) => {
+        this.propagate(object, (behaviour) => {
             if (!behaviour.gameObject || behaviour.destroyed) return;
 
             const inst: any = behaviour;
@@ -597,6 +607,67 @@ export class EventSystem extends Behaviour {
         });
     }
 
+    /** handles onPointerUp - this will also release the pointerCapture */
+    private invokeOnPointerUp(evt: PointerEventData, handler: IPointerUpHandler) {
+        handler.onPointerUp?.call(handler, evt);
+        this.releasePointerCapture(evt.pointerId, handler);
+    }
+
+    /** the list of component handlers that requested pointerCapture for a specific pointerId */
+    private readonly _capturedPointer: { [pointerId: number]: IPointerEventHandler[] } = {};
+
+    /** check if the event was marked to be captured: if yes add the current component to the captured list */
+    private handlePointerCapture(evt: PointerEventData, comp: IPointerEventHandler) {
+        if (evt.z__pointer_ctured) {
+            evt.z__pointer_ctured = false;
+            // only the onPointerMove event is called with captured pointers so we don't need to add it to our list if it doesnt implement onPointerMove
+            if (comp.onPointerMove) {
+                const list = this._capturedPointer[evt.pointerId] || [];
+                list.push(comp);
+                this._capturedPointer[evt.pointerId] = list;
+            }
+            else {
+                if (isDevEnvironment())
+                    console.warn("PointerCapture was requested but the component doesn't implement onPointerMove. It will not receive any pointer events");
+            }
+        }
+        else if (evt.z__pointer_cture_rleased) {
+            evt.z__pointer_cture_rleased = false;
+            this.releasePointerCapture(evt.pointerId, comp);
+        }
+    }
+
+    /** removes the component from the pointer capture list */
+    releasePointerCapture(pointerId: number, component: IPointerEventHandler) {
+        if (this._capturedPointer[pointerId]) {
+            const i = this._capturedPointer[pointerId].indexOf(component);
+            if (i !== -1) {
+                this._capturedPointer[pointerId].splice(i, 1);
+            }
+        }
+    }
+    /** invoke the pointerMove event on all captured handlers */
+    private invokePointerCapture(evt: PointerEventData) {
+        if (evt.event.type === InputEvents.PointerMove) {
+            const pointerId = evt.pointerId;
+            const captured = this._capturedPointer[pointerId];
+            if (captured) {
+                for (let i = 0; i < captured.length; i++) {
+                    const handler = captured[i];
+                    // check if it was destroyed
+                    const comp = handler as IComponent;
+                    if (comp.destroyed) {
+                        captured.splice(i, 1);
+                        i--;
+                        continue;
+                    }
+                    // invoke pointer move
+                    handler.onPointerMove?.call(handler, evt);
+                }
+            }
+        }
+    }
+
     private readonly pointerEnterSymbol = Symbol("pointerEnter");
     private readonly pointerExitSymbol = Symbol("pointerExit");
 

package/src/engine-components/ui/PointerEvents.ts

@@ -5,13 +5,20 @@ import { GamepadButtonName, MouseButtonName } from "../../engine/engine_types.js
 
 export interface IInputEventArgs {
     get used(): boolean;
-    Use(): void;
-    StopPropagation?(): void;
+    use(): void;
+    stopImmediatePropagation?(): void;
 }
 
+/** This pointer event data object is passed to all event receivers that are currently active  
+ * It contains hit information if an object was hovered or clicked  
+ * If the event is received in onPointerDown or onPointerMove, you can call `setPointerCapture` to receive onPointerMove events even when the pointer has left the object until you call `releasePointerCapture` or when the pointerUp event happens  
+ * You can get additional information about the event or event source via the `event` property (of type `NEPointerEvent`)
+ */
 export class PointerEventData implements IInputEventArgs {
 
+    /** the original event */
     readonly event: NEPointerEvent;
+    /** the pointer identifier for this event */
     readonly pointerId: number;
     /** 
      * mouse button 0 === LEFT, 1 === MIDDLE, 2 === RIGHT 
@@ -20,25 +27,53 @@ export class PointerEventData implements IInputEventArgs {
     readonly buttonName: MouseButtonName | GamepadButtonName | undefined;
 
     private _used: boolean = false;
+    /** true when `use()` has been called */
     get used(): boolean {
         return this._used;
     }
 
+    /** mark this event to be used */
     use() {
+        if (this._used) return;
         this._used = true;
         if (this.pointerId !== undefined)
             this.input.setPointerUsed(this.pointerId);
     }
 
-    /** @deprecated use `stopImmediatePropagation` */
+    private _propagationStopped: boolean = false;
+    get propagationStopped() {
+        return this._propagationStopped;
+    }
+
+    /** Call this method to stop immediate propagation on the `event` object.   
+     * WARNING: this is currently equivalent to stopImmediatePropagation   
+     */
     stopPropagation() {
-        // we currently don't have a distinction between stopPropagation and stopImmediatePropagation
+        // we currently don't have a distinction between stopPropagation and stopImmediatePropagation  
+        this._propagationStopped = true;
         this.event.stopImmediatePropagation();
     }
+    /** Call this method to stop immediate propagation on the `event` object.   
+     */
     stopImmediatePropagation() {
+        this._propagationStopped = true;
         this.event.stopImmediatePropagation();
     }
 
+    /**@ignore internal flag, pointer captured (we dont want to see it in intellisense) */
+    z__pointer_ctured: boolean = false;
+    /** Call this method in `onPointerDown` or `onPointerMove` to receive onPointerMove events for this pointerId even when the pointer has left the object until you call `releasePointerCapture` or when the pointerUp event happens 
+    */
+    setPointerCapture() {
+        this.z__pointer_ctured = true;
+    }
+    /**@ignore internal flag, pointer capture released */
+    z__pointer_cture_rleased: boolean = false;
+    /** call this method in `onPointerDown` or `onPointerMove` to stop receiving onPointerMove events */
+    releasePointerCapture() {
+        this.z__pointer_cture_rleased = true;
+    }
+
 
     /** Who initiated this event */
     inputSource: Input | any;
@@ -67,7 +102,7 @@ export class PointerEventData implements IInputEventArgs {
 
     private input: Input;
 
-    constructor(pointerId: number, input: Input, event: NEPointerEvent) {        
+    constructor(pointerId: number, input: Input, event: NEPointerEvent) {
         this.pointerId = pointerId;
         this.event = event;
         this.input = input;