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

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.1",
   "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/plugins/vite/build.js

@@ -1,4 +1,7 @@
 
+/** 
+ * @returns {import('vite').Plugin}
+ */
 export const needleBuild = (command, config, userSettings) => {
 
     // TODO: need to set this when building a dist

package/src/engine/engine_gameobject.ts

@@ -1,4 +1,4 @@
-import { Bone, Object3D, Quaternion, SkinnedMesh, Vector3 } from "three";
+import { Bone, Euler, Object3D, Quaternion, SkinnedMesh, Vector3 } from "three";
 
 import { $shadowDomOwner } from "../engine-components/ui/Symbols.js";
 import { type AssetReference } from "./engine_addressables.js";
@@ -11,7 +11,7 @@ import { processNewScripts } from "./engine_mainloop_utils.js";
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
 import { assign, ISerializable } from "./engine_serialization_core.js";
 import { Context, registerComponent } from "./engine_setup.js";
-import { logHierarchy, setWorldPosition, setWorldQuaternion } from "./engine_three_utils.js";
+import { getTempQuaternion, logHierarchy, setWorldPosition, setWorldQuaternion } from "./engine_three_utils.js";
 import { type Constructor, type GuidsMap, type IComponent as Component, type IComponent, IEventList, type IGameObject as GameObject, type UIDProvider } from "./engine_types.js";
 import { deepClone, getParam, tryFindObject } from "./engine_utils.js";
 import { apply } from "./js-extensions/index.js";
@@ -24,12 +24,12 @@ export type IInstantiateOptions = {
     //** parent guid or object */
     parent?: string | Object3D;
     /** position in local space. Set `keepWorldPosition` to true if this is world space */
-    position?: Vector3;
+    position?: Vector3 | [number, number, number];
     /** for duplicatable parenting */
     keepWorldPosition?: boolean;
     /** rotation in local space. Set `keepWorldPosition` to true if this is world space */
-    rotation?: Quaternion;
-    scale?: Vector3;
+    rotation?: Quaternion | Euler | [number, number, number];
+    scale?: Vector3 | [number, number, number];
     /** if the instantiated object should be visible */
     visible?: boolean;
     context?: Context;
@@ -46,9 +46,9 @@ export class InstantiateOptions implements IInstantiateOptions {
     idProvider?: UIDProvider | undefined;
     parent?: string | undefined | Object3D;
     keepWorldPosition?: boolean
-    position?: Vector3 | undefined;
-    rotation?: Quaternion | undefined;
-    scale?: Vector3 | undefined;
+    position?: Vector3 | [number, number, number] | undefined;
+    rotation?: Quaternion | Euler | [number, number, number] | undefined;
+    scale?: Vector3 | [number, number, number] | undefined;
     visible?: boolean | undefined;
     context?: Context | undefined;
     components?: boolean | undefined;
@@ -58,9 +58,9 @@ export class InstantiateOptions implements IInstantiateOptions {
         clone.idProvider = this.idProvider;
         clone.parent = this.parent;
         clone.keepWorldPosition = this.keepWorldPosition;
-        clone.position = this.position?.clone();
-        clone.rotation = this.rotation?.clone();
-        clone.scale = this.scale?.clone();
+        clone.position = Array.isArray(this.position) ? [...this.position] : this.position?.clone();
+        clone.rotation = Array.isArray(this.rotation) ? [...this.rotation] : this.rotation?.clone();
+        clone.scale = Array.isArray(this.scale) ? [...this.scale] : this.scale?.clone();
         clone.visible = this.visible;
         clone.context = this.context;
         clone.components = this.components;
@@ -72,9 +72,9 @@ export class InstantiateOptions implements IInstantiateOptions {
         this.idProvider = other.idProvider;
         this.parent = other.parent;
         this.keepWorldPosition = other.keepWorldPosition;
-        this.position = other.position?.clone();
-        this.rotation = other.rotation?.clone();
-        this.scale = other.scale?.clone();
+        this.position = Array.isArray(other.position) ? [...other.position] : other.position?.clone();
+        this.rotation = Array.isArray(other.rotation) ? [...other.rotation] : other.rotation?.clone();
+        this.scale = Array.isArray(other.scale) ? [...other.scale] : other.scale?.clone();
         this.visible = other.visible;
         this.context = other.context;
         this.components = other.components;
@@ -287,6 +287,8 @@ declare type ObjectCloneReference = {
 
 
 declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
+declare type NewObjectReferenceMap = Record<string, { target: object, key: string }>;
+
 /**
  * Provides access to the instantiated object and its clone
  */
@@ -325,13 +327,13 @@ export function instantiate(instance: AssetReference | GameObject | Object3D, op
     }
 
     const components: Array<Component> = [];
-    const goMapping: InstantiateReferenceMap = {}; // used to resolve references on components to components on other gameobjects to their new counterpart
+    const referencemap: InstantiateReferenceMap = {}; // used to resolve references on components to components on other gameobjects to their new counterpart
     const skinnedMeshes: InstantiateReferenceMap = {}; // used to resolve skinned mesh bones
-    const clone = internalInstantiate(context, instance, options, components, goMapping, skinnedMeshes);
+    const clone = internalInstantiate(context, instance, options, components, referencemap, skinnedMeshes);
 
     if (clone) {
-        resolveReferences(goMapping);
-        resolveAndBindSkinnedMeshBones(skinnedMeshes, goMapping);
+        resolveReferences(clone, referencemap);
+        resolveAndBindSkinnedMeshBones(skinnedMeshes, referencemap);
     }
 
     if (debug) {
@@ -426,19 +428,45 @@ function internalInstantiate(
         parent.add(clone);
     }
 
-    // apply transform
+    // POSITION
     if (opts?.position) {
-        setWorldPosition(clone, opts.position);
+        if (Array.isArray(opts.position)) {
+            const vec = new Vector3();
+            vec.fromArray(opts.position);
+            clone.worldPosition = vec;
+        }
+        else {
+            clone.worldPosition = opts.position;
+        }
     }
     else clone.position.copy(instance.position);
+
+    // ROTATION
     if (opts?.rotation) {
-        setWorldQuaternion(clone, opts.rotation);
+        if (opts.rotation instanceof Quaternion)
+            clone.worldQuaternion = opts.rotation;
+        else if (opts.rotation instanceof Euler)
+            clone.worldQuaternion = getTempQuaternion().setFromEuler(opts.rotation);
+        else if (Array.isArray(opts.rotation)) {
+            const euler = new Euler();
+            euler.fromArray(opts.rotation);
+            clone.worldQuaternion = getTempQuaternion().setFromEuler(euler);
+        }
     }
     else clone.quaternion.copy(instance.quaternion);
+
+    // SCALE
     if (opts?.scale) {
-        clone.scale.copy(opts.scale);
         // TODO MAJOR: replace with worldscale
         // clone.worldScale = opts.scale;
+        if (Array.isArray(opts.scale)) {
+            const vec = new Vector3();
+            vec.fromArray(opts.scale);
+            opts.scale = vec;
+        }
+        else {
+            clone.scale.copy(opts.scale);
+        }
     }
     else clone.scale.copy(instance.scale);
 
@@ -470,17 +498,7 @@ function internalInstantiate(
         for (let i = 0; i < components.length; i++) {
             const comp = components[i];
             const copy = new comp.constructor();
-            assign(copy, comp, undefined, {
-                // onAssign: (source, key, value) => {
-                //     if (typeof value === "object") {
-                //         const serializable = source as ISerializable;
-                //         if (serializable?.$serializedTypes?.[key]) {
-                //             console.debug("TODO CLONE", key, value);
-                //         }
-                //     }
-                //     return value;
-                // }
-            });
+            onAssignComponent(comp, copy, objectsMap);
             // make sure the original guid stays intact
             if (comp[editorGuidKeyName] !== undefined)
                 copy[editorGuidKeyName] = comp[editorGuidKeyName];
@@ -501,7 +519,6 @@ function internalInstantiate(
         opts.parent = undefined;
         opts.visible = undefined;
     }
-
     for (const ch in instance.children) {
         const child = instance.children[ch];
         const newChild = internalInstantiate(context, child as GameObject, opts, componentsList, objectsMap, skinnedMeshesMap);
@@ -510,11 +527,59 @@ function internalInstantiate(
             clone.add(newChild);
         }
     }
-
     return clone;
+}
+
 
+function onAssignComponent(source: any, target: any, _newObjectsMap: InstantiateReferenceMap) {
+    assign(target, source, undefined, {
+        // onAssigned: (target, key, _oldValue, value) => {
+            // if (value !== null && typeof value === "object") {
+            //     const serializable = target as ISerializable;
+            //     if (serializable?.$serializedTypes?.[key]) {
+            //         if (!(value instanceof Object3D)) {
+            //             // let clone = null;
+            //             // if ("clone" in value) {
+            //             //     if (canClone(value)) clone = (value as any).clone();
+            //             // }
+            //             // else {
+            //             //     clone = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+            //             // }
+            //             // if (clone) {
+            //             //     console.debug(key, { target, value, clone })
+            //             //     target[key] = clone;
+            //             //     findNestedReferences(clone, objectsMap);
+            //             // }
+            //             // else console.debug("Could not clone value for key", key, value);
+            //         }
+            //         else {
+            //             console.log("ASSIGNED", value)
+            //         }
+
+            //         recursiveAssign(target, target[key], newObjectsMap);
+            //     }
+
+            // }
+        // }
+    });
 }
 
+// function findNestedReferences(object: object, map: InstantiateReferenceMap) {
+//     const keys = Object.keys(object);
+//     for (const key of keys) {
+//         const val = (object as any)[key];
+//         if (val instanceof Object3D) {
+//             if ("guid" in val && val.guid) {
+//                 console.log("FOUND ", val.guid, val)
+//                 map[val.guid] = { original: val, clone: null };
+//             }
+//         }
+//         else if (typeof val === "object" && val !== null) {
+//             findNestedReferences(val, map);
+//         }
+//     }
+// }
+
 function resolveAndBindSkinnedMeshBones(
     skinnedMeshes: { [key: string]: ObjectCloneReference },
     newObjectsMap: { [key: string]: ObjectCloneReference }
@@ -599,13 +664,13 @@ function resolveAndBindSkinnedMeshBones(
 
 // }
 
-function resolveReferences(newObjectsMap: InstantiateReferenceMap) {
+function resolveReferences(_newInstance: Object3D, newObjectsMap: InstantiateReferenceMap) {
     // for every object that is newly created we want to update references to their newly created counterparts
     // e.g. a collider instance referencing a rigidbody instance should be updated so that 
     // the cloned collider does not reference the cloned rigidbody (instead of the original rigidbody)
     for (const key in newObjectsMap) {
         const val = newObjectsMap[key];
-        const clone = val.clone as Object3D;
+        const clone = val.clone as Object3D | null;
         // resolve references
         if (clone?.isObject3D && clone?.userData?.components) {
             for (let i = 0; i < clone.userData.components.length; i++) {
@@ -706,4 +771,6 @@ function postProcessNewInstance(copy: Object3D, key: string, value: IComponent |
             return copy;
         }
     }
-}
+}
+
+// const canClone = (value: any) => value.isVector4 || value.isVector3 || value.isVector2 || value.isQuaternion || value.isEuler || value.isColor === true;

package/src/engine/engine_networking_instantiate.ts

@@ -1,4 +1,4 @@
-import { Object3D, Quaternion, Vector3 } from "three";
+import { Euler, Object3D, Quaternion, Vector3 } from "three";
 // https://github.com/uuidjs/uuid
 // v5 takes string and namespace
 import { v5 } from 'uuid';
@@ -254,12 +254,27 @@ export function syncInstantiate(object: GameObject | Object3D, opts: SyncInstant
             if (opts.deleteOnDisconnect === true)
                 model.deleteStateOnDisconnect = true;
             if (originalOpts) {
-                if (originalOpts.position)
-                    model.position = { x: originalOpts.position.x, y: originalOpts.position.y, z: originalOpts.position.z };
-                if (originalOpts.rotation)
+                if (originalOpts.position) {
+                    if (Array.isArray(originalOpts.position)) {
+                        model.position = { x: originalOpts.position[0], y: originalOpts.position[1], z: originalOpts.position[2] };
+                    }
+                    else model.position = { x: originalOpts.position.x, y: originalOpts.position.y, z: originalOpts.position.z };
+                }
+                if (originalOpts.rotation) {
+                    if (originalOpts.rotation instanceof Euler) {
+                        originalOpts.rotation = new Quaternion().setFromEuler(originalOpts.rotation);
+                    }
+                    else if (originalOpts.rotation instanceof Array) {
+                        originalOpts.rotation = new Quaternion().fromArray(originalOpts.rotation);
+                    }
                     model.rotation = { x: originalOpts.rotation.x, y: originalOpts.rotation.y, z: originalOpts.rotation.z, w: originalOpts.rotation.w };
-                if (originalOpts.scale)
-                    model.scale = { x: originalOpts.scale.x, y: originalOpts.scale.y, z: originalOpts.scale.z };
+                }
+                if (originalOpts.scale) {
+                    if (Array.isArray(originalOpts.scale)) {
+                        model.scale = { x: originalOpts.scale[0], y: originalOpts.scale[1], z: originalOpts.scale[2] };
+                    }
+                    else model.scale = { x: originalOpts.scale.x, y: originalOpts.scale.y, z: originalOpts.scale.z };
+                }
             }
             if (!model.position)
                 model.position = { x: go.position.x, y: go.position.y, z: go.position.z };

package/src/engine/engine_serialization_core.ts

@@ -658,10 +658,10 @@ export const $isAssigningProperties = Symbol("assigned component properties");
  * @param key the key that is being assigned
  * @param value the value that is being assigned
  */
-type OnAssign = (source: object, key: string, value: any) => any;
+type AssignedCallback = (source: object, key: string, oldValue: any, newValue: any) => any;
 
 /** Object.assign behaviour but check if property is writeable (e.g. getter only properties are skipped) */
-export function assign(target: any, source: any, info?: ImplementationInformation, opts?: { onAssign?: OnAssign }) {
+export function assign(target: any, source: any, info?: ImplementationInformation, opts?: { onAssigned?: AssignedCallback }) {
     if (source === undefined || source === null) return;
     if (target === undefined || target === null) return;
 
@@ -699,13 +699,13 @@ export function assign(target: any, source: any, info?: ImplementationInformatio
             // arrow functions are defined as properties on the object
             continue;
         }
-        if (!desc || desc.writable === true) {
-            const value = opts?.onAssign ? opts.onAssign(source, key, source[key]) : source[key];
-            target[key] = value;
-        }
-        else if (desc?.set !== undefined) {
-            const value = opts?.onAssign ? opts.onAssign(source, key, source[key]) : source[key];
-            target[key] = value;
+        if (!desc || desc.writable === true || desc.set !== undefined) {
+            const newValue = source[key];
+            const oldValue = target[key];
+            target[key] = newValue;
+            if (opts?.onAssigned) {
+                opts.onAssigned(target, key, oldValue, newValue);
+            }
         }
     }
     delete target[$isAssigningProperties];

package/src/engine/engine_serialization_decorator.ts

@@ -27,7 +27,8 @@ export const serializable = function <T>(type?: Constructor<T> | null | Array<Co
 
     return function (_target: any, _propertyKey: string | { name: string }) {
         if (!_target) {
-            console.error("Found @serializable decorator without a target");
+            const propertyName = typeof _propertyKey === 'string' ? _propertyKey : _propertyKey.name;
+            console.warn(`@serializable without a target at '${propertyName}'.`);
             return;
         }
         // The _propertyKey parameter is a string in TS4 with experimentalDecorators

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/Renderer.ts

@@ -1,5 +1,5 @@
 import { getRaycastMesh } from "@needle-tools/gltf-progressive";
-import { AxesHelper, Material, Mesh, Object3D, SkinnedMesh, Texture, Vector4 } from "three";
+import { AxesHelper, Material, Mesh, MeshBasicMaterial, MeshPhysicalMaterial, MeshStandardMaterial, Object3D, RawShaderMaterial, ShaderMaterial, SkinnedMesh, Texture, Vector4 } from "three";
 
 import { showBalloonWarning } from "../engine/debug/index.js";
 import { getComponent, getOrAddComponent } from "../engine/engine_components.js";
@@ -48,6 +48,8 @@ export enum RenderState {
     Front = 2,
 }
 
+type SharedMaterial = (Material & Partial<MeshStandardMaterial> & Partial<MeshPhysicalMaterial> & Partial<ShaderMaterial> & Partial<RawShaderMaterial>);
+
 
 // support sharedMaterials[index] assigning materials directly to the objects
 class SharedMaterialArray implements ISharedMaterials {
@@ -185,7 +187,7 @@ class SharedMaterialArray implements ISharedMaterials {
         this.changed = true;
     }
 
-    private getMaterial(index: number): Material | null {
+    private getMaterial(index: number): SharedMaterial | null {
         index = this.resolveIndex(index);
         if (index < 0) return null;
         const obj = this._targets;
@@ -302,11 +304,11 @@ export class Renderer extends Behaviour implements IRenderer {
         return this._sharedMeshes;
     }
 
-    get sharedMaterial(): Material {
-        return this.sharedMaterials[0];
+    get sharedMaterial(): SharedMaterial {
+        return this.sharedMaterials[0] as SharedMaterial;
     }
 
-    set sharedMaterial(mat: Material) {
+    set sharedMaterial(mat: SharedMaterial) {
         const cur = this.sharedMaterials[0];
         if (cur === mat) return;
         this.sharedMaterials[0] = mat;
@@ -314,12 +316,12 @@ export class Renderer extends Behaviour implements IRenderer {
     }
 
     /**@deprecated please use sharedMaterial */
-    get material(): Material {
-        return this.sharedMaterials[0];
+    get material(): SharedMaterial {
+        return this.sharedMaterials[0] as SharedMaterial;
     }
 
     /**@deprecated please use sharedMaterial */
-    set material(mat: Material) {
+    set material(mat: SharedMaterial) {
         this.sharedMaterial = mat;
     }
 
@@ -329,10 +331,10 @@ export class Renderer extends Behaviour implements IRenderer {
     private _probeAnchorLastFrame?: Object3D;
 
     // this is just available during deserialization
-    private set sharedMaterials(_val: Array<Material | null>) {
+    private set sharedMaterials(_val: Array<SharedMaterial | null>) {
         // TODO: elements in the array might be missing at the moment which leads to problems if an index is serialized
         if (!this._originalMaterials) {
-            this._originalMaterials = _val as Material[];
+            this._originalMaterials = _val as SharedMaterial[];
         }
         else if (_val) {
             let didWarn = false;

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