@needle-tools/engine 5.1.0-alpha.3 → 5.1.0-alpha.5

package/src/engine-components/Component.ts

@@ -10,9 +10,10 @@ import * as main from "../engine/engine_mainloop_utils.js";
 import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/engine_networking_instantiate.js";
 import { Context, FrameEvent } from "../engine/engine_setup.js";
 import * as threeutils from "../engine/engine_three_utils.js";
-import { $componentName, type Collision, type ComponentInit, type Constructor, type ConstructorConcrete, type GuidsMap, type ICollider, type IComponent, type IGameObject, type SourceIdentifier } from "../engine/engine_types.js";
+import { $componentName, type Collision, type ComponentInit, type Constructor, type ConstructorConcrete, type ICollider, type IComponent, type IGameObject, type SourceIdentifier } from "../engine/engine_types.js";
 import { TypeStore } from "../engine/engine_typestore.js";
 import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
+import { DisposableStore, type IDisposable, type DisposeFn } from "../engine/engine_disposable.js";
 import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
 
 
@@ -556,7 +557,7 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
  * **Input event methods:**   
  * {@link onPointerDown}, {@link onPointerUp}, {@link onPointerEnter}, {@link onPointerExit} and {@link onPointerMove}.
  * 
- * @example
+ * @example Basic component
  * ```typescript
  * import { Behaviour } from "@needle-tools/engine";
  * export class MyComponent extends Behaviour {
@@ -568,13 +569,31 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
  *  }
  * }
  * ```
- * 
+ *
+ * @example Automatic cleanup with autoCleanup
+ * ```typescript
+ * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
+ * export class ScoreTracker extends Behaviour {
+ *   @serializable(EventList)
+ *   onScoreChanged?: EventList<number>;
+ *
+ *   start() {
+ *     // Registered during start → survives enable/disable, cleaned up on destroy
+ *     this.autoCleanup(this.onScoreChanged?.on(score => console.log("Score:", score)));
+ *   }
+ *
+ *   onEnable() {
+ *     // Registered during onEnable → cleaned up on disable
+ *     this.autoCleanup(() => this.cleanupResources());
+ *   }
+ * }
+ * ```
+ *
  * @group Components
  */
 export abstract class Component implements IComponent, EventTarget,
     Partial<INeedleXRSessionEventReceiver>,
-    Partial<IPointerEventHandler>
-{
+    Partial<IPointerEventHandler> {
     /** 
      * Indicates whether this object is a component
      * @internal 
@@ -686,6 +705,74 @@ export abstract class Component implements IComponent, EventTarget,
         return true;
     }
 
+    private __disableCleanups?: DisposableStore;
+    private __destroyCleanups?: DisposableStore;
+
+    /**
+     * @experimental
+     * Register a resource for automatic cleanup tied to this component's lifecycle.
+     * Accepts {@link IDisposable} objects, cleanup functions, or event unsubscribe functions.
+     * `null` and `undefined` are safe no-ops (convenient for conditional subscriptions).
+     *
+     * **Lifecycle-aware:** The cleanup store is chosen automatically based on when `autoCleanup` is called:
+     * - Called during {@link onEnable} → cleaned up on {@link onDisable} (and re-registered on re-enable)
+     * - Called during {@link awake} or {@link start} → cleaned up on {@link onDestroy} (survives enable/disable cycles)
+     * - Called at any other time (e.g. from update) → cleaned up on {@link onDisable}
+     *
+     * @param disposable An {@link IDisposable}, a cleanup/unsubscribe function, or `null`/`undefined`
+     *
+     * @example EventList subscriptions
+     * ```ts
+     * import { Behaviour, serializable, EventList } from "@needle-tools/engine";
+     *
+     * export class MyComponent extends Behaviour {
+     *     @serializable(EventList)
+     *     onScoreChanged?: EventList<number>;
+     *
+     *     onEnable() {
+     *         this.autoCleanup(this.onScoreChanged?.on(score => {
+     *             console.log("Score:", score);
+     *         }));
+     *     }
+     * }
+     * ```
+     *
+     * @example Lifetime subscriptions in awake
+     * ```ts
+     * import { Behaviour } from "@needle-tools/engine";
+     *
+     * export class Persistent extends Behaviour {
+     *     awake() {
+     *         // Registered during awake → survives enable/disable, cleaned up on destroy
+     *         this.autoCleanup(() => this.save());
+     *     }
+     * }
+     * ```
+     */
+    protected autoCleanup(disposable: IDisposable | DisposeFn | Function | null | undefined): void {
+        if (!disposable) {
+            if (isDevEnvironment()) {
+                console.warn(`[Component] autoCleanup called with null or undefined, no cleanup registered. This is safe, but you may want to check if this was intentional (${this[$componentName] || this.constructor.name})`);
+            }
+            return;
+        }
+        // During onEnable → cleaned up on disable
+        if (this.__inEnableOrDisableCallback) {
+            if (!this.__disableCleanups) this.__disableCleanups = new DisposableStore();
+            this.__disableCleanups.add(disposable);
+        }
+        // During awake or start → cleaned up on destroy
+        else if (!this.__didCompleteStart) {
+            if (!this.__destroyCleanups) this.__destroyCleanups = new DisposableStore();
+            this.__destroyCleanups.add(disposable);
+        }
+        // After start (update, etc.) → cleaned up on disable
+        else {
+            if (!this.__disableCleanups) this.__disableCleanups = new DisposableStore();
+            this.__disableCleanups.add(disposable);
+        }
+    }
+
     private get __isActive(): boolean {
         return this.gameObject.visible;
     }
@@ -720,12 +807,6 @@ export abstract class Component implements IComponent, EventTarget,
      */
     sourceId?: SourceIdentifier;
 
-    /**
-     * Called when this component needs to remap guids after an instantiate operation.
-     * @param guidsMap Mapping from old guids to newly generated guids
-     */
-    resolveGuids?(guidsMap: GuidsMap): void;
-
     /**
      * Called once when the component becomes active for the first time.
      * This is the first lifecycle callback to be invoked
@@ -988,6 +1069,12 @@ export abstract class Component implements IComponent, EventTarget,
     /** @internal */
     private __didStart: boolean = false;
 
+    /** True while start() has finished executing (used by autoCleanup to distinguish start from update) */
+    private __didCompleteStart: boolean = false;
+
+    /** True while onEnable() is executing (used by autoCleanup to route to disable store) */
+    private __inEnableOrDisableCallback: boolean = false;
+
     /** @internal */
     protected __didEnable: boolean = false;
 
@@ -1004,6 +1091,8 @@ export abstract class Component implements IComponent, EventTarget,
     constructor(init?: ComponentInit<Component>) {
         this.__didAwake = false;
         this.__didStart = false;
+        this.__didCompleteStart = false;
+        this.__inEnableOrDisableCallback = false;
         this.__didEnable = false;
         this.__isEnabled = undefined;
         this.__destroyed = false;
@@ -1015,6 +1104,8 @@ export abstract class Component implements IComponent, EventTarget,
     __internalNewInstanceCreated(init?: ComponentInit<this>): this {
         this.__didAwake = false;
         this.__didStart = false;
+        this.__didCompleteStart = false;
+        this.__inEnableOrDisableCallback = false;
         this.__didEnable = false;
         this.__isEnabled = undefined;
         this.__destroyed = false;
@@ -1051,11 +1142,12 @@ export abstract class Component implements IComponent, EventTarget,
         if (this.__didStart) return;
         this.__didStart = true;
         if (this.start) this.start();
+        this.__didCompleteStart = true;
     }
 
 
     /** @internal */
-    __internalEnable(isAddingToScene?: boolean): boolean {
+    __internalEnable(isHierarchyChange?: boolean): boolean {
         if (this.__destroyed) {
             if (isDevEnvironment()) {
                 console.warn("[Needle Engine Dev] Trying to enable destroyed component");
@@ -1066,33 +1158,38 @@ export abstract class Component implements IComponent, EventTarget,
         // But a user can change enable during awake
         if (!this.__didAwake) return false;
         if (this.__didEnable) {
-            // We dont want to change the enable state if we are adding to scene
-            // But we want to change the state when e.g. a user changes the enable state during awake
-            if (isAddingToScene !== true)
+            // Don't change __isEnabled for hierarchy-driven changes (e.g. adding to scene, visibility)
+            if (isHierarchyChange !== true)
                 this.__isEnabled = true;
             return false;
         }
-        // console.trace("INTERNAL ENABLE");
         this.__didEnable = true;
         this.__isEnabled = true;
+        this.__inEnableOrDisableCallback = true;
         this.onEnable();
+        this.__inEnableOrDisableCallback = false;
         return true;
     }
 
     /** @internal */
-    __internalDisable(isRemovingFromScene?: boolean) {
+    __internalDisable(isHierarchyChange?: boolean) {
         // Don't change enable before awake
         // But a user can change enable during awake
         if (!this.__didAwake) return;
         if (!this.__didEnable) {
-            // We dont want to change the enable state if we are removing from a scene
-            if (isRemovingFromScene !== true)
+            // Don't change __isEnabled for hierarchy-driven changes (e.g. removing from scene, visibility)
+            if (isHierarchyChange !== true)
                 this.__isEnabled = false;
             return;
         }
         this.__didEnable = false;
-        this.__isEnabled = false;
+        // Don't change __isEnabled for hierarchy-driven changes — the component itself is still "enabled"
+        if (isHierarchyChange !== true)
+            this.__isEnabled = false;
+        this.__inEnableOrDisableCallback = true;
         this.onDisable();
+        this.__disableCleanups?.dispose();
+        this.__inEnableOrDisableCallback = false;
     }
 
     /** @internal */
@@ -1101,6 +1198,7 @@ export abstract class Component implements IComponent, EventTarget,
         this.__destroyed = true;
         if (this.__didAwake) {
             this.onDestroy?.call(this);
+            this.__destroyCleanups?.dispose();
             this.dispatchEvent(new CustomEvent("destroyed", { detail: this }));
         }
         destroyComponentInstance(this as any);

package/src/engine-components/ContactShadows.ts

@@ -100,7 +100,7 @@ export class ContactShadows extends Behaviour {
             const obj = new Object3D();
             obj.name = "ContactShadows";
             instance = addComponent(obj, ContactShadows, {
-                autoFit: false,
+                autoFit: true,
                 occludeBelowGround: false
             });
             this._instances.set(context, instance);
@@ -169,6 +169,10 @@ export class ContactShadows extends Behaviour {
         return this._needsUpdate;
     }
     private _needsUpdate: boolean = false;
+    private _needsFit: boolean = false;
+
+    // TODO: support auto-refit for moveable/animated objects (e.g. via mesh-bvh / scene BVH).
+    // Currently there's no reliable way to detect object position/scale changes.
 
     /** All shadow objects are parented to this object. 
      * The gameObject itself should not be transformed because we want the ContactShadows object e.g. also have a GroundProjectedEnv component
@@ -366,6 +370,11 @@ export class ContactShadows extends Behaviour {
 
     onEnable(): void {
         this._needsUpdate = true;
+        this.autoCleanup(this.context.events.on("scene-content-changed", () => {
+            if (!this.autoFit) return;
+            this._needsFit = true;
+            this._needsUpdate = true;
+        }));
     }
 
     /** @internal */
@@ -393,6 +402,11 @@ export class ContactShadows extends Behaviour {
     /** @internal */
     onBeforeRender(_frame: XRFrame | null): void {
 
+        if (this._needsFit && this.autoFit) {
+            this._needsFit = false;
+            this.fitShadows();
+        }
+
         if (this.manualUpdate) {
             if (!this._needsUpdate) return;
         }

package/src/engine-components/DragControls.ts

@@ -10,7 +10,6 @@ import { getBoundingBox, getTempVector, getWorldPosition, setWorldPosition } fro
 import { type IGameObject } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js";
 import { NeedleXRSession } from "../engine/engine_xr.js";
-import { Avatar_POI } from "./avatar/Avatar_Brain_LookAt.js";
 import { Behaviour, GameObject } from "./Component.js";
 import { EventList } from "./EventList.js";
 import { UsageMarker } from "./Interactable.js";
@@ -1500,11 +1499,6 @@ class LegacyDragVisualsHelper {
             }
         }
 
-        if (this._selected) {
-            // TODO move somewhere else
-            Avatar_POI.Remove(context, this._selected);
-        }
-
         this._selected = newSelected;
         this._context = context;
         this._rbs.length = 0;
@@ -1524,9 +1518,6 @@ class LegacyDragVisualsHelper {
                 return;
             }
 
-            // TODO move somewhere else
-            Avatar_POI.Add(context, this._selected, null);
-
             this._groundOffsetFactor = 0;
             this._hasGroundPlane = true;
             this._groundOffset.set(0, 0, 0);

package/src/engine-components/DropListener.ts

@@ -597,6 +597,9 @@ export class DropListener extends Behaviour {
         });
         this.dispatchEvent(evt);
         this.onDropped?.invoke(evt.detail);
+        if (obj) {
+            this.context.events.emit("scene-content-changed", { source: this, object: obj });
+        }
 
         // send network event
         if (!isRemote && ctx.url?.startsWith("http") && this.context.connection.isConnected && obj) {

package/src/engine-components/EventList.ts

@@ -1,13 +1,17 @@
 import { isDevEnvironment } from "../engine/debug/index.js";
-import { InstantiateContext } from "../engine/engine_gameobject.js";
 import type { IComponent, IEventList } from "../engine/engine_types.js";
 
 const argumentsBuffer = new Array<any>();
 
 /**
- * CallInfo represents a single callback method that can be invoked by the {@link EventList}.  
+ * CallInfo represents a single callback method that can be invoked by the {@link EventList}.
  */
 export class CallInfo {
+
+    /** @internal Used by the instantiate resolver to recursively resolve references */
+    static { CallInfo.prototype.$serializedTypes = { target: Object, arguments: Array }; }
+    declare $serializedTypes: Record<string, any>;
+
     /**
      * When the CallInfo is enabled it will be invoked when the EventList is invoked
      */
@@ -95,8 +99,7 @@ export class CallInfo {
     }
 }
 
-const isUpperCase = (string) => /^[A-Z]*$/.test(string);
-
+/** @deprecated No longer automatically dispatched. Use `eventList.on()` directly instead. */
 export class EventListEvent<TArgs extends any> extends Event { //implements ArrayLike<T> {
     args?: TArgs;
 }
@@ -150,73 +153,13 @@ export class EventListEvent<TArgs extends any> extends Event { //implements Arra
  */
 export class EventList<TArgs extends any = any> implements IEventList {
 
+    /** @internal Used by the instantiate resolver to recursively resolve references */
+    static { EventList.prototype.$serializedTypes = { methods: Array }; }
+    declare $serializedTypes: Record<string, any>;
+
     /** checked during instantiate to create a new instance */
     readonly isEventList = true;
 
-    /**
-     * @internal Used by the Needle Engine instantiate call to remap the event listeners to the new instance
-     */
-    __internalOnInstantiate(ctx: InstantiateContext) {
-        const newMethods = new Array<CallInfo>();
-        for (let i = 0; i < this.methods.length; i++) {
-            const method = this.methods[i];
-            if (method.target instanceof Function) {
-                // can not clone a function
-            }
-            else {
-                const target = method.target as { uuid?: string };
-                let key = target?.uuid;
-                if ((target as IComponent)) {
-                    key = (target as IComponent).guid;
-                }
-                if (key) {
-                    const newTarget = ctx[key];
-                    if (newTarget) {
-                        // remap the arguments to the new instance (e.g. if an object is passed as an argument to the event list and this object has been cloned we want to remap it to the clone)
-                        const newArguments = method.arguments?.map(arg => {
-                            if (arg instanceof Object && arg.uuid) {
-                                return ctx[arg.uuid].clone;
-                            }
-                            else if ((arg as IComponent)?.isComponent) {
-                                return ctx[(arg as IComponent).guid].clone;
-                            }
-                            return arg;
-                        });
-                        newMethods.push(new CallInfo(newTarget.clone, method.methodName, newArguments, method.enabled));
-                    }
-                    else if (isDevEnvironment()) {
-                        console.warn("Could not find target for event listener");
-                    }
-                }
-            }
-        }
-        const newInstance = new EventList(newMethods);
-        return newInstance;
-    }
-
-    private target?: object;
-    private key?: string;
-
-    // TODO: serialization should not take care of the args but instead give them to the eventlist directly
-    // so we can handle passing them on here instead of in the serializer
-    // this would also allow us to pass them on to the component EventTarget
-
-    /** set an event target to try invoke the EventTarget dispatchEvent when this EventList is invoked */
-    setEventTarget(key: string, target: object) {
-        this.key = key;
-        this.target = target;
-        if (this.key !== undefined) {
-            let temp = "";
-            let foundFirstLetter = false;
-            for (const c of this.key) {
-                if (foundFirstLetter && isUpperCase(c))
-                    temp += "-";
-                foundFirstLetter = true;
-                temp += c.toLowerCase();
-            }
-            this.key = temp;
-        }
-    }
 
     /** How many callback methods are subscribed to this event */
     get listenerCount() { return this.methods?.length ?? 0; }
@@ -285,24 +228,9 @@ export class EventList<TArgs extends any = any> implements IEventList {
             this._methodsCopy.length = 0;
             this._methodsCopy.push(...this.methods);
 
-            // first invoke all the methods that were subscribed to this eventlist
             for (const m of this._methodsCopy) {
                 m.invoke(...args);
             }
-
-
-            // then try to dispatch the event on the object that is owning this eventlist
-            // with this we get automatic event listener support for unity events on all componnets
-            // so example for a component with a click UnityEvent you can also subscribe to the component like this:
-            // myComponent.addEventListener("click", args => {...")
-            if (typeof this.target === "object" && typeof this.key === "string") {
-                const fn = this.target["dispatchEvent"];
-                if (typeof fn === "function") {
-                    const evt = new EventListEvent(this.key);
-                    evt.args = args;
-                    fn.call(this.target, evt);
-                }
-            }
         }
         finally {
             this._isInvoking = false;
@@ -313,12 +241,32 @@ export class EventList<TArgs extends any = any> implements IEventList {
 
     /** Add a new event listener to this event
      * @returns a function to remove the event listener
+     * @see {@link removeEventListener} for more details and return value information
+     * @see {@link off} for an alias with better readability when unsubscribing from events
+     * @example
+     * ```ts
+     * const off = myEvent.addEventListener(args => console.log("Clicked!", args));
+     * // later
+     * off();
+     * ```
      */
     addEventListener(callback: (args: TArgs) => void): Function {
         this.methods.push(new CallInfo(callback));
         return () => this.removeEventListener(callback);
     }
 
+    /**
+     * Alias for addEventListener for better readability when subscribing to events. You can use it like this:
+     * ```ts
+     * myEvent.on(args => console.log("Clicked!", args));
+     * ```
+      * @returns a function to remove the event listener
+      * @see {@link addEventListener} for more details and return value information
+     */
+    on(callback: (args: TArgs) => void): Function {
+        return this.addEventListener(callback);
+    }
+
     /**
      * Remove an event listener from this event.
      * @returns true if the event listener was found and removed, false otherwise
@@ -336,6 +284,20 @@ export class EventList<TArgs extends any = any> implements IEventList {
         return found;
     }
 
+    /**
+     * Alias for removeEventListener for better readability when unsubscribing from events. You can use it like this:
+     * ```ts
+     * const off = myEvent.on(args => console.log("Clicked!", args));
+     * // later
+     * off();
+     * ```
+     * 
+     * @see {@link removeEventListener} for more details and return value information
+     */
+    off(callback: Function | null | undefined) {
+        return this.removeEventListener(callback);
+    }
+
     /**
      * Remove all event listeners from this event. Use with caution! This will remove all listeners!
      */

package/src/engine-components/Joints.ts

@@ -28,6 +28,7 @@ export abstract class Joint extends Behaviour {
         return this._rigidBody;
     }
     private _rigidBody: Rigidbody | null = null;
+    private _jointHandle: any = null;
 
 
     onEnable() {
@@ -36,14 +37,28 @@ export abstract class Joint extends Behaviour {
             this.startCoroutine(this.create());
     }
 
+    onDisable() {
+        if (this._jointHandle) {
+            this.context.physics.engine?.removeJoint(this._jointHandle);
+            this._jointHandle = null;
+        }
+    }
+
     private *create() {
         yield;
+        if (this._jointHandle) return;
         if (this.rigidBody && this.connectedBody && this.activeAndEnabled) {
-            this.createJoint(this.rigidBody, this.connectedBody)
+            const result = this.createJoint(this.rigidBody, this.connectedBody);
+            if (result instanceof Promise) {
+                yield result.then(handle => this._jointHandle = handle);
+            }
+            else {
+                this._jointHandle = result;
+            }
         }
     }
 
-    protected abstract createJoint(self: Rigidbody, other: Rigidbody);
+    protected abstract createJoint(self: Rigidbody, other: Rigidbody): any;
 }
 
 /**
@@ -70,7 +85,7 @@ export abstract class Joint extends Behaviour {
 export class FixedJoint extends Joint {
 
     protected createJoint(self: Rigidbody, other: Rigidbody) {
-        this.context.physics.engine?.addFixedJoint(self, other);
+        return this.context.physics.engine?.addFixedJoint(self, other) ?? null;
     }
 }
 
@@ -110,7 +125,8 @@ export class HingeJoint extends Joint {
 
     protected createJoint(self: Rigidbody, other: Rigidbody) {
         if (this.axis && this.anchor)
-            this.context.physics.engine?.addHingeJoint(self, other, this.anchor, this.axis);
+            return this.context.physics.engine?.addHingeJoint(self, other, this.anchor, this.axis) ?? null;
+        return null;
     }
 
 }

package/src/engine-components/Light.ts

@@ -1,12 +1,12 @@
 import { CameraHelper, Color, DirectionalLight, DirectionalLightHelper, Light as ThreeLight, OrthographicCamera, PointLight, SpotLight, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { FrameEvent } from "../engine/engine_setup.js";
 import { setWorldPositionXYZ } from "../engine/engine_three_utils.js";
 import type { ILight } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js";
 import type { NeedleXREventArgs } from "../engine/xr/api.js";
 import { Behaviour, GameObject } from "./Component.js";
+import { isDevEnvironment } from "../engine/debug/index.js";
 
 // https://threejs.org/examples/webgl_shadowmap_csm.html
 
@@ -135,7 +135,10 @@ export class Light extends Behaviour implements ILight {
                 this._type = value;
                 break;
             default:
-                throw new Error("Invalid light type: " + value);
+                if (debug || isDevEnvironment())
+                    console.warn(`[Light] Unsupported light type: ${LightType[value]} (${value}) on '${this.name}'`);
+                this._type = "unsupported" as any;
+                break;
         }
     }
     private _type: ILight["type"] = "point";
@@ -474,6 +477,11 @@ export class Light extends Behaviour implements ILight {
                     // const pointHelper = new PointLightHelper(pointLight, this.range, this.color);
                     // scene.add(pointHelper);
                     break;
+
+                default:
+                    if (debug) console.warn(`[Light] Unsupported light type: ${LightType[this.type as any]} (${this.type}) on '${this.name}'`);
+                    break;
+
             }
         }
 

package/src/engine-components/OrbitControls.ts

@@ -663,7 +663,15 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
         this._controls.enabled = true;
 
-        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || (this.context.input.getPointerPressed(0) && this.context.input.getPointerPositionDelta(0)?.length() || 0 > .1)) {
+        // Interrupt programmatic transitions on meaningful new user interaction:
+        // - Middle/right button down (always intentional camera control)
+        // - Mouse wheel (zoom intent)
+        // - Left button drag start: getPointerDown(0) with a position delta — a bare click
+        //   without movement shouldn't cancel an animation, but starting to drag should.
+        //   Using getPointerDown (not getPointerPressed) ensures we only interrupt once at
+        //   drag onset, not continuously every frame during a drag.
+        const leftDragStart = this.context.input.getPointerDown(0) && (this.context.input.getPointerPositionDelta(0)?.length() || 0) > .1;
+        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || leftDragStart) {
             this._inputs += 1;
         }
         if (this._inputs > 0 && this.allowInterrupt) {
@@ -1095,13 +1103,16 @@ export class OrbitControls extends Behaviour implements ICameraController {
     // Adapted from https://discourse.threejs.org/t/camera-zoom-to-fit-object/936/24
     // Slower but better implementation that takes bones and exact vertex positions into account: https://github.com/google/model-viewer/blob/04e900c5027de8c5306fe1fe9627707f42811b05/packages/model-viewer/src/three-components/ModelScene.ts#L321
 
-    /** 
-     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
+    /**
+     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
      * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
     */
     fitCamera(options?: OrbitFitCameraOptions);
-    /** @deprecated Use fitCamera(options) */
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
+    // Deprecated overload commented out: it accepted Object3D as first arg, which caused
+    // TypeScript autocomplete to show Object3D properties (position, worldPosition, etc.)
+    // instead of OrbitFitCameraOptions. The implementation still handles Object3D at runtime
+    // for backwards-compat — use fitCamera({ objects: [...] }) instead.
+    // fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
     fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | OrbitFitCameraOptions, options?: OrbitFitCameraOptions): void {