@needle-tools/engine 4.9.0-next.ce04b9f → 4.9.0

package/lib/engine-components/web/CursorFollow.js

@@ -7,14 +7,28 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getTempVector } from "../../engine/engine_three_utils.js";
 import { Behaviour } from "../Component.js";
+/**
+ * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ */
 export class CursorFollow extends Behaviour {
     /**
      * Damping for the movement, set to 0 for instant movement
      * @default 0
      */
     damping = 0;
+    /**
+     * If true, the initial distance to the camera is maintained when following the cursor.
+     * @default true
+     */
+    keepDistance = true;
+    awake() {
+        this._distance = -1;
+    }
     _distance = -1;
     updateDistance() {
+        if (this.keepDistance && this._distance !== -1) {
+            return;
+        }
         this._distance = this.gameObject.worldPosition.distanceTo(this.context.mainCamera.worldPosition);
     }
     /** @internal */
@@ -43,4 +57,7 @@ export class CursorFollow extends Behaviour {
 __decorate([
     serializable()
 ], CursorFollow.prototype, "damping", void 0);
+__decorate([
+    serializable()
+], CursorFollow.prototype, "keepDistance", void 0);
 //# sourceMappingURL=CursorFollow.js.map

package/lib/engine-components/web/CursorFollow.js.map

@@ -1 +1 @@
-{"version":3,"file":"CursorFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/CursorFollow.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,MAAM,OAAO,YAAa,SAAQ,SAAS;IAEvC;;;OAGG;IAEH,OAAO,GAAW,CAAC,CAAC;IAGZ,SAAS,GAAW,CAAC,CAAC,CAAC;IAC/B,cAAc;QACV,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACrG,CAAC;IAGD,gBAAgB;IAChB,MAAM;QACF,8DAA8D;QAC9D,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,yEAAyE;QACzE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACvC,MAAM,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;QAE5C,iDAAiD;QACjD,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC5E,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,CAAC;QAE7C,oDAAoD;QACpD,MAAM,WAAW,GAAG,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACpF,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE;YAClB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAClE,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,GAAG,CAAC;SACvC;aACI;YACD,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,WAAW,CAAC;SAC/C;IAEL,CAAC;CAEJ;AApCG;IADC,YAAY,EAAE;6CACK"}
+{"version":3,"file":"CursorFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/CursorFollow.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,SAAS;IAEvC;;;OAGG;IAEH,OAAO,GAAW,CAAC,CAAC;IAEpB;;;OAGG;IAEH,YAAY,GAAY,IAAI,CAAC;IAE7B,KAAK;QACD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACxB,CAAC;IAEO,SAAS,GAAW,CAAC,CAAC,CAAC;IAE/B,cAAc;QACV,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC,EAAE;YAC5C,OAAO;SACV;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACrG,CAAC;IAED,gBAAgB;IAChB,MAAM;QACF,8DAA8D;QAC9D,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,yEAAyE;QACzE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QACvC,MAAM,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;QAE5C,iDAAiD;QACjD,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC5E,YAAY,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,CAAC;QAE7C,oDAAoD;QACpD,MAAM,WAAW,GAAG,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACpF,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE;YAClB,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAClE,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,GAAG,CAAC;SACvC;aACI;YACD,IAAI,CAAC,UAAU,CAAC,aAAa,GAAG,WAAW,CAAC;SAC/C;IAEL,CAAC;CAEJ;AAjDG;IADC,YAAY,EAAE;6CACK;AAOpB;IADC,YAAY,EAAE;kDACc"}

package/lib/engine-components/web/ScrollFollow.d.ts

@@ -1,7 +1,32 @@
 import { Behaviour } from "../Component.js";
+import { EventList } from "../EventList.js";
+type ScrollFollowEvent = {
+    /** Event type */
+    type: "change";
+    /** Current scroll value */
+    value: number;
+    /** ScrollFollow component that raised the event */
+    component: ScrollFollow;
+    /** Call to prevent invocation of default (e.g. updating targets) */
+    preventDefault: () => void;
+    defaultPrevented: boolean;
+};
+/**
+ * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.
+ * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
+ *
+ * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/
+ */
 export declare class ScrollFollow extends Behaviour {
     /**
      * Target object(s) to follow the scroll position of the page. If null, the main camera is used.
+     *
+     * Supported target types:
+     * - PlayableDirector (timeline), the scroll position will be mapped to the timeline time
+     * - Animator, the scroll position will be set to a float parameter named "scroll"
+     * - Animation, the scroll position will be mapped to the animation time
+     * - AudioSource, the scroll position will be mapped to the audio time
+     * - Any object with a `scroll` property (number or function)
      */
     target: object[] | object | null;
     /**
@@ -9,19 +34,38 @@ export declare class ScrollFollow extends Behaviour {
      * @default 0
      */
     damping: number;
-    mode: "window";
+    /**
+     * If true, the scroll value will be inverted (e.g. scrolling down will result in a value of 0)
+     * @default false
+     */
+    invert: boolean;
+    /**
+     * If set, the scroll position will be read from the specified element instead of the window.
+     * Use a CSS selector to specify the element, e.g. `#my-scrollable-div` or `.scroll-container`.
+     * @default null
+     */
+    htmlSelector: string | null;
+    private mode;
+    /**
+     * Event fired when the scroll position changes
+     */
+    changed: EventList<ScrollFollowEvent>;
     /**
      * Current scroll value in "pages" (0 = top of page, 1 = bottom of page)
      */
     get currentValue(): number;
     private current_value;
     private target_value;
+    private applied_value;
     /** @internal */
     onEnable(): void;
     /** @internal */
     onDisable(): void;
     /** @internal */
     lateUpdate(): void;
-    private updateCurrentScroll;
-    private applyScroll;
+    private _lastSelectorValue;
+    private _lastSelectorElement;
+    private updateCurrentScrollValue;
+    private static applyScroll;
 }
+export {};

package/lib/engine-components/web/ScrollFollow.js

@@ -5,13 +5,33 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Object3D } from "three";
-import { serializable } from "../../engine/engine_serialization.js";
 import { Mathf } from "../../engine/engine_math.js";
+import { serializable } from "../../engine/engine_serialization.js";
+import { getBoundingBox } from "../../engine/engine_three_utils.js";
+import { Animation } from "../Animation.js";
+import { Animator } from "../Animator.js";
+import { AudioSource } from "../AudioSource.js";
 import { Behaviour } from "../Component.js";
-import { Animation, PlayableDirector } from "../api.js";
+import { EventList } from "../EventList.js";
+import { Light } from "../Light.js";
+import { SplineWalker } from "../splines/SplineWalker.js";
+import { PlayableDirector } from "../timeline/PlayableDirector.js";
+/**
+ * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.
+ * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
+ *
+ * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/
+ */
 export class ScrollFollow extends Behaviour {
     /**
      * Target object(s) to follow the scroll position of the page. If null, the main camera is used.
+     *
+     * Supported target types:
+     * - PlayableDirector (timeline), the scroll position will be mapped to the timeline time
+     * - Animator, the scroll position will be set to a float parameter named "scroll"
+     * - Animation, the scroll position will be mapped to the animation time
+     * - AudioSource, the scroll position will be mapped to the audio time
+     * - Any object with a `scroll` property (number or function)
      */
     target = null;
     /**
@@ -19,7 +39,22 @@ export class ScrollFollow extends Behaviour {
      * @default 0
      */
     damping = 0;
+    /**
+     * If true, the scroll value will be inverted (e.g. scrolling down will result in a value of 0)
+     * @default false
+     */
+    invert = false;
+    /**
+     * If set, the scroll position will be read from the specified element instead of the window.
+     * Use a CSS selector to specify the element, e.g. `#my-scrollable-div` or `.scroll-container`.
+     * @default null
+     */
+    htmlSelector = null;
     mode = "window";
+    /**
+     * Event fired when the scroll position changes
+     */
+    changed = new EventList();
     /**
      * Current scroll value in "pages" (0 = top of page, 1 = bottom of page)
      */
@@ -28,48 +63,122 @@ export class ScrollFollow extends Behaviour {
     }
     current_value = 0;
     target_value = 0;
+    applied_value = -1;
     /** @internal */
     onEnable() {
-        window.addEventListener("wheel", this.updateCurrentScroll, { passive: true });
+        window.addEventListener("wheel", this.updateCurrentScrollValue, { passive: true });
+        this.applied_value = -1;
     }
     /** @internal */
     onDisable() {
-        window.removeEventListener("wheel", this.updateCurrentScroll);
+        window.removeEventListener("wheel", this.updateCurrentScrollValue);
     }
     /** @internal */
     lateUpdate() {
+        this.updateCurrentScrollValue();
         // apply damping if any
         if (this.damping > 0) {
             this.current_value = Mathf.lerp(this.current_value, this.target_value, this.context.time.deltaTime / this.damping);
         }
-        // apply scroll to target(s)
-        if (Array.isArray(this.target)) {
-            this.target.forEach(t => t && this.applyScroll(t));
+        else {
+            this.current_value = this.target_value;
         }
-        else if (this.target) {
-            this.applyScroll(this.target);
+        if (this.current_value !== this.applied_value) {
+            this.applied_value = this.current_value;
+            let defaultPrevented = false;
+            if (this.changed.listenerCount > 0) {
+                // fire change event
+                const event = {
+                    type: "change",
+                    value: this.current_value,
+                    component: this,
+                    preventDefault: () => { event.defaultPrevented = true; },
+                    defaultPrevented: false,
+                };
+                this.changed.invoke(event);
+                defaultPrevented = event.defaultPrevented;
+            }
+            // if not prevented apply scroll
+            if (!defaultPrevented) {
+                const value = this.invert ? 1 - this.current_value : this.current_value;
+                // apply scroll to target(s)
+                if (Array.isArray(this.target)) {
+                    this.target.forEach(t => t && ScrollFollow.applyScroll(t, value));
+                }
+                else if (this.target) {
+                    ScrollFollow.applyScroll(this.target, value);
+                }
+            }
         }
     }
-    updateCurrentScroll = () => {
+    _lastSelectorValue = null;
+    _lastSelectorElement = null;
+    updateCurrentScrollValue = () => {
         switch (this.mode) {
             case "window":
-                this.target_value = window.scrollY / (document.body.scrollHeight - window.innerHeight);
+                if (this.htmlSelector?.length) {
+                    if (this.htmlSelector !== this._lastSelectorValue) {
+                        this._lastSelectorElement = document.querySelector(this.htmlSelector);
+                        this._lastSelectorValue = this.htmlSelector;
+                    }
+                    if (this._lastSelectorElement) {
+                        const rect = this._lastSelectorElement.getBoundingClientRect();
+                        this.target_value = -rect.top / (rect.height - window.innerHeight);
+                        if (isNaN(this.target_value) || !isFinite(this.target_value))
+                            this.target_value = 0;
+                        break;
+                    }
+                }
+                else {
+                    this.target_value = window.scrollY / (document.body.scrollHeight - window.innerHeight);
+                }
                 if (isNaN(this.target_value) || !isFinite(this.target_value))
                     this.target_value = 0;
                 break;
         }
-        if (this.damping <= 0) {
-            this.current_value = this.target_value;
-        }
     };
-    applyScroll(target) {
+    static applyScroll(target, value) {
+        if (!target)
+            return;
         if (target instanceof PlayableDirector) {
-            target.time = this.current_value * target.duration;
+            target.time = value * target.duration;
             if (!target.isPlaying)
                 target.evaluate();
         }
+        else if (target instanceof Animator) {
+            target.setFloat("scroll", value);
+        }
         else if (target instanceof Animation) {
-            target.time = this.current_value * target.duration;
+            target.time = value * target.duration;
+        }
+        else if (target instanceof AudioSource) {
+            if (!target.duration)
+                return;
+            target.time = value * target.duration;
+        }
+        else if (target instanceof SplineWalker) {
+            target.position01 = value;
+        }
+        else if (target instanceof Light) {
+            target.intensity = value;
+        }
+        else if (target instanceof Object3D) {
+            // When objects are assigned they're expected to move vertically based on scroll
+            if (target["needle:scrollbounds"] === undefined) {
+                target["needle:scrollbounds"] = getBoundingBox(target) || null;
+            }
+            const bounds = target["needle:scrollbounds"];
+            if (bounds) {
+                target.position.y = -bounds.min.y - value * (bounds.max.y - bounds.min.y);
+            }
+        }
+        else if ("scroll" in target) {
+            if (typeof target.scroll === "number") {
+                target.scroll = value;
+            }
+            else if (typeof target.scroll === "function") {
+                target.scroll(value);
+            }
         }
     }
 }
@@ -79,7 +188,16 @@ __decorate([
 __decorate([
     serializable()
 ], ScrollFollow.prototype, "damping", void 0);
+__decorate([
+    serializable()
+], ScrollFollow.prototype, "invert", void 0);
+__decorate([
+    serializable()
+], ScrollFollow.prototype, "htmlSelector", void 0);
 __decorate([
     serializable()
 ], ScrollFollow.prototype, "mode", void 0);
+__decorate([
+    serializable(EventList)
+], ScrollFollow.prototype, "changed", void 0);
 //# sourceMappingURL=ScrollFollow.js.map

package/lib/engine-components/web/ScrollFollow.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/ScrollFollow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScrollFollow.js","sourceRoot":"","sources":["../../../src/engine-components/web/ScrollFollow.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.9.0-next.ce04b9f",
+  "version": "4.9.0",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {
@@ -93,7 +93,7 @@
   ],
   "dependencies": {
     "@dimforge/rapier3d-compat": "^0.19.0",
-    "@needle-tools/gltf-progressive": "3.3.3",
+    "@needle-tools/gltf-progressive": "3.3.4",
     "@needle-tools/three-animation-pointer": "1.0.2",
     "@webxr-input-profiles/motion-controllers": "^1.0.0",
     "flatbuffers": "2.0.4",
@@ -168,4 +168,4 @@
   "module": "lib/needle-engine.js",
   "typings": "lib/needle-engine.d.ts",
   "types": "lib/needle-engine.d.ts"
-}
+}

package/src/engine-components/Component.ts

@@ -543,22 +543,25 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
 
 
 /** 
- * Needle Engine component base class. Component's are the main building blocks of the Needle Engine.    
+ * Needle Engine component's are the main building blocks of the Needle Engine.    
  * Derive from {@link Behaviour} to implement your own using the provided lifecycle methods.    
  * Components can be added to any {@link Object3D} using {@link addComponent} or {@link GameObject.addComponent}. 
  * 
- * The most common lifecycle methods are {@link update}, {@link awake}, {@link start}, {@link onEnable}, {@link onDisable} and {@link onDestroy}.   
+ * **Component lifecycle event methods:**   
+ * {@link awake}, {@link start}, {@link onEnable}, {@link onDisable}, {@link onDestroy}, {@link earlyUpdate}, {@link update}, {@link lateUpdate}, {@link onBeforeRender}, {@link onAfterRender}.   
  * 
- * XR specific callbacks include {@link onEnterXR}, {@link onLeaveXR}, {@link onUpdateXR}, {@link onXRControllerAdded} and {@link onXRControllerRemoved}.    
+ * **XR event methods:**   
+ * {@link onEnterXR}, {@link onLeaveXR}, {@link onUpdateXR}, {@link onXRControllerAdded} and {@link onXRControllerRemoved}.    
  * 
- * To receive pointer events implement {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
+ * **Input event methods:**   
+ * {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
  * 
  * @example
  * ```typescript
  * import { Behaviour } from "@needle-tools/engine";
  * export class MyComponent extends Behaviour {
  *  start() {
- *     console.log("Hello World");
+ *     console.log("Hello World", this.gameObject.name);
  *  }
  *  update() {
  *    console.log("Frame", this.context.time.frame);

package/src/engine-components/physics/Attractor.ts

@@ -1,9 +1,20 @@
+import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { Behaviour } from "../Component.js";
 import { Rigidbody } from "../RigidBody.js";
-import { serializable } from "../../engine/engine_serialization_decorator.js";
-
 
 
+/**
+ * Used to attract Rigidbodies towards the position of this component.
+ * Add Rigidbodies to the `targets` array to have them be attracted.  
+ * You can use negative strength values to create a repulsion effect.
+ * 
+ * @example Attractor component attracting a Rigidbody
+ * ```ts
+ * const attractor = object.addComponent(Attractor);
+ * attractor.strength = 5; // positive value to attract
+ * attractor.radius = 10; // only attract within 10 units
+ * attractor.targets.push(rigidbody); // add the Rigidbody to be attracted
+ */
 export class Attractor extends Behaviour {
 
     @serializable()
@@ -15,11 +26,10 @@ export class Attractor extends Behaviour {
     @serializable(Rigidbody)
     targets: Rigidbody[] = [];
 
-
     update() {
         const wp = this.gameObject.worldPosition;
         const factor = -this.strength * this.context.time.deltaTime;
-        this.targets.forEach(t => {
+        this.targets?.forEach(t => {
             if(!t) return;
             const dir = t.gameObject.worldPosition.sub(wp);
             const length = dir.length();

package/src/engine-components/web/Clickthrough.ts

@@ -1,6 +1,6 @@
 import { NEPointerEvent } from "../../engine/engine_input.js";
-import { Behaviour } from "../Component.js";
 import { onStart } from "../../engine/engine_lifecycle_api.js";
+import { Behaviour } from "../Component.js";
 
 // Automatically add ClickThrough component if "clickthrough" attribute is present on the needle-engine element
 onStart(ctx => {
@@ -23,6 +23,9 @@ onStart(ctx => {
  * @link Example https://stackblitz.com/~/github.com/needle-engine/sample-3d-over-html
  */
 export class ClickThrough extends Behaviour {
+
+    private _previousPointerEvents: string = 'all';
+
     onEnable() {
         // Register for pointer down and pointer move event
         this.context.input.addEventListener('pointerdown', this.onPointerEvent);
@@ -30,12 +33,13 @@ export class ClickThrough extends Behaviour {
             queue: 100,
         });
         window.addEventListener("touchend", this.onTouchEnd, { passive: true });
+        this._previousPointerEvents = this.context.domElement.style.pointerEvents;
     }
     onDisable() {
         this.context.input.removeEventListener('pointerdown', this.onPointerEvent);
         this.context.input.removeEventListener('pointermove', this.onPointerEvent);
         window.removeEventListener("touchend", this.onTouchEnd);
-        this.context.domElement.style.pointerEvents = 'all';
+        this.context.domElement.style.pointerEvents = this._previousPointerEvents;
     }
     onPointerEnter() {
         /** do nothing, necessary to raycast children */

package/src/engine-components/web/CursorFollow.ts

@@ -2,7 +2,9 @@ import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getTempVector } from "../../engine/engine_three_utils.js";
 import { Behaviour } from "../Component.js";
 
-
+/**
+ * The CursorFollow component makes the object follow the cursor (or touch) position on screen.
+ */
 export class CursorFollow extends Behaviour {
 
     /**
@@ -12,13 +14,26 @@ export class CursorFollow extends Behaviour {
     @serializable()
     damping: number = 0;
 
+    /**
+     * If true, the initial distance to the camera is maintained when following the cursor.
+     * @default true
+     */
+    @serializable()
+    keepDistance: boolean = true;
+
+    awake() {
+        this._distance = -1;
+    }
 
     private _distance: number = -1;
+
     updateDistance() {
+        if (this.keepDistance && this._distance !== -1) {
+            return;
+        }
         this._distance = this.gameObject.worldPosition.distanceTo(this.context.mainCamera.worldPosition);
     }
 
-
     /** @internal */
     update() {
         // continuously update distance in case camera or object moves